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.

Autocomplete¶

Free

Starter

Standard

Professional

The autocomplete endpoint enables search-as-you-type applications, and can return addresses, points of interest, and administrative areas.

The only required parameter is text, but the results can be easily tuned to meet your needs.

Bias results with the focus.point parameters
Ignore anything outside a bounding box, circle, or country using the boundary parameters
Limit the data sources searched using the sources parameter
Limit the layers searched using the layers parameter

Endpoint: https://api.stadiamaps.com/geocoding/v1/autocomplete

Query String Parameters¶

Parameter	Type	Required	Description	Default	Example
`text`	string	yes	The place name (address, venue name, etc.) to search for.	none	`Union Square`
`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¶

Avoid sending extremely short queries. A good rule of thumb is to have your application wait for two or three characters of user input before sending a query. Allowing shorter queries can make sense for some applications (ex: postal code search in a small region), but when in doubt, stick to the rule of thumb.
We recommend throttling and debouncing of some sort. We intend to offer an SDK for this in the near future so that you don't have to worry about on major platform.
Responses are not guaranteed to be received in the order requested. Your application is responsible for handling out-of-order responses.
Specify only the layers you need to improve relevance and performance. layers=coarse in particular is useful if you don't need venues or addresses.
If you are using Leaflet, the Pelias Leaflet Plugin is a quick way to get started with an autocomplete search box. We intend release official plugins for Leaflet and MapLibre after beta.

Response format¶

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