Skip to main content

Places

note

This guide is focused on the Overture places data — its content, scope, properties, and use cases. Please see the schema reference documentation for more information on the Overture places schema.

Overview​

The Overture places theme has one feature type, called place, and contains more than 53 million point representations of real-world entities: schools, businesses, hospitals, religious organizations, landmarks, mountain peaks, and much more. The theme is derived from a conflation of Meta and Microsoft data and is available under a CDLA Permissive 2.0 license.

Overture places theme coverage
Overture places data, styled by data source: purple for Meta, orange for Microsoft.
Primary sourceFeature count, July 2024 release
Meta~48 million
Microsoft~5.5 million

Dataset description​

All Overture data, including places data, is distributed as GeoParquet, a column-based data structure. Below you'll find a table with column-by-column descriptions of the properties in the place feature type. Of particular interest to users is the categories property; we offer a complete list of available categories here.

Schema for GeoParquet files in the places theme
columntypedescription
idVARCHARA feature ID. This may be an ID associated with the Global Entity Reference System (GERS) if—and-only-if the feature represents an entity that is part of GERS.
geometryBLOBThe point representation of the Place's location. Place's geometry which MUST be a Point as defined by GeoJSON schema.
bboxSTRUCTArea defined by two longitudes and two latitudes: latitude is a decimal number between -90.0 and 90.0; longitude is a decimal number between -180.0 and 180.0.
versionINTEGERVersion number of the feature, incremented in each Overture release where the geometry or attributes of this feature changed.
sourcesSTRUCTThe array of source information for the properties of a given feature, with each entry being a source object which lists the property in JSON Pointer notation and the dataset that specific value came from. All features must have a root level source which is the default source if a specific property's source is not specified.
namesSTRUCTProperties defining the names of a feature.
categoriesSTRUCTThe categories of the place. Complete list is available on GitHub: https://github.com/OvertureMaps/schema/blob/main/task-force-docs/places/overture_categories.csv
confidenceDOUBLEThe confidence of the existence of the place. It's a number between 0 and 1. 0 means that we're sure that the place doesn't exist (anymore). 1 means that we're sure that the place exists. If there's no value for the confidence, it means that we don't have any confidence information.
websitesVARCHAR[]The websites of the place.
socialsVARCHAR[]The social media URLs of the place.
emailsVARCHAR[]The email addresses of the place.
phonesVARCHAR[]The phone numbers of the place.
brandSTRUCTThe brand of the place. A location with multiple brands is modeled as multiple separate places, each with its own brand.
addressesSTRUCTThe addresses of the place.

Data access and retrieval​

The latest places data can be obtained from AWS or Azure as GeoParquet files at the following locations.

ProviderLocation
Amazon S3
s3://overturemaps-us-west-2/release/2024-07-22.0/theme=places/type=place/
Azure Blob Storage
https://overturemapswestus2.blob.core.windows.net/release/2024-07-22.0/theme=places/type=place/

More information can be found in the Getting Overture Data section of this documentation. You can download the entire dataset directly from the S3 or Azure locations above. Warning: the output will be a very large file. Depending on your use case, these methods might be more practical for you:

First, follow the setup guide for the Python Command-line Tool.

overturemaps download -f geoparquet --type=place -o places.geoparquet

Data usage guidelines​

We recommend downloading only the Overture data you need. If you have a particular geographic area of interest, there are several options for using a simple bounding box to extract places data and output a GeoJSON file.

To quickly view and download modest amounts of data, you can use the Overture Maps Explorer website.

To download data: Pan to the area you are interested in, turn off the other layers, then click Download Visible.

This will download the area visible on your screen.

Data manipulation and analysis​

Querying by properties​

These examples use data properties in the address, category, and confidence scores columns to filter the data in useful ways using DuckDB.

The address column can be used to quickly filter data down to a particular political unit. This example uses the country key to get all the data with addresses in Lithuania. Region can be likewise used to extract data from smaller units such as US states.

LOAD spatial;
LOAD httpfs;
-- Access the data on AWS in this example
SET s3_region='us-west-2';

COPY (
    SELECT
-- we can parse addresses into columns to make further filtering of the data simpler
    addresses[1].freeform as street,
    addresses[1].locality as locality,
    addresses[1].postcode as postcode,
    addresses[1].region as region,
    addresses[1].country as country,
    *
FROM read_parquet('s3://overturemaps-us-west-2/release/2024-07-22.0/theme=places/*/*')
WHERE
    addresses[1].country = 'LT'
) TO 'lithuania_places.parquet';

Advanced examples​

These examples present some use cases that combine places data with other datasets.

Overture Places can be a valuable source for conflating with or enhancing your own existing dataset.

In this example, suppose we want to use OpenStreetMap POIs for a project but would like to fill in any missing attributes such as addresses or phone numbers with Overture Place data.

Using some basic matching logic, we can join these two datasets together to create a more robust final product. By also joining the GERS ID to our output dataset we could easily keep our now conflated dataset synced with future Overture releases with a simple join.

To run this example yourself, an Oregon PBF can be obtained from Geofabrik.

Note: Joining data with a CDLA Permissive 2.0 license to OSM is permitted but the resulting data may need to carry the Open Database License (ODbL) if it is a derivative database. Please see the OSM Collective Database Guideline for information on this topic.

Query
LOAD spatial;
LOAD httpfs;
-- Access the data on AWS in this example
SET s3_region='us-west-2';

COPY (
-- We'll first select OSM data from Oregon with amenity = restaurant
    WITH osm AS (
        SELECT kind,
            id,
            tags->>'name' AS name,
            tags->>'addr:housenumber' AS housenumber,
            tags->>'addr:street' AS street,
            tags->>'addr:postcode' AS postcode,
            tags->>'addr:city' AS city,
            tags->>'website' AS website,
            tags->>'phone' AS phone,
            lat,
            lon,
            tags
        FROM st_readosm(
                'oregon-latest.osm.pbf'
            )
        WHERE tags->>'amenity' = 'restaurant'
    ),
-- Then select Overture data with any category containing the word restauarant in Oregon.
    overture AS (
        SELECT id,
            names.primary AS "names.primary",
            websites[1] AS website,
            socials[1] AS social,
            emails[1] AS email,
            phones[1] AS phone,
            addresses[1].freeform AS freeform,
            addresses[1].locality AS locality,
            addresses[1].postcode AS postcode,
            addresses[1].region AS region,
            addresses[1].country AS country,
            ST_GeomFromWKB(geometry) AS geometry
        FROM read_parquet('s3://overturemaps-us-west-2/release/2024-07-22.0/theme=places/*/*')
        WHERE region = 'OR'
            AND country = 'US'
            AND categories.primary ilike '%restaurant%'
    )
-- Now that we have our input data we will join them together.
    SELECT
        -- With the GERS id joined to the final result this dataset can be quickly synced to future Overture releases
        overture.id AS GERS_id,
        osm.name,
        -- Using CASE statements, we'll favor OSM data when it is present but use Overture data wherever there are gaps
        CASE
            WHEN osm.housenumber IS NOT NULL
            OR osm.street IS NOT NULL THEN concat(osm.housenumber, ' ', osm.street)
            ELSE overture.freeform
        END AS address,
        CASE
            WHEN osm.city IS NOT NULL THEN osm.city
            ELSE overture.locality
        END AS city,
        CASE
            WHEN osm.postcode IS NOT NULL THEN osm.postcode
            ELSE overture.postcode
        END AS postcode,
        CASE
            WHEN osm.website IS NOT NULL THEN osm.website
            ELSE overture.website
        END AS website,
        CASE
            WHEN osm.phone IS NOT NULL THEN osm.phone
            ELSE overture.phone
        END AS phone,
        overture.social,
        overture.email,
        ST_AsWKB(st_point(osm.lon, osm.lat)) AS geometry
    FROM osm
-- To join the data, we'll first match features that have the same OR similar names 
        LEFT JOIN overture ON (
            osm.name = overture."names.primary"
            OR osm.name ilike concat('%', overture."names.primary", '%')
            OR overture."names.primary" ilike concat('%', osm.name, '%')
            OR damerau_levenshtein(osm.name, overture."names.primary") < 3
        )
-- Then use a small buffer to match features that are nearby to each other
        AND st_intersects(
            st_buffer(overture.geometry::geometry, 0.003),
            st_point(osm.lon, osm.lat)
        )
) TO 'oregon_restaurants_combined.parquet';

Tools and libraries​

Rapid​

Rapid, an OpenStreetMap editor, is capable of displaying places data as a reference layer by following the guide here.

The license is compatible with OSM and this data can be used for mapping.

Last updated on