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.
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.
Ready-to-go Integrations¶
These pre-built UI components help you get started easily with popular frameworks! This should dramatically speed up your development and let you focus on building a great app rather than technical details like throttling and input debouncing.
Platform | Description | |
---|---|---|
MapLibre GL JS | Official Stadia Maps plugin for MapLibre GL JS | Get Started |
SwiftUI | Official Stadia Maps autocomplete search view for SwiftUI | Get Started |
Leaflet | Leaflet plugin from Pelias, which is compatible with our API | Get it on GitHub |
Using the API Directly¶
If the ready-to-go integrations don't cover for your use case, you can build your own autocomplete search integration using the API directly. Here is some example code to get you started.
Example Code¶
Installation Instructions
The Stadia Maps JavaScript/TypeScript SDK is available for any package manager that supports the npm registry.
npm install @stadiamaps/api
yarn add @stadiamaps/api
bun add @stadiamaps/api
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" }); (1)
// 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" });
- Learn how to get an API key in our authentication guide.
Installation Instructions
The Stadia Maps Python SDK is available through any package manager that supports PyPi.
pip install stadiamaps
poetry add stadiamaps
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). (1)
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)
- Learn how to get an API key in our authentication guide.
Installation Instructions
If aren't already using Maven Central, add the repository in your Gradle build script.
repositories {
mavenCentral()
}
Then, add the API package and its dependencies.
dependencies {
val retrofitVersion = "2.11.0"
// API package
implementation("com.stadiamaps:api:3.2.1")
// Dependencies
implementation("com.squareup.moshi:moshi-kotlin:1.14.0")
implementation("com.squareup.moshi:moshi-adapters:1.14.0")
implementation("com.squareup.okhttp3:logging-interceptor:4.10.0")
implementation("com.squareup.retrofit2:retrofit:$retrofitVersion")
implementation("com.squareup.retrofit2:converter-moshi:$retrofitVersion")
implementation("com.squareup.retrofit2:converter-scalars:$retrofitVersion")
}
dependencies {
def retrofitVersion = "2.11.0"
// API package
implementation 'com.stadiamaps:api:3.2.1'
// Dependencies
implementation 'com.squareup.moshi:moshi-kotlin:1.15.1'
implementation 'com.squareup.moshi:moshi-adapters:1.15.1'
implementation 'com.squareup.okhttp3:logging-interceptor:4.10.0'
implementation "com.squareup.retrofit2:retrofit:${retrofitVersion}"
implementation "com.squareup.retrofit2:converter-moshi:${retrofitVersion}"
implementation "com.squareup.retrofit2:converter-scalars:${retrofitVersion}"
}
Our API package is available on Maven Central.
All you need to do is add a few dependencies to your pom.xml
.
<properties>
<retrofit.version>2.9.0</retrofit.version>
</properties>
<dependencies>
<!-- API package -->
<dependency>
<groupId>com.stadiamaps</groupId>
<artifactId>api</artifactId>
<version>3.2.1</version>
</dependency>
<!-- Dependencies -->
<dependency>
<groupId>com.squareup.moshi</groupId>
<artifactId>moshi-kotlin</artifactId>
<version>1.15.1</version>
</dependency>
<dependency>
<groupId>com.squareup.moshi</groupId>
<artifactId>moshi-adapters</artifactId>
<version>1.15.1</version>
</dependency>
<dependency>
<groupId>com.squareup.okhttp3</groupId>
<artifactId>logging-interceptor</artifactId>
<version>4.10.0</version>
</dependency>
<dependency>
<groupId>com.squareup.retrofit2</groupId>
<artifactId>retrofit</artifactId>
<version>${retrofit.version}</version>
</dependency>
<dependency>
<groupId>com.squareup.retrofit2</groupId>
<artifactId>converter-moshi</artifactId>
<version>${retrofit.version}</version>
</dependency>
<dependency>
<groupId>com.squareup.retrofit2</groupId>
<artifactId>converter-scalars</artifactId>
<version>${retrofit.version}</version>
</dependency>
</dependencies>
// 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) (1)
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: this code is blocking for demonstration purposes.
// If you're using Kotlin with coroutines,
// you can also use these asynchronously within suspend functions.
// Synchronous code can enqueue a callback to avoid blocking
// (you'll definitely want to do one of these instead when on the main thread of an app).
// See the docs for details: https://square.github.io/retrofit/2.x/retrofit/retrofit2/Call.html
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()}")
}
- Learn how to get an API key in our authentication guide.
Installation Instructions
Our Swift SDK is distributed using the Swift Package Manager (SPM).
Apple's documentation
shows how to add a Swift Package dependency to your Xcode project.
On the Add Package screen, you can find our package by its repository URL: https://github.com/stadiamaps/stadiamaps-api-swift
.
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 (1)
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)
}
- Learn how to get an API key in our authentication guide.
Installation Instructions
Composer
To install the package via Composer,
add stadiamaps/stadiamaps-api-php
to your composer.json
:
{
"require": {
"stadiamaps/stadiamaps-api-php": "1.*"
}
}
Then run composer install
.
Manual Installation
You can also download the files manually and include autoload.php
in your scripts:
<?php
require_once('/path/to/OpenAPIClient-php/vendor/autoload.php');
<?php
// use or require, depending on your installation method.
// Configure API key authorization (replace with your Stadia Maps API key) (1)
$config = OpenAPI\Client\Configuration::getDefaultConfiguration()->setApiKey('api_key', 'YOUR-API-KEY');
// You can also use our EU endpoint to keep traffic within the EU using setHost:
// $config = Configuration::getDefaultConfiguration()->setApiKey('api_key', 'YOUR-API-KEY')->setHost('https://api-eu.stadiamaps.com');
$apiInstance = new OpenAPI\Client\Api\GeocodingApi(
new GuzzleHttp\Client(),
$config
);
try {
$result = $apiInstance->autocomplete('Põhja pst 27');
} catch (Exception $e) {
// Add your error handling here
echo 'Exception when calling the Stadia Maps API: ', $e->getMessage(), PHP_EOL;
}
- Learn how to get an API key in our authentication guide.
curl "https://api.stadiamaps.com/geocoding/v1/autocomplete?text=P%C3%B5hja%20pst%2027&api_key=YOUR-API-KEY"
Can I Store 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 ready-to-go integrations usually 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.