Skip to content

Common Response Format

The Stadia Maps geocoding, search, and autocomplete API endpoints share a common JSON 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 https://www.rfc-editor.org/rfc/rfc7946. 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.
query Technical details of the query. This is most useful for debugging during development. See the full example for the list of properties; these should be self-explanatory.
warnings An array of non-critical warnings. This is normally for informational/debugging purposes and not a serious problem.
errors An array of more serious errors (for example, omitting a required parameter). Don’t ignore these.

feature properties

Field Description
accuracy See Determining Result Quality for details.
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.
Various GIDs Scoped GIDs referencing the underlying dataset. These are generally stable IDs.
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.

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": "Pelias",
            "author": "Mapzen",
            "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:aa53d4bd0fe295be",
                "layer": "address",
                "source": "openaddresses",
                "source_id": "us/dc/statewide: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
    ]
}