Global IDs

Every result from Geocode Earth includes several properties containg Global IDs, or gids.

These identifiers are meant to help you work with the rich hierarchy of places that Geocode Earth understands.

For example, the following response data shows what might be sent back for a query returning the New York city borough of Manhattan:

{
  "properties": {
    "gid": "whosonfirst:borough:421205771",
    "layer": "borough",
    "source": "whosonfirst",
    "source_id": "421205771",
    "name": "Manhattan",
    "confidence": 1,
    "match_type": "exact",
    "accuracy": "centroid",
    "country": "United States",
    "country_gid": "whosonfirst:country:85633793",
    "country_a": "USA",
    "region": "New York",
    "region_gid": "whosonfirst:region:85688543",
    "region_a": "NY",
    "county": "New York County",
    "county_gid": "whosonfirst:county:102081863",
    "county_a": "NE",
    "locality": "New York",
    "locality_gid": "whosonfirst:locality:85977539",
    "locality_a": "NYC",
    "borough": "Manhattan",
    "borough_gid": "whosonfirst:borough:421205771",
    "continent": "North America",
    "continent_gid": "whosonfirst:continent:102191575",
    "label": "Manhattan, New York, NY, USA"
  }
}

This response includes Global IDs for both Manhattan itself, as well as all its parents: New York City, New York County, New York State, the United States, and even the continent of North America.

Filtering by parent Global ID #

Any of the parent Global IDs shown above can be used with the boundary.gid parameter to filter results.

However, other Global IDs from datasets besides Who’s on First can not be used with boundary.gid.

Datasets without stable IDs #

Due to the ever-changing nature of open data, some Global IDs can change at any time as we update our data.

Both Geonames and Who’s on First have excellent, stable IDs: you can store these IDs in your own databases and be confident that they will refer to the same record later.

However, OpenAddresses and OpenStreetMap do not have stable IDs. The same address, point of interest, or other record returned for a particular query might return a different Global ID later.

While you can use the Global ID of an OpenStreetMap or OpenAddresses record to compare results from two queries made at the same time as one another, don’t count on seeing the same Global ID over time.