Skip to content

Autocomplete Search

Free

Starter

Standard

Professional

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

Animated demonstration of an autocomplete search experience

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

Tip

The autocomplete endpoint is optimized for speed based on potentially incomplete user input. The search (forward geocoding) endpoint will usually yield better results for complete input, and is able to interpolate between addresses where precise results are not available.

Using a plugin will dramatically speed up your development, and the ones recommended below will take care of the tricky bits like throttling and input debouncing.

Platform Description
MapLibre GL JS Official Stadia Maps plugin for MapLibre GL JS Get Started
Leaflet Leaflet plugin from the Pelias team Get it on GitHub

Example Code

Tip

Get started quickly with code samples using our official SDKs or cURL. Official SDKs include documentation of all request and response models, either as separate pages, or through docstrings and autocomplete in most IDEs. If you are building for another language or want to try out requests in a browser, refer to our interactive API reference.

import { GeocodingApi, Configuration } from '@stadiamaps/api';

// If you are writing for a backend application or can't use domain-based auth,
// then you'll need to add your API key like so:
// 
// const config = new Configuration({ apiKey: "YOUR-API-KEY" });
// You can also use our EU endpoint to keep traffic within the EU using the basePath option:
// const config = new Configuration({ basePath: "https://api-eu.stadiamaps.com" });
// const api = new GeocodingApi(config);
const api = new GeocodingApi();

const res = await api.autocomplete({ text: "Põhja pst 27" });
import os
import stadiamaps
from stadiamaps.rest import ApiException

# You can also use our EU endpoint to keep traffic within the EU like so:
# configuration = stadiamaps.Configuration(host="https://api-eu.stadiamaps.com")
configuration = stadiamaps.Configuration()

# Configure API key authentication (ex: via environment variable).
configuration.api_key['ApiKeyAuth'] = os.environ["API_KEY"]

with stadiamaps.ApiClient(configuration) as api_client:
    # Create an instance of the API class
    api_instance = stadiamaps.GeocodingApi(api_client)

    try:
        res = api_instance.autocomplete(text="Põhja pst 27")
    except ApiException as e:
        # Add your error handling here
        print("Exception when calling the Stadia Maps API: %s\n" % e)
// Imports (at the top of your source file; we've used some wildcard imports for simplicity)
import com.stadiamaps.api.apis.*
import com.stadiamaps.api.auth.ApiKeyAuth
import com.stadiamaps.api.infrastructure.*
import com.stadiamaps.api.models.*

// Set your API key (from an environment variable in this case)
val apiKey = System.getenv("STADIA_API_KEY") ?: throw RuntimeException("API Key not set")

// Defining the host is optional and defaults to https://api.stadiamaps.com
// You can also use our EU endpoint to keep traffic within the EU like so:
// val client = ApiClient(baseUrl = "https://api-eu.stadiamaps.com")
val client = ApiClient()
client.addAuthorization("ApiKeyAuth", ApiKeyAuth("query", "api_key", apiKey))

// Configure a service for the group of APIs we want to talk to
val service = client.createService(GeocodingApi::class.java)

// Set up the request. Note: if you're using Kotlin with coroutines, you can also await
// rather than executing synchronously when using suspend functions.
val res = service.autocomplete("Põhja pst 27").execute()

if (res.isSuccessful) {
    println("Found result: ${res.body()}")
} else {
    println("Request failed with error code ${res.code()}")
}
import StadiaMaps

// This setup code can go anywhere before you actually make an API call (typically in your app init)
func setupStadiaMapsAPI() {
    // Set your API key
    StadiaMapsAPI.customHeaders = ["Authorization": "Stadia-Auth YOUR-API-KEY"]
    // Optionally use our EU endpoint to keep traffic within the EU
    // StadiaMapsAPI.basePath = "https://api-eu.stadiamaps.com"
}

// This function demonstrates how to call the Stadia Maps API.
// If you have not yet adopted async/await in your Swift codebase, you can use the Task API
// to call async functions in a non-async context: https://developer.apple.com/documentation/swift/task.
func myFunction() async throws {
    let res = try await GeocodingAPI.autocomplete(text: "Põhja pst 27")

    // Do something with the response...
    print(res)
}
curl "https://api.stadiamaps.com/geocoding/v1/autocomplete?text=P%C3%B5hja%20pst%2027&api_key=YOUR-API-KEY"
Storage of Geocoding API Results

Permanently storing results, in part or in whole, (e.g. in a database) from this API for future use requires an active Standard, Professional, or Enterprise subscription. See our terms of service for the full legal terms.

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
lang string no A BCP47 language tag which specifies a preference for localization of results. none ko

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 or debouncing (or both) for interactive applications. The recommended plugins will handle this automatically.
  • 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.

Response format

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

Next Steps