Skip to main content

Using the GERS "system"

· 7 min read

In the June release, we introduced new components of GERS, including a new format for GERS IDs and a GERS Registry. In this blog post, we'll walk you through the GERS "system" and show you how to ask probing questions of the Overture datasets.

Understanding GERS IDs​

First, let's look at the new ID format for GERS. As of the June 2025 release, all GERS IDs are UUIDs: 128-bit, randomly-generated identifiers (UUID v4) that Overture keeps stable across data releases and updates. These IDs are stored as strings with dashes: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.

For this release only, we're providing Parquet files that map GERS IDs from the May release to the new GERS UUIDs in June release. These files are partitioned by theme and 'type' and can be accessed here: s3://overturemaps-extras-us-west-2/june_to_may_id_mapping/.

Exploring Overture data with GERS​

Let's start our exploration by examining how GERS IDs work in one Overture dataset. The divisions theme contains administrative boundaries and points for global administrative areas. In this example, we'll use DuckDB to connect to Azure and read the Parquet files from Azure blob storage. You can also access the files on Amazon S3.

CREATE TABLE slc AS (
    SELECT
        *
    FROM
        read_parquet('az://overturemapswestus2.blob.core.windows.net/release/2025-06-25.0/theme=divisions/type=division/*')
    WHERE
    -- ID for Salt Lake City, Utah
        id = 'c85948de-26de-4c4a-8479-1dac33fa8b04'
);

When we query that table, we can see the divisions hierarchy: Salt Lake City is a locality in Salt Lake County, which is in the region of Utah, within the country of the United States.

SELECT
    h.name,
    h.subtype,
    h.division_id
FROM
    slc
CROSS JOIN UNNEST(hierarchies[1]) AS t(h);
┌──────────────────┬──────────┬──────────────────────────────────────┐
│       name       │ subtype  │             division_id              │
│     varchar      │ varchar  │               varchar                │
├──────────────────┼──────────┼──────────────────────────────────────┤
│ United States    │ country  │ f39eb4af-5206-481b-b19e-bd784ded3f05 │
│ Utah             │ region   │ 506017c0-8932-44b5-b82c-92f9dcffdcf1 │
│ Salt Lake County │ county   │ 53d671bc-c294-44fb-a767-169bffedc5cb │
│ Salt Lake City   │ locality │ c85948de-26de-4c4a-8479-1dac33fa8b04 │
└──────────────────┴──────────┴──────────────────────────────────────┘

To retrieve the actual polygons for these entities, we can query the division_area type of the divisions theme, using division_id as the foreign key that links the datasets. Note: This query will take a few minutes to run.

COPY(
    SELECT
        names.primary AS name,
        subtype,
        id,
        geometry
    FROM
        read_parquet('az://overturemapswestus2.blob.core.windows.net/release/2025-06-25.0/theme=divisions/type=division_area/*') areas
    WHERE
        division_id IN (
            SELECT
                h.division_id
            FROM
                slc
            CROSS JOIN UNNEST(hierarchies[1]) AS t(h)
            )
    ) TO 'slc_hierarchies.geojson' WITH (FORMAT GDAL, DRIVER GeoJSON);

Next we'll load slc_hierarchies.geojson into KeplerGL so that we can see the complete hierarchy of divisions.

Salt lake City Hierarchies

info

GERS IDs are intended to be the key to unlock interoperability both inside and outside of Overture data. This example showed how Overture features within the same theme can reference one-another via GERS.

Looking up IDs in the GERS Registry​

Let's grab a GERS ID for an important place in Salt Lake City and see if it exists in the GERS Registry. The UUID for the Utah State Capitol is d724e74f-017a-4902-9031-bc784ffc1789. Is that part of GERS? We can search the GERS Registry with this query:

SELECT 
    *
FROM 
    read_parquet('s3://overturemaps-us-west-2/registry/*')   
WHERE 
    id='d724e74f-017a-4902-9031-bc784ffc1789';

We can see that d724e74f-017a-4902-9031-bc784ffc1789 is a place type that was first seen by the GERS Registry in the 2025-06-25.0 release. (This makes sense because the GERS Registry didn't exist to see any features before then!) It has a bbox of {'xmin': -111.888214, 'xmax': -111.8882, 'ymin': 40.777214, 'ymax': 40.77722} and it lives in this Parquet file: /theme=places/type=place/part-00001-f6d803dd-3ff7-47d7-a58f-7af6e054e9c4-c000.zstd.parquet.

Using the data changelog​

note

For the next part of this tutorial, we're using the data changelog from the May release (2025-05-21.0) to examine new places in Salt Lake City. Because of the switch to UUIDs in June, we did not generate a changelog in June. The next changelog will be published with the July release.

Every Overture release (except the June 2025 release) includes a changelog with a high-level overview of data added, removed, or changed, based on the ID. The changelog is partitioned by theme, type, and change_type. Let's query the changelog to identify all of the features added in Salt Lake City in Overture's May release.

Let's do query that dumps to the terminal all the new places in the May release for our area of interest.

SELECT
    id
FROM
    read_parquet('s3://overturemaps-us-west-2/changelog/2025-05-21.0/theme=places/*/*/*.parquet')
WHERE
    change_type = 'added'
    AND bbox.xmin > -112.461 AND bbox.xmax < -111.073
    AND bbox.ymin > 40.296 AND bbox.ymax < 40.955;

This gives us 5,727 new places in the Salt Lake City area added to the May release. Now let's write a query to join this list of new places to the full May data release by id and write out a new Parquet file:

COPY(
    SELECT
        places.id as id,
        names.primary as name,
        categories.primary as category,
        confidence,
        CAST(sources AS JSON) as sources,
        geometry
    FROM
        read_parquet('s3://overturemaps-us-west-2/release/2025-05-21.0/theme=places/type=place/*') places
    JOIN (
        SELECT
            id
        FROM
            read_parquet('s3://overturemaps-us-west-2/changelog/2025-05-21.0/theme=places/*/*/*.parquet')
        WHERE 
            change_type = 'added'
            AND bbox.xmin > -112.461 AND bbox.xmax < -111.073 
            AND bbox.ymin > 40.296 AND bbox.ymax < 40.955
            ) changelog
        ON places.id = changelog.id
        ORDER BY places.id ASC
    ) TO 'new_places_slc_may.parquet';

Let's go one step further and query the one-time May to June ID mapping to translate the May IDs in our list of new places to the new UUID system. Here's how we would do that:

COPY(
    SELECT 
        newUUIDs.id
     FROM 
         read_parquet('new_places_slc_may.parquet') oldIDs
     JOIN (
     SELECT
        *
     FROM read_parquet('s3://overturemaps-extras-us-west-2/june_to_may_id_mapping/theme=places/type=place/*')) newUUIDs
     ON newUUIDs.previous_id = oldIDs.id
     ) TO 'new_places_slc_may_UUIDs.parquet';

This tells us that all 5,727 new places in Salt Lake City that appeared in the May release were assigned new UUIDs before the June data release. Can we find all of those UUIDs in the June release? Let's take a look. Note: this query take several minutes to run.

COPY(
     SELECT
            june_places_UUID.id,
            names.primary as name,
            categories.primary as category,
            confidence,
            CAST(sources AS JSON) as sources,
            geometry
        FROM
            read_parquet('s3://overturemaps-us-west-2/release/2025-06-25.0/theme=places/type=place/*') june_places_UUID
        JOIN(
            SELECT
                id
            FROM
                read_parquet('new_places_slc_may_UUIDs.parquet')) may_places_UUID
            ON 
                june_places_UUID.id = may_places_UUID.id
    ) TO new_places_slc_may_to_june_UUIDs.parquet;

Only 1,546 of new places that appeared in the May release show up in the June release with their newly- assigned UUIDs. This is a known quality issue with our source datasets. As tedious as this process might be, it demonstrates how we can use the GERS tools to track features across releases and gauge churn and data quality from one release to another. Overture is aware that some of our source data providers have significant churn in their data before the data is ingested in Overture pipelines each month. We're working hard to improve these issues. Transparency is the first step.

Using bridge files​

Now what? Let's move forward with our smaller-than-expected dataset of new places in the June release and see if we can find the Facebook pages for some of them. How might we do that? Bridge files are published mappings of GERS ID to source IDs for the datasets that Overture ingests before each release. We only create bridge files for established datasets with a meaningful record_id properites. ML-Derived buildings, for example, do not have stable meaningful input IDs, but place records from Meta have corresponding IDs that reference public Facebook pages.

The sources property in each Overture data release lists the original source of the data and any additional properties that Overture has added. We can use the bridge file for Meta's places data to map the GERS ID back to the source ID. Then we can look up the Facebook pages for the new places in Salt Lake City:

COPY(
    SELECT
        'https://facebook.com/' || cast(bridge.record_id as varchar) AS facebook_page,
            slc_places.*
    FROM read_parquet('new_places_slc_may_to_june_UUIDs.parquet') slc_places 
    JOIN(
        SELECT
            id,
            record_id
        FROM
            read_parquet('s3://overturemaps-us-west-2/bridgefiles/2025-06-25.0/dataset=meta/theme=places/type=place/*')
        ) bridge ON slc_places.id = bridge.id
    ) TO 'new_places_slc_with_fb_pages.geojson' WITH (FORMAT GDAL, Driver GeoJSON);

One new place of note is the "Bootlegged Barber" in Sandy, Utah. On their Facebook page, the proprietors advertise themselves as a "NeoTraditional Barbershop | Where tradition and style meet."

Bootleg Barbershop

Next steps​