Skip to content

Common Geocoding and Search Response Format

The Stadia Maps geocoding, search, and autocomplete API endpoints share a common GeoJSON response format.

Standard envelope

Field Description
geocoding A meta information object. Full description below.
bbox An array of 4 floating point numbers representing the (W, S, E, N) extremes of the features found.
features A list of GeoJSON features. These conform to RFC 7946. Properties are documented below.

geocoding meta object properties

Most fields are not something you’ll normally need to care about for your application development, but it contains some useful debugging information. We’ve mentioned the noteworthy fields below; the rest should be self-explanatory.

Field Description
attribution A URL containing attribution information. If you are not using Stadia Maps and our standard attribution already for your basemaps, you must include this attribution link somewhere in your website/app.
warnings An array of non-critical warnings. This is normally for informational/debugging purposes and not a serious problem.
errors (v1) / error (v2) An array (v1) / string (v2) of serious error(s) (for example, omitting a required parameter). Don’t ignore these.

This object may contain other properties for debugging purposes, but these are not guaranteed to be stable.

feature properties

Field Description
accuracy Any feature which can be represented as a single geographic point will be a point. Places which are an area (such a a city) are centroids. Note that this field does not necessarily indicate anything about the quality of a result.
addendum Optional additional information from the underlying data source (ex: OSM). This includes select fields. The Wikipedia and Wikidata IDs and the website (all optional) are probably the most useful for OSM results.
continent, country, neighbourhood, postalcode, street, housenumber Should be fairly self-explanatory.
confidence The level of confidence (0.0 - 1.0) that the result is what you actually searched for. This is not necessarily the same as relevance (results are returned sorted by relevance already), but rather how closely the explicit or inferred components match the result.
Various GIDs Scoped GIDs referencing the underlying dataset. These are not necessarily stable for all data sources.
source_id An ID referencing the original data source (specified via source) for the result. In the case of OSM, these typically look like way/123 or point/123.
label A full, human-readable label. However, you may not necessarily want to use this; be sure to read about name, locality, and region before deciding. This field is mostly localized. The order of components is generally locally correct (ex: for an address in South Korea, the house number appears after the street name). However, components will use a request language equivalent if one exists (ex: Seoul instead of 서울 if lang=en).
name The name of the place, the street address including house number, or label of similar relevance. If your app is localized to a specific region, you may get better display results by combining name, locality OR region (or neither?), and postal code together in the local format. Experiment with what works best for your use case.
locality The city, village, town, etc. that the place / address is part of. Note that at this time, the matching is a bit crude, so values may not always match postal or local conventions perfectly. This is an area of active development.
county Administrative divisions between localities and regions. Useful for disambiguating nearby results with similar names.
region Typically the first administrative division within a country. For example, a US state or a Canadian province.
Field Description
addendum Optional additional information from the underlying data source (ex: OSM or Who's on First).
address_components The structured components of the feature's street address.
coarse_location The coarse-grained location of the place (e.g. Seoul, South Korea). In search experiences, this is typically the second line of a result cell.
confidence The level of confidence (0.0 - 1.0) that the result is what you actually searched for. This is not necessarily the same as relevance (results are returned sorted by relevance already), but rather how closely the explicit or inferred components match the result.
context The geographic context for a feature.
distance The distance from the search focus point, in kilometers.
formatted_address_line The address formatted as a single line, following local postal conventions for ordering and separators.
formatted_address_lines Address components split up into lines, following local postal conventions for ordering and separators.
gid The globally unique identifier for this result. You can use this to uniquely identify a place, and to fetch the full details from the place details endpoint. NOTE: While GIDs are unique, they may not necessarily be stable in all datasets.
layer The data layer containing the place (e.g. "address" or "poi").
name The best name for the place, accounting for request language preferences. When building an autocomplete search experience, this is the primary display string.
precision Any feature which can be represented as a single geographic point will be a point. Places which are an area (such a a city) are centroids.
sources A list of sources from which the result is derived.

NOTE: The v2 autocomplete endpoint has a reduced set of properties: coarse_location, distance, gid, layer, name, and precision.

Refer to the full API reference for details on all the sub-keys.

Note

We generally attempt to present the same view as OpenStreetMap. When we include location context referencing a data source, we are not necessrily implying that the source endorses any specific view. Contact us if your use case requires a specific political view of the world.

Example Response

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

{
  "geocoding": {
    "attribution": "https://stadiamaps.com/attribution/"
  },
  "type": "FeatureCollection",
  "bbox": [
    -77.036547,
    38.897675,
    -77.036547,
    38.897675
  ],
  "features": [
    {
      "type": "Feature",
      "geometry": {
        "type": "Point",
        "coordinates": [
          -77.036547,
          38.897675
        ]
      },
      "properties": {
        "gid": "openaddresses:address:us/dc/statewide-addresses-city:aa53d4bd0fe295be",
        "layer": "address",
        "sources": [
          {
            "source": "openaddresses",
            "source_id": "us/dc/statewide-addresses-city:aa53d4bd0fe295be"
          }
        ],
        "precision": "point",
        "name": "1600 Pennsylvania Avenue NW",
        "formatted_address_lines": [
          "1600 Pennsylvania Avenue NW",
          "Washington, District of Columbia 20500"
        ],
        "formatted_address_line": "1600 Pennsylvania Avenue NW, Washington, District of Columbia 20500",
        "coarse_location": "Washington, DC, United States",
        "address_components": {
          "number": "1600",
          "street": "Pennsylvania Avenue NW",
          "postal_code": "20500"
        },
        "context": {
          "whosonfirst": {
            "country": {
              "gid": "whosonfirst:country:85633793",
              "name": "United States"
            },
            "region": {
              "gid": "whosonfirst:region:85688741",
              "name": "District of Columbia"
            },
            "county": {
              "gid": "whosonfirst:county:1377370667",
              "name": "District of Columbia"
            },
            "neighbourhood": {
              "gid": "whosonfirst:neighbourhood:1108724059",
              "name": "White House Grounds"
            },
            "locality": {
              "gid": "whosonfirst:locality:85931779",
              "name": "Washington"
            }
          },
          "iso_3166_a2": "US",
          "iso_3166_a3": "USA"
        }
      }
    }
  ]
}