Warning

This documentation covers a service that is currently in public beta. While we make a reasonable effort to ensure that things stay online, our beta services are not subject to the same availability guarantees of our other services. Additionally, beta services may not have the same global redundancy as our other services, so latency may be higher.

You will not be charged for beta access. If you continue using the service once it goes live, you will be charged as usual per the terms of our public pricing or your enterprise agreement.

Please send any feedback and issue reports to betafeedback@stadiamaps.com.

Structured Search¶

Free

Starter

Standard

Professional

The structured search endpoint lets you search for addresses or places. Rather than using a single string and leaving the API to infer meaning, the structured endpoint puts you in control of the parsing.

Endpoint: https://api.stadiamaps.com/geocoding/v1/search/structured

Query String Parameters¶

Parameter	Type	Required	Description	Default	Example
`address`	string	no	A street name, optionally with a house number.	none	`11 Wall Street`
`neighbourhood`	string	no	Varies by area, but has a locally specific meaning (may not always be an administrative unit).	none	`Financial District`
`borough`	string	no	A unit within a city (not widely used, but present in places such as NYC and Mexico City).	none	`Manhattan`
`locality`	string	no	The city, village, town, etc. that the place / address is part of.	none	`New York`
`county`	string	no	Administrative divisions between localities and regions. Not commonly used as input to structured geocoding.	none	`New York County`
`region`	string	no	Typically the first administrative division within a country. For example, a US state or a Canadian province.	none	`New York`
`postalcode`	string	no	A mail sorting code; format varies by area.	none	`10005`
`country`	string (full name, ISO 3116-1 alpha-2 or alpha-3)	no	A full name (ex: Canada), or a 2 or 3 character ISO code. Prefer ISO codes when possible.	none	`United States`
`focus.point.lat`	float	no	The latitude of the point to focus the search on. This will bias results toward the focus point. Requires `focus.point.lon`	none	`48.581755`
`focus.point.lon`	float	no	The longitude of the point to focus the search on. This will bias results toward the focus point. Requires `focus.point.lat`	none	`7.745843`
`boundary.rect.min_lon`	float	no	Defines the min longitude component of a bounding box to limit the search to. Requires all other `boundary.rect` parameters to be specified.	none	`139.2794`
`boundary.rect.max_lon`	float	no	Defines the max longitude component of a bounding box to limit the search to. Requires all other `boundary.rect` parameters to be specified.	none	`140.1471`
`boundary.rect.min_lat`	float	no	Defines the min latitude component of a bounding box to limit the search to. Requires all other `boundary.rect` parameters to be specified.	none	`35.53308`
`boundary.rect.max_lat`	float	no	Defines the max latitude component of a bounding box to limit the search to. Requires all other `boundary.rect` parameters to be specified.	none	`35.81346`
`boundary.circle.lat`	float	no	The latitude of the center of a circle to limit the search to. Requires `boundary.circle.lon`.	none	`43.818156`
`boundary.circle.lon`	float	no	The latitude of the center of a circle to limit the search to. Requires `boundary.circle.lat`.	none	`-79.186484`
`boundary.circle.radius`	float	no	Tho radius of the circle (in kilometers) to limit the search to. Requires the other `boundary.circle` parameters to take effect.	`50`	`35`
`layers`	comma-delimited string array	no	A list of layers, to limit the search to.	all layers	`address,venue`
`sources`	comma-delimited string array	no	A list of sources, to limit the search to.	all sources	`openstreetmap,wof`
`boundary.country`	comma-delimited string array	no	A list of countries to limit the search to.	none	`GBR,FRA`
`boundary.gid`	Pelias GID	no	The Pelias GID of a region to limit the search to.	none	`whosonfirst:locality:101748355`
`size`	integer	no	The maximum number of results to return.	`10`	`3`

Notes and tips¶

While all fields are technically marked as optional, you will probably get the best results if you include address, region, postalcode, and country. (Why not locality? Sometimes these do not match up with postal addresses; experiment with what works for your use case.)
Be sure to read Determining Result Quality and our best practices

Response format¶

All geocoding, autocomplete, and search endpoints share a common response format. See the response format documentation for details.