Global Entity Reference System (GERS)

Understanding GERS

The Global Entity Reference System (GERS) is a framework for structuring, encoding, and matching map data to a shared universal reference. All features in Overture have a unique ID, and for some feature types those unique IDs, called Overture IDs or GERS IDs, are registered to GERS and are intended to be stable. GERS provides a mechanism to match features across datasets, track data stability, and detect errors in the data.

What does an Overture ID look like?

Unique IDs in Overture are 128 bits and 32 characters. Below you can inspect the unique IDs for five building features in Overture's latest release. The property appears as id in the schema.

D SELECT id FROM read_parquet('s3://overturemaps-us-west-2/release/2024-07-22.0/theme=buildings/type=building/*', filename=true, hive_partitioning=1) limit 5;
┌──────────────────────────────────┐
│                id                │
│             varchar              │
├──────────────────────────────────┤
│ 08bf2a40219b0fff0200c394dae731bd │
│ 08bf35ad6a05afff0200e90ab3b011fa │
│ 08bf35ad6a058fff020009945ce09d65 │
│ 08bf35ad6a04efff02006264a736fc56 │
│ 08bf35ad6a04afff0200cf5e511a3f1b │
├──────────────────────────────────┤
│             5 rows               │
└──────────────────────────────────┘

Stability and traceability

Unique IDs registered to GERS are intended to be stable — within a reasonable tolerance of error — across multiple Overture releases. When stability is not possible, we will attempt to provide traceability in a GERS changelog. For example:

• a single road segment is bisected by a new road and becomes two road segments: 1 unique ID → 2 new unique IDs;
• a large building footprint is determined to be four smaller buildings when a higher resolution dataset becomes available: 1 unique ID → 4 new unique ID;
• a building is shifted 10 meters to the west when higher resolution imagery is made available: the unique ID is preserved for that feature.

Using GERS

Here are two general mechanisms for using GERS:

1. Associating data. You can independently associate your own data or third-party data to Overture data. If features in your dataset match features in an Overture dataset, you can assign existing Overture IDs to the matched features. Your data is now GERS-enabled data, ready to be associated via Overture ID to any other GERS-enabled dataset in the Overture ecosystem.
2. Contributing data. If an organization contributes data to the Overture Maps Foundation, our engineering team will match the features in that dataset to features in Overture. Matched features may be assigned an existing Overture ID, and we may generate new Overture IDs for new features.

You'll find theme-specific examples in the GERS demonstrations section of this documentation.