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. |
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
]
}