Geographic identifiers: `geo_id`#

To streamline data exchange, essential entities in openplaces (parcels, buildings, footprints, admin units) are indexed with globally replicable, location-based identifiers (IDs):

Entity

Identifier

Anonymity

Administrative units

admin_id

Example: 'US-CA-LA' (Los Angeles, California)

Global, hierarchical ISO/HASC/custom code

Purposefully human-readable

Used to organize code and data.

Buildings, footprints

openlocationcode

Example: '8765MFPF+7FC'

Reversible Plus Code

Easily identifiable (encodes location)

Global building footprints are already public data.

Parcels

geo_id

Example: '5965a76da11121835af16e83'

Encrypted, quantized polygon geometry derivative

Securely hashed, but not anonymous.

You can infer the polygon from a geo_id if you already know six of the polygon’s geometric properties (bounds, area, complexity). It is trivial to crack if the geo_id is derived from a public parcel polygon.

Administrative units: `admin_id`#

openplaces ships with a global referencing system for countries, states, counties, etc.

Example: 'US-CA-LA': county of Los Angeles, California, U.S.

Learn more about these identifiers in the section on administrative units.

Building footprints: Plus Codes#

Building footprints and point locations in openplaces are indexed using Open Location Codes (OLCs), commonly known as Plus Codes.

Example: '8765MFPF+7FC'

These Plus Codes define a specific area on the Earth’s surface. They are non-anonymous and reversible: they can be decoded directly back into a latitude and longitude bounding box without needing a database lookup.

For buildings and footprints, that seems non-controversial: building geometries and locations are already publicly visible globally, often derived from open satellite imagery.

Parcels and the `geo_id`#

All parcels in openplaces (so far) are indexed with a parcel_id.

Example: 'a3f1c08e9b2d47e6c5a09f4b'

This type of identifier is a geo_id: a unique identifier derived from a geo-referenced 2D polygon.

The geo_id is designed to link parcel datasets across time and versions, without giving away the actual coordinates of the parcel (unless the exact coordinates are known to the “attacker”, e.g., in a public parcel dataset).

Why stable, geometry-based parcel identifiers?#

Source parcel numbers (e.g., assessor parcel numbers, map numbers) are unreliable as long-term keys for unique parcel polygons: they are jurisdiction-specific, can change between assessments, some parcels have no IDs, some polygons have duplicate IDs, etc.

The geo_id answers the question:

Is this the same piece of land I saw in a different download, from a different source?

A stable parcel boundary hashes to the same value. Therefore, the geo_id allows you to:

Join a parcel to its earlier and later vintages.
Attach transactions, assessments, and footprints to the same lot over time.
Deduplicate parcels that appear in more than one source dataset.

How the `geo_id` is built#

The geo_id is generated by the function openplaces.geo.ids.get_geo_ids().

It reduces each polygon to six numbers, each computed in the global EPSG:4326 projection:

Its bounding-box corners minx, miny, maxx, and maxy, snapped to a grid of 0.000001°
Its log-scaled and rounded area (in degrees)
Its compactness (perimeter² / area, a unitless shape measure), also scaled and rounded.

These six integers are joined into a single string:

"{minx_q},{miny_q},{maxx_q},{maxy_q},{area_q},{compact_q}"

This string is then hashed using SHA-256, and the first 24 characters are used as the geo_id.

        flowchart TD
    geom([Input polygon]) --> bbox[1a. Extract snapped minx, miny, maxx, maxy]
    geom --> area[1b. Compute & round log-scaled area]
    geom --> comp[1c. Compute & round compactness]
    bbox & area & comp --> join[2. Format string: minx,miny,maxx,maxy,area,compactness]
    join --> hash[3. Hash with secure SHA-256 algorithm]
    hash --> trunc[4. Pick first 24 characters]
    trunc --> geoid([geo_id])

An empty geometry gets the value: 'no-geometry'.

Two parcels that happen to share a bounding box, area, and compactness can collide. Unique suffixes ('-1', '-2') are added to duplicate geo_id values to obtain unique parcel_id values.

What counts as a significant change#

The geo_id is deliberately tolerant. A boundary shift is invisible to it when it stays below the grid threshold: rounding errors from reprojections do not alter the ID.

A change is significant, and generates a new geo_id, when it is large enough to:

Move a bounding-box corner into a different 0.000001° cell (~11 cm @ equator; ~8 cm at 45°N).
Shift the log-scaled area by ~2.3% or more.
Shift the compactness (perimeter² / area ratio) by 0.1 or more.

Subdividing a lot, merging two lots, lopping off a strip for road widening, or resurveying the outline all produce a new ID because they represent a different parcel of land.

Geographic identifiers: geo_id#

Administrative units: admin_id#