Bridge Files

With each release, Overture publishes bridge files that map the identifiers in its source data to the GERS IDs those sources contributed to. They answer two questions: which source records went into a given Overture feature, and which GERS ID a given source record ended up in.

The second direction is the useful one for most readers. If your data already shares an identifier system with one of Overture's sources, bridge files give you GERS IDs without matching anything. A dataset keyed to OpenStreetMap IDs, for example, can pick up GERS IDs with a join rather than a conflation job.

Provider	Location
Amazon S3	`s3://overturemaps-us-west-2/bridgefiles/<RELEASE>`
Microsoft Azure Blob Storage	`https://overturemapswestus2.blob.core.windows.net/bridgefiles/<RELEASE>`

The latest <RELEASE> is:

2026-09-23.1/

Coverage

Bridge files exist for five combinations of theme and type:

buildings / building
divisions / division
divisions / division_area
places / place
transportation / segment

There are no bridge files for the addresses or base themes, and none for building_part, division_boundary, or connector. Two of those types are in the GERS registry, so their absence here is a gap rather than a statement about their identifiers.

Within those five, every source dataset is included by default, and a hand-maintained list excludes a few: Microsoft ML Buildings, Google Open Buildings, USGS Lidar and a Zenodo buildings dataset for buildings; TomTom for segments; Esri Community Maps and Maps Entity Variant Names for divisions. Most are sources whose record identifiers are not stable or not meaningful to look up. Places has no exclusions, so every places source appears.

note

Not every feature has a bridge file row. Joining a release to its bridge files returns fewer rows than the release contains. A feature built only from excluded sources has no row at all, and that is expected: the feature is in the reference map, it just has no source identifier to look up. Use a left join if you want to keep those features.

Partitioning

Bridge files are Parquet, partitioned by provider, theme, and type:

bridgefiles/
  <RELEASE>/
    provider=osm/
      theme=buildings/type=building/
      theme=divisions/type=division/
      theme=divisions/type=division_area/
      theme=places/type=place/
      theme=transportation/type=segment/
    provider=meta/
      theme=places/type=place/
    provider=microsoft/
      theme=places/type=place/
    provider=esri/
      theme=buildings/type=building/
    ...

provider is a short lowercase label such as osm, meta, microsoft, pinmeto, or esri. It is not the same as dataset, which is the human-readable source name and remains an ordinary column. Source records that carry no provider value appear under provider=unknown.

warning

Partitioning changed in August 2026. Bridge files were partitioned by dataset until the 2026-08 release and are partitioned by provider from that release onward. A query written against dataset=<name>/theme=.../type=... will return nothing against current data. Change the first path segment to provider=<label>, or glob it with provider=* and filter on the dataset column instead.

Schema

Column	Type	Description
`id`	string	The GERS ID, from the `id` column of the Overture feature.
`record_id`	string	The feature's identifier in the source data, parsed from the Overture `sources` column. For OpenStreetMap this includes the object type and version, as in `n2757802019@9`.
`dataset`	string	The human-readable name of the source dataset.
`provider`	string	Partition key. Short label for the organization supplying the data. `unknown` where the field was not recorded.
`resource`	string	The specific resource within the dataset, where the provider supplies one. Nullable.
`version`	string	The source resource version, where the provider supplies one. Nullable.
`update_time`	string	When the source feature or dataset was updated, depending on what the provider reports. Parsed from `sources`.
`theme`	string	Partition key.
`type`	string	Partition key.
`between`	array of double	For linear features, the portion of the Overture segment covered by the source way, as a normalized range between 0 and 1. Null elsewhere.
`dataset_between`	array of double	Reserved. Always null. Overture does not compute the inverse mapping.

A single GERS ID appears on multiple rows when it was conflated from multiple sources. That is the normal case for buildings and places.

Example: source identifiers to GERS IDs

Overture's places data includes records from Meta, and those record_id values are Facebook page identifiers. Joining the bridge file to the release turns GERS IDs into links you can follow:

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

-- Resolve GERS IDs back to their source records.
-- Meta place record_ids are Facebook page identifiers, so the join
-- turns each GERS ID into a link you can follow.
SELECT
    p.id AS gers_id,
    p.names.primary AS name,
    'https://facebook.com/' || b.record_id AS source_url
FROM read_parquet('s3://overturemaps-us-west-2/release/2026-09-23.1/theme=places/type=place/*') AS p
INNER JOIN read_parquet('s3://overturemaps-us-west-2/bridgefiles/2026-09-23.1/provider=meta/theme=places/type=place/*') AS b
    ON p.id = b.id
WHERE
    p.bbox.xmin > -75.280303
    AND p.bbox.xmax < -74.955763
    AND p.bbox.ymin > 39.867005
    AND p.bbox.ymax < 40.137992
LIMIT 10;

The same join in the other direction is the on-ramp for anyone holding source identifiers. If you maintain a dataset keyed to OpenStreetMap, join your OSM IDs to record_id under provider=osm and you have GERS IDs without running a matcher. Note that the OSM record_id carries a version suffix, so strip it before joining if your identifiers do not have one.

Example: tracing a feature back to its sources

Bridge files also show how Overture built a feature. Take buildings in a small area and count them by source:

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

-- Which sources contributed the buildings in a small area near the
-- US-Mexico border outside San Diego?
SELECT
    sources[1].dataset AS source,
    count(*) AS buildings
FROM read_parquet('s3://overturemaps-us-west-2/release/2026-09-23.1/theme=buildings/type=building/*')
WHERE
    bbox.xmin > -117.048198
    AND bbox.xmax < -117.044608
    AND bbox.ymin > 32.535068
    AND bbox.ymax < 32.600154
GROUP BY source
ORDER BY buildings DESC;

Then join to the bridge files to see which of those buildings were assembled from more than one source:

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

-- Which buildings were conflated from more than one source?
-- Globbing provider=* reads every provider, then the dataset column
-- gives the human-readable source name.
WITH border_buildings AS (
    SELECT id
    FROM read_parquet('s3://overturemaps-us-west-2/release/2026-09-23.1/theme=buildings/type=building/*')
    WHERE
        bbox.xmin > -117.048198
        AND bbox.xmax < -117.044608
        AND bbox.ymin > 32.535068
        AND bbox.ymax < 32.600154
)

SELECT
    bb.id AS gers_id,
    count(DISTINCT b.dataset) AS source_count,
    string_agg(DISTINCT b.dataset, ', ') AS datasets
FROM border_buildings AS bb
INNER JOIN read_parquet('s3://overturemaps-us-west-2/bridgefiles/2026-09-23.1/provider=*/theme=buildings/type=building/*', filename=true, hive_partitioning=1) AS b
    ON bb.id = b.id
GROUP BY bb.id
HAVING count(DISTINCT b.dataset) > 1
ORDER BY source_count DESC, gers_id;

A building that appears with both OpenStreetMap and Esri Community Maps was created by a conflation process that drew on both. It may also have drawn on sources that produce no bridge files, so read the result as a floor rather than a complete account.

Next steps

Follow the GERS tutorial to match data that does not share an identifier system with an Overture source.
Use the changelog to keep a match current across releases.
Query the registry to check whether an ID you hold is still live.

Coverage​

Partitioning​

Schema​

Example: source identifiers to GERS IDs​

Example: tracing a feature back to its sources​

Next steps​