99e0701a73aa
latestOpenAPI 3.1.02026-08-0420183200.9 KBFind locations matching components (structured forward geocoding).
The structured search endpoint lets you search for addresses, points of interest, and administrative areas. Rather than a single string which the API must infer meaning from, the structured search endpoint allows you to specify the known components upfront, which is useful in many forward geocoding workflows.
Query parameters
A street name and optional house number together, e.g. 11 Wall St. If you have the data available separately, you should provide the house number and street separately.
A house or building number. Mutually exclusive with the address field. Requires street to also be specified.
A street name. Mutually exclusive with the address field.
The apartment, suite, or unit number. Requires both house_number and street to be specified. Mutually exclusive with the address field.
A smaller area within a locality, e.g. Financial District. Practices vary by area, but these are typically not distinct administrative units.
A unit within a city, e.g. Manhattan (not widely used outside mega cities like NYC and Mexico City).
The city, village, town, etc. that the place/address is part of.
Administrative divisions between localities and regions. Not commonly used as input to structured geocoding.
Typically the first administrative division within a country. For example, a US state or a Canadian province.
A mail sorting code (e.g. a US ZIP code).
A country code in ISO 3116-1 alpha-2 or alpha-3 format.
The latitude of the point to focus the search on. This will bias results toward the focus point. Requires focus.point.lon.
The longitude of the point to focus the search on. This will bias results toward the focus point. Requires focus.point.lat.
Defines the min latitude component of a bounding box to limit the search to. Requires all other boundary.rect parameters to be specified.
Defines the max latitude component of a bounding box to limit the search to. Requires all other boundary.rect parameters to be specified.
Defines the min longitude component of a bounding box to limit the search to. Requires all other boundary.rect parameters to be specified.
Defines the max longitude component of a bounding box to limit the search to. Requires all other boundary.rect parameters to be specified.
The latitude of the center of a circle to limit the search to. Requires boundary.circle.lon.
The longitude of the center of a circle to limit the search to. Requires boundary.circle.lat.
The radius of the circle (in kilometers) to limit the search to. Defaults to 50km (search) or 1km (reverse) if unspecified.
A list of country codes in ISO 3116-1 alpha-2 or alpha-3 format.
The GID of an area to limit the search to.
A list of layers to limit the search to.
A list of sources to limit the search to.
The maximum number of results to return.
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.
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"
}