Skip to main content

Registry

The GERS registry is the catalog of identifiers that carry a stability commitment. The registry can tell you if the ID is part of GERS at all, in the current release, and when the feature associated with that ID last changed.

There is only ever one registry. It is not versioned. Each release rebuilds it by comparing the published registry with the new release data and overwriting it in place, so what you read is always current.

ProviderLocation
Amazon S3s3://overturemaps-us-west-2/registry/
Microsoft Azure Blob Storagehttps://overturemapswestus2.blob.core.windows.net/registry/

The files are Parquet, sorted by id across roughly 50 files, so a lookup by ID is fast and efficient.

What the registry is for​

Overture publishes identifiers for every feature in every theme. Only some of them are GERS IDs. Features in the base theme and features of type building_part carry deterministic UUIDs that are structurally identical to GERS IDs and carry no stability commitment at all.

You cannot tell the difference by looking at the identifier. Presence in the registry is the only discriminator, and that is the registry's main job.

Schema​

ColumnTypeDescription
idstringThe GERS ID, a 128-bit random UUID. See what a GERS ID is.
versionintegerThe feature's version at last_seen.
first_seenstringThe release in which this identifier first appeared. Identifiers predating the 2025-06-25.0 switchover all show that release, so this is not the feature's age.
last_seenstringThe most recent release containing the ID.
last_changedstringThe most recent release in which the feature changed, taken from the changelog.
pathstringPath to the Parquet file holding the feature, relative to the release root. Null when the ID is not in the current release.
bboxstruct of floatBounding box of the feature. Null when the ID is not in the current release.

first_seen is not the age of the feature​

Every identifier in Overture was replaced in the 2025-06-25.0 release, and the registry begins there. Roughly 3.3 billion identifiers carry that release as their first_seen, against 7 to 27 million added in each release since. For most of the registry, first_seen records when the current identifier was minted, not when Overture first carried the feature. Use it to reason about identifiers, not about how long the thing they point at has existed.

A null path is meaningful. It means the ID is part of GERS and is not in the current release. bbox is null on those rows for the same reason. Use path IS NOT NULL as your test for "still live", and last_seen to find the release that last carried it.

path is relative to the release root. It starts at theme= and has no leading slash, so prepend the release root to get a full path:

s3://overturemaps-us-west-2/release/<RELEASE>/theme=buildings/type=building/part-00403-e684fe1e-d4f5-5b6a-8315-f17bb5d8394c-c000.zstd.parquet

Or have the query do it:

LOAD httpfs;  -- noqa
SET s3_region='us-west-2';

-- The registry's path column is relative to the release root and starts at
-- theme=, so prepend the release root to get a path you can read directly.
SELECT
    id,
    's3://overturemaps-us-west-2/release/2026-09-23.1/' || path AS file
FROM read_parquet('s3://overturemaps-us-west-2/registry/*.parquet')
WHERE id = 'fea28f69-7afa-460c-b270-61ef74cd340c';

What is in the registry​

building, division, division_area, division_boundary, place, segment, and connector.

Inclusion signifies Overture's long-term commitment to matching and stability for that type. The three exclusions are the base theme, the building_part type, and the addresses theme. Base and building_part come from a single source and need no matching to conflate, so they cannot offer stability through matching, which is the thing GERS provides. Addresses are excluded pending general availability of that theme rather than as a permanent decision.

The filter is written as a deny-list, so a new feature type added to a theme that is not excluded joins the registry automatically.

Addresses​

Address features carry identifiers, and between the July and December 2025 releases those identifiers were in the registry. They were withdrawn pending general availability of the addresses theme, and the identifiers published during that window were withdrawn with them.

So an address ID from a 2025 release will not be found in the registry today. That is a statement about the commitment, not about the identifier: it means Overture is not yet promising stability for addresses, because the addresses matcher is still being built. Addresses are expected to return to the registry at GA.

Guarantees​

Every release candidate validates the registry before it can be published, and any failure blocks the release. Four of those checks are guarantees you can build assertions against:

  • id is unique in the registry.
  • first_seen, last_seen, and last_changed are never null, and first_seen <= last_changed <= last_seen always holds.
  • Any row with a populated path has last_seen equal to the current release.
  • Registry contents and release contents never disagree in either direction. No row claims to be in the release when it is not, and no row claims absence when the ID is present.

Example: is this ID part of GERS?​

LOAD httpfs;  -- noqa
SET s3_region='us-west-2';

-- Is this identifier part of GERS, and is it in the current release?
-- The registry is not versioned, so there is no release in this path.
SELECT id, version, first_seen, last_seen, last_changed, path, bbox
FROM read_parquet('s3://overturemaps-us-west-2/registry/*.parquet')
WHERE id = 'fea28f69-7afa-460c-b270-61ef74cd340c';

One row comes back, so this identifier is part of GERS rather than a bare UUID:

ColumnValue
idfea28f69-7afa-460c-b270-61ef74cd340c
version1
first_seen2025-06-25.0
last_seen2026-09-23.1
last_changed2025-06-25.0
paththeme=buildings/type=building/part-00403-….zstd.parquet
bboxxmin 80.67177, xmax 80.67182, ymin 26.61979, ymax 26.61984

Reading it: this is a building, last_seen is the current release so the identifier is still live, and last_changed is the switchover release, meaning nothing about this building has changed in any release since. path names the one file that holds it, so you can read the feature without scanning the theme. Part file names change with every release, which is why the query below takes the path from the registry rather than hardcoding one.

LOAD httpfs;  -- noqa
SET s3_region='us-west-2';

-- The registry gives the path to the exact Parquet file holding a feature, so
-- you can read that one file instead of scanning the theme. Part file names
-- change with every release, so take the path from the registry rather than
-- pasting one in.
SET VARIABLE feature_path = (  -- noqa
    SELECT 's3://overturemaps-us-west-2/release/2026-09-23.1/' || path
    FROM read_parquet('s3://overturemaps-us-west-2/registry/*.parquet')
    WHERE id = 'fea28f69-7afa-460c-b270-61ef74cd340c'
);

SELECT *
FROM read_parquet(getvariable('feature_path'))
WHERE id = 'fea28f69-7afa-460c-b270-61ef74cd340c';

Looking up an ID without SQL​

The Overture Explorer finds features by GERS ID. Paste an identifier into the search box and Explorer switches to GERS mode on its own, goes straight to the feature, and selects it. The result can be shared as a link.

Explorer only shows features that are in the current release. The registry also covers identifiers that have dropped out of one, so if you need to tell a removed feature from an identifier that was never in GERS, use the registry.

Example: which of my IDs are still live?​

Registry lookups are cheap enough to run over a whole table of held identifiers:

LOAD httpfs;  -- noqa
SET s3_region='us-west-2';

-- Check a whole table of held identifiers against the registry in one pass.
-- Swap the my_matched_records CTE for your own crosswalk table. It needs one
-- column of your record identifiers and one column of GERS IDs.
-- last_seen IS NULL         the identifier is not in GERS at all
-- in_current_release false  the feature is gone, so re-match those records
WITH my_matched_records AS (
    SELECT *
    FROM (VALUES
        ('inspection-4471', 'fea28f69-7afa-460c-b270-61ef74cd340c'),
        ('inspection-8823', '00000000-0000-0000-0000-000000000000')
    ) AS t (my_record_id, gers_id)
)

SELECT
    m.my_record_id,
    m.gers_id,
    r.last_seen,
    r.last_changed,
    r.path IS NOT NULL AS in_current_release
FROM my_matched_records AS m
LEFT JOIN read_parquet('s3://overturemaps-us-west-2/registry/*.parquet') AS r
    ON m.gers_id = r.id;

A null r.last_seen means the ID is not in GERS at all: either it was never a GERS ID, or you are holding an identifier from before the June 2025 switchover. in_current_release = false means the feature has gone and those records need re-matching. See GERS ID stability.

Last updated on