v1

latestOpenAPI 3.1.02026-08-0420183200.9 KB

Geocoding

Retrieve details of a place using its GID.

Many search result components include an associated GID field (for example, an address may have a localadmin_gid). The place endpoint lets you look up these places directly by ID. Note that GIDs are not stable for all sources. See the online documentation for details.

get/geocoding/v1/place

Query parameters

idsstring[] required

A list of GIDs to search for.

langstring

A BCP47 language tag which specifies a preference for localization of results. By default, results are in the default locale of the source data, but specifying a language will attempt to localize the results. Note that while a langtag (in RFC 5646 terms) can contain script, region, etc., only the language portion, an ISO 639 code, will be considered. So en-US and en-GB will both be treated as English.

Response

A GeoJSON collection of search results.

bboxnumber[]

An array of 4 floating point numbers representing the (W, S, E, N) extremes of the features found.

Example response

{
  "bbox": [
    -77.036547,
    38.897675,
    -77.036547,
    38.897675
  ],
  "features": [
    {
      "geometry": {
        "coordinates": [
          -77.036547,
          38.897675
        ],
        "type": "Point"
      },
      "properties": {
        "accuracy": "point",
        "confidence": 1,
        "continent": "North America",
        "continent_gid": "whosonfirst:continent:102191575",
        "country": "United States",
        "country_a": "USA",
        "country_code": "US",
        "country_gid": "whosonfirst:country:85633793",
        "county": "District of Columbia",
        "county_a": "DI",
        "county_gid": "whosonfirst:county:1377370667",
        "gid": "openaddresses:address:us/dc/statewide:aa53d4bd0fe295be",
        "housenumber": "1600",
        "id": "us/dc/statewide:aa53d4bd0fe295be",
        "label": "1600 Pennsylvania Avenue NW, Washington, DC, USA",
        "layer": "address",
        "locality": "Washington",
        "locality_gid": "whosonfirst:locality:85931779",
        "match_type": "exact",
        "name": "1600 Pennsylvania Avenue NW",
        "neighbourhood": "White House Grounds",
        "neighbourhood_gid": "whosonfirst:neighbourhood:1108724059",
        "postalcode": "20500",
        "region": "District of Columbia",
        "region_a": "DC",
        "region_gid": "whosonfirst:region:85688741",
        "source": "openaddresses",
        "source_id": "us/dc/statewide:aa53d4bd0fe295be",
        "street": "Pennsylvania Avenue NW"
      },
      "type": "Feature"
    }
  ],
  "geocoding": {
    "attribution": "https://stadiamaps.com/attribution",
    "engine": {
      "name": "Theseus",
      "version": "1.0"
    },
    "query": {
      "lang": {
        "defaulted": true,
        "iso6391": "en",
        "iso6393": "eng",
        "name": "English",
        "via": "default"
      },
      "parsed_text": {
        "housenumber": "1600",
        "street": "pennsylvania ave nw"
      },
      "parser": "libpostal",
      "private": false,
      "querySize": 20,
      "size": 10,
      "text": "1600 Pennsylvania Ave NW"
    },
    "timestamp": 1679043782383,
    "version": "0.2"
  },
  "type": "FeatureCollection"
}