User Reference#
Below you can find the reference for the package modules, as well as some additional information for using them.
Dataset Information#
Dataset Schemas and Additional Information#
Schemas can be retrieved from either dataset by using get_schema
Additional schema and dataset information can be found below.
Formatting parameters#
Filtering and Accessing Dictionary Columns#
The filter structure is based off of DuckDB comparision functionality which can be found here. This is only the raw SQL, no need to insert “WHERE.” Anything that can be in the “WHERE” statement can go into this filter
Certain columns within the datasets will be a dictionary, most notably, the Overture Places column “categories.”
This column is set up as a dictionary: {"primary":"<category>","secondary":["<category2>","<category3>",...]}
In order to filter by the dictionary values, use a “.” in your filter. More information on that here.
Finding Categories#
Finding categories for a place can be challenging because of the accessibility of the category names and codes.(which can be found below)
The find_categories function for each dataset can help. You can enter in a search query(e.g., finding hardware stores by searching “hardware store”).
It uses exact and semantic matching to find relevant categories to the search. The quality of the results depend on the detail of your search.
Versions#
Each dataset is continuously updated with new information. One of the goals of pyplaces is to be able to reference historic editions of all the datasets supported.
Overture Maps Releases#
Release Date |
Unsupported Themes |
|---|---|
2025-07-23.0 |
X |
2025-06-25.0 |
X |
2025-05-21.0 |
X |
2025-04-23.0 |
X |
2025-03-19.1 |
X |
2025-02-19.0 |
X |
2025-01-22.0 |
X |
2024-12-18.0 |
X |
2024-11-13.0 |
X |
2024-10-23.0 |
X |
2024-09-18.0 |
X |
2024-08-20.0 |
X |
2024-07-22.0 |
X |
2024-06-13-beta.1 |
addresses |
2024-05-16-beta.0 |
addresses |
2024-04-16-beta.0 |
addresses |
2024-03-12-alpha.0 |
addresses |
2024-02-15-alpha.0 |
addresses |
2024-01-17-alpha.0 |
addresses |
2023-12-14-alpha.0 |
addresses |
2023-11-14-alpha.0 |
addresses |
2023-10-19-alpha.0 |
addresses |
2023-07-26-alpha.0 |
base, addresses |
Foursquare Open Places Releases#
Release Date |
|---|
2025-07-08 |
2025-06-10 |
2025-05-09 |
2025-04-08 |
2025-03-06 |
2025-02-06 |
2025-01-10 |
2024-12-03 |
2024-11-19 |
Modules#
pyplaces.overture_maps#
Functions to fetch geoparquet data from Overture Maps on AWS
- pyplaces.overture_maps.find_categories(search, num_results=5, exact_match=False, verbose=False, as_df=False)#
Finds Overture Places categories based on a user search.
- Return type:
Union[list[str],DataFrame]
Parameters#
- searchstr
User search term for matching.
- num_resultsint, optional. Defaults to 5
Number of matched categories to retrieve.
- exact_matchbool, optional. Defaults to False.
Whether to retrieve only exact matches from search.
- verbosebool, optional. Defaults to False.
Whether to show the additional information of the matches
- as_dfbool, optional. Defaults to False.
Whether to retrieve the matches as a DataFrame with additional information.
Returns#
- Union[list[str],Dataframe]
Matched Overture Category names as a list of strings or DataFrame.
- pyplaces.overture_maps.get_schema(dataset_name, connector=False, building_part=False, base_type=None, release='2025-10-22.0')#
Get DuckDB schema for the given dataset.
- Return type:
DataFrame
Parameters#
- dataset_namestr
Name of the dataset to get the schema of, must be one of “buildings”,”transportation”,”base”,”places”,”addresses”
- connectorbool, optional
Whether to retrieve connector schema. Defaults to False.
- building_partbool, optional
Whether to retrieve building_part schema. Defaults to False.
- base_typestr, optional
Which base type schema to retrive.
- releasestr, optional
Release version to use, defaults to the latest version.
Returns#
- DataFrame
DataFrame with columns showing DuckDB types
- pyplaces.overture_maps.overture_addresses_from_address(address, columns=None, filters=None, distance=500, unit='m', release='2025-10-22.0')#
Retrieve address data from Overture in a bounding box around a specified address.
- Return type:
GeoDataFrame
Parameters#
- addressstr | tuple[float,float]
The address or (longitude, latitude) tuple to search for nearby places.
- columnslist[str] | None, optional
Specific columns to include in the result.
- filtersstr | None, optional
DuckDB SQL expression
- distancefloat, optional
Radius of the bounding box around the address. Defaults to 500 meters.
- unitstr, optional
Unit of measurement for the distance. Defaults to “m” (meters). One of: “m”,”km”,”in”,”ft”,”yd”,”mi”
- releasestr, optional
Dataset release version to use. Defaults to the latest version.
Returns#
- GeoDataFrame
A GeoDataFrame containing address data within the specified bounding box of the address
- pyplaces.overture_maps.overture_addresses_from_bbox(bbox, columns=None, filters=None, release='2025-10-22.0')#
Retrieve address data from Overture within a bounding box.
- Return type:
GeoDataFrame
Parameters#
- bboxtuple[float, float, float, float]
The bounding box coordinates (min_x, min_y, max_x, max_y)
- columnslist[str] | None, optional
Specific columns to include in the result.
- filtersstr | None, optional
DuckDB SQL expression
- releasestr, optional
Dataset release version to use. Defaults to the latest version.
Returns#
- GeoDataFrame
A GeoDataFrame containing address data within the specified bounding box
- pyplaces.overture_maps.overture_addresses_from_place(address, columns=None, filters=None, release='2025-10-22.0')#
Retrieve address data from Overture by its address or place name.
- Return type:
GeoDataFrame
Parameters#
- addressstr
The place name to search within
- columnslist[str] | None, optional
Specific columns to include in the result.
- filtersstr | None, optional
DuckDB SQL expression
- releasestr, optional
Dataset release version to use. Defaults to the latest version.
Returns#
- GeoDataFrame
A GeoDataFrame containing address data within the specified place
- pyplaces.overture_maps.overture_base_from_address(address, base_type, columns=None, filters=None, distance=500, unit='m', release='2025-10-22.0')#
Retrieve base data of a specific type from Overture in a bounding box around a specified address.
- Return type:
GeoDataFrame
Parameters#
- addressstr | tuple[float,float]
The address or (longitude, latitude) tuple to search for nearby places.
- base_typestr
The type of base data to retrieve. One of: “bathymetry”,”infrastructure”,”land”,”land_cover”,land_use”,”water”.
- columnslist[str] | None, optional
Specific columns to include in the result.
- filtersstr | None, optional
DuckDB SQL expression
- distancefloat, optional
Radius of the bounding box around the address. Defaults to 500 meters.
- unitstr, optional
Unit of measurement for the distance. Defaults to “m” (meters). One of: “m”,”km”,”in”,”ft”,”yd”,”mi”
- releasestr, optional
Dataset release version to use. Defaults to the latest version.
Returns#
- GeoDataFrame
A GeoDataFrame containing base data of the specified type within the specified bounding box of the address.
- pyplaces.overture_maps.overture_base_from_bbox(bbox, base_type, columns=None, filters=None, release='2025-10-22.0')#
Retrieve base data of a specific type from Overture within a bounding box.
- Return type:
GeoDataFrame
Parameters#
- bboxtuple[float, float, float, float]
The bounding box coordinates (min_x, min_y, max_x, max_y)
- base_typestr
The type of base data to retrieve. One of: “bathymetry”,”infrastructure”,”land”,”land_cover”,land_use”,”water”
- columnslist[str] | None, optional
Specific columns to include in the result.
- filtersstr | None, optional
DuckDB SQL expression
- releasestr, optional
Dataset release version to use. Defaults to the latest version.
Returns#
- GeoDataFrame
A GeoDataFrame containing base data of the specified type within the bounding box
- pyplaces.overture_maps.overture_base_from_place(address, base_type, columns=None, filters=None, release='2025-10-22.0')#
Retrieve base data of a specific type from Overture by its address or place name.
- Return type:
GeoDataFrame
Parameters#
- addressstr
The place name to search within
- base_typestr
The type of base data to retrieve. One of: “bathymetry”,”infrastructure”,”land”,”land_cover”,land_use”,”water”
- columnslist[str] | None, optional
Specific columns to include in the result.
- filtersstr | None, optional
DuckDB SQL expression
- releasestr, optional
Dataset release version to use. Defaults to the latest version.
Returns#
- GeoDataFrame
A GeoDataFrame containing base data of the specified type within the place
- pyplaces.overture_maps.overture_buildings_from_address(address, columns=None, filters=None, distance=500, unit='m', release='2025-10-22.0', building_part=False)#
Retrieve buildings data from Overture in a bounding box around a specified address.
- Return type:
GeoDataFrame
Parameters#
- addressstr | tuple[float,float]
The address or (longitude, latitude) tuple to search for nearby places.
- columnslist[str] | None, optional
Specific columns to include in the result.
- filtersstr | None, optional
DuckDB SQL expression
- distancefloat, optional
Radius of the bounding box around the address. Defaults to 500 meters.
- unitstr, optional
Unit of measurement for the distance. Defaults to “m” (meters). One of: “m”,”km”,”in”,”ft”,”yd”,”mi”
- releasestr, optional
Dataset release version to use. Defaults to the latest version.
- building_partbool, optional
Whether to retrieve building parts instead of whole buildings, by default False
Returns#
- GeoDataFrame
A GeoDataFrame containing buildings data within the specified bounding box of the address
- pyplaces.overture_maps.overture_buildings_from_bbox(bbox, columns=None, filters=None, release='2025-10-22.0', building_part=False)#
Retrieve buildings data from Overture within a bounding box.
- Return type:
GeoDataFrame
Parameters#
- bboxtuple[float, float, float, float]
The bounding box coordinates (min_x, min_y, max_x, max_y)
- columnslist[str] | None, optional
Specific columns to include in the result.
- filtersstr | None, optional
DuckDB SQL expression
- releasestr, optional
Dataset release version to use. Defaults to the latest version.
- building_partbool, optional
Whether to retrieve building parts instead of whole buildings, by default False
Returns#
- GeoDataFrame
A GeoDataFrame containing buildings data within the specified bounding box
- pyplaces.overture_maps.overture_buildings_from_place(address, columns=None, filters=None, release='2025-10-22.0', building_part=False)#
Retrieve buildings data from Overture by its address or place name.
- Return type:
GeoDataFrame
Parameters#
- addressstr
The place name to search within
- columnslist[str] | None, optional
Specific columns to include in the result.
- filtersstr | None, optional
DuckDB SQL expression
- releasestr, optional
Dataset release version to use. Defaults to the latest version.
- building_partbool, optional
Whether to retrieve building parts instead of whole buildings, by default False
Returns#
- GeoDataFrame
A GeoDataFrame containing buildings data within the specified place
- pyplaces.overture_maps.overture_places_from_address(address, columns=None, filters=None, distance=500, unit='m', release='2025-10-22.0')#
Retrieve places data from Overture in a bounding box around a specified address.
- Return type:
GeoDataFrame
Parameters#
- addressstr | tuple[float,float]
The address or (longitude, latitude) tuple to search for nearby places.
- columnslist[str] | None, optional
Specific columns to include in the result.
- filtersstr | None, optional
DuckDB SQL expression
- distancefloat, optional
Radius of the bounding box around the address. Defaults to 500 meters.
- unitstr, optional
Unit of measurement for the distance. Defaults to “m” (meters). One of: “m”,”km”,”in”,”ft”,”yd”,”mi”
- releasestr, optional
Dataset release version to use. Defaults to the latest version.
Returns#
- GeoDataFrame
A GeoDataFrame containing places data within the specified bounding box of the address
- pyplaces.overture_maps.overture_places_from_bbox(bbox, columns=None, filters=None, release='2025-10-22.0')#
Retrieve places data from Overture within a bounding box.
- Return type:
GeoDataFrame
Parameters#
- bboxtuple[float, float, float, float]
The bounding box coordinates (min_x, min_y, max_x, max_y)
- columnslist[str] | None, optional
Specific columns to include in the result.
- filtersstr | None, optional
DuckDB SQL expression
- releasestr, optional
Dataset release version to use. Defaults to the latest version.
Returns#
- GeoDataFrame
A GeoDataFrame containing places data within the specified bounding box
- pyplaces.overture_maps.overture_places_from_place(address, columns=None, filters=None, release='2025-10-22.0')#
Retrieve places data from Overture by its address or place name.
- Return type:
GeoDataFrame
Parameters#
- addressstr
The place name to search within
- columnslist[str] | None, optional
Specific columns to include in the result.
- filtersstr | None, optional
DuckDB SQL expression
- releasestr, optional
Dataset release version to use. Defaults to the latest version.
Returns#
- GeoDataFrame
A GeoDataFrame containing places data within the specified place
- pyplaces.overture_maps.overture_transportation_from_address(address, columns=None, filters=None, distance=500, unit='m', release='2025-10-22.0', connector=False)#
Retrieve transportation data from Overture in a bounding box around a specified address.
- Return type:
GeoDataFrame
Parameters#
- addressstr | tuple[float,float]
The address or (longitude, latitude) tuple to search for nearby places.
- columnslist[str] | None, optional
Specific columns to include in the result.
- filtersstr | None, optional
DuckDB SQL expression
- distancefloat, optional
Radius of the bounding box around the address. Defaults to 500 meters.
- unitstr, optional
Unit of measurement for the distance. Defaults to “m” (meters). One of: “m”,”km”,”in”,”ft”,”yd”,”mi”
- releasestr, optional
Dataset release version to use. Defaults to the latest version.
- connectorbool, optional
Whether to retrieve connectors instead of segments, by default False
Returns#
- GeoDataFrame
A GeoDataFrame containing transportation data within the specified bounding box of the address
- pyplaces.overture_maps.overture_transportation_from_bbox(bbox, columns=None, filters=None, release='2025-10-22.0', connector=False)#
Retrieve transportation data from Overture within a bounding box.
- Return type:
GeoDataFrame
Parameters#
- bboxtuple[float, float, float, float]
The bounding box coordinates (min_x, min_y, max_x, max_y)
- columnslist[str] | None, optional
Specific columns to include in the result.
- filtersstr | None, optional
DuckDB SQL expression
- releasestr, optional
Dataset release version to use. Defaults to the latest version.
- connectorbool, optional
Whether to retrieve connectors instead of segments, by default False
Returns#
- GeoDataFrame
A GeoDataFrame containing transportation data within the specified bounding box
- pyplaces.overture_maps.overture_transportation_from_place(address, columns=None, filters=None, release='2025-10-22.0', connector=False)#
Retrieve transportation data from Overture by its address or place name.
- Return type:
GeoDataFrame
Parameters#
- addressstr
The place name to search within
- columnslist[str] | None, optional
Specific columns to include in the result.
- filtersstr | None, optional
DuckDB SQL expression
- releasestr, optional
Dataset release version to use. Defaults to the latest version.
- connectorbool, optional
Whether to retrieve connectors instead of segments, by default False
Returns#
- GeoDataFrame
A GeoDataFrame containing transportation data within the specified place
pyplaces.foursquare_open_places#
Functions to fetch geoparquet data from Foursquare Open Places on AWS
- pyplaces.foursquare_open_places.find_categories(search, num_results=5, exact_match=False, verbose=False, as_df=False)#
Finds Foursquare Open Places categories based on a user search.
- Return type:
Union[list[str],DataFrame]
Parameters#
- searchstr
User search term for matching.
- num_resultsint, optional. Defaults to 5
Number of matched categories to retrieve.
- exact_matchbool, optional. Defaults to False.
Whether to retrieve only exact matches from search.
- verbosebool, optional. Defaults to False.
Whether to show the additional information of the matches
- as_dfbool, optional. Defaults to False.
Whether to retrieve the matches as a DataFrame with additional information.
Returns#
- Union[list[str],Dataframe]
Matched Foursquare Category IDs as a list of strings or DataFrame.
- pyplaces.foursquare_open_places.foursquare_places_from_address(address, columns=None, filters=None, distance=500, unit='m', release='2025-09-09')#
Retrieves Foursquare places data in a bounding box around a specified address.
- Return type:
GeoDataFrame
Parameters#
- addressstr | tuple[float,float]
The addres or (longitude, latitude) tuple to search for nearby places.
- columnslist[str] | None, optional
Specific columns to retrieve from the dataset.
- filtersstr | None, optional
DuckDB SQL expression
- distancefloat, default 500
Radius of the bounding box around the address. Defaults to 500 meters.
- unitstr, default “m”
Unit of measurement for the distance. Defaults to “m” (meters). One of: “m”,”km”,”in”,”ft”,”yd”,”mi”
- releasestr, default FSQ_LATEST_RELEASE
Dataset release version to use. Defaults to the latest version.
Returns#
- GeoDataFrame
A GeoDataFrame containing Foursquare places data within the specified bounding box of the address.
- pyplaces.foursquare_open_places.foursquare_places_from_bbox(bbox, columns=None, filters=None, release='2025-09-09')#
Retrieves Foursquare places data within a specified bounding box.
- Return type:
GeoDataFrame
Parameters#
- bboxtuple[float, float, float, float]
Bounding box coordinates in the format (min_x, min_y, max_x, max_y).
- columnslist[str] | None, optional
Specific columns to retrieve from the dataset.
- filtersstr | None, optional
DuckDB SQL expression
- releasestr, default FSQ_LATEST_RELEASE
Dataset release version to use. Defaults to the latest version.
Returns#
- GeoDataFrame
A GeoDataFrame containing Foursquare places data within the specified bounding box.
- pyplaces.foursquare_open_places.foursquare_places_from_place(address, columns=None, filters=None, release='2025-09-09')#
Retrieves Foursquare places data for a specific place identified by its address or place name.
- Return type:
GeoDataFrame
Parameters#
- addressstr
The address or identifier of the place to retrieve data for.
- columnslist[str] | None, optional
Specific columns to retrieve from the dataset.
- filtersstr | None, optional
DuckDB SQL expression
- releasestr, default FSQ_LATEST_RELEASE
Dataset release version to use. Defaults to the latest version.
Returns#
- GeoDataFrame
A GeoDataFrame containing Foursquare places data within specified place.
- pyplaces.foursquare_open_places.get_categories(columns=None, filters=None, release='2025-09-09')#
Retrieves Foursquare place categories data.
- Return type:
DataFrame
Parameters#
- columnslist[str] | None, optional
Specific columns to retrieve from the dataset.
- filtersstr | None, optional
DuckDB SQL expression
- releasestr, default FSQ_LATEST_RELEASE
Dataset release version to use. Defaults to the latest version.
Returns#
- DataFrame
A DataFrame containing Foursquare place categories data.
Notes#
This function constructs the data path using Foursquare-specific constants and retrieves the categories data using read_parquet_duckdb.
- pyplaces.foursquare_open_places.get_schema(categories=False, release='2025-09-09')#
Get DuckDB schema for the given dataset. Set categories to True if you want to get the categories instead of the places schema.
- Return type:
DataFrame
Parameters#
- connectorbool, optional
Whether to get categories schema, by default False.
- releasestr, optional
Release version to use, defaults to the latest version.
Returns#
- DataFrame
DataFrame with columns showing DuckDB types