Skip to content

Place Lookup





Most components of each geocoding response include a unique identifier in the form of a gid. For example, if you search for an address, you may want to find out more about the localadmin. You can get more information by looking up the result's localadmin_gid with the place endpoint.


Example Code


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: "" });
// const api = new GeocodingApi(config);
const api = new GeocodingApi();

const res = await{ ids: ["openstreetmap:address:way/109867749"] });
import os
import stadiamaps
from import ApiException

# You can also use our EU endpoint to keep traffic within the EU like so:
# configuration = stadiamaps.Configuration(host="")
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)

        res =["openstreetmap:address:way/109867749"])
    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
// You can also use our EU endpoint to keep traffic within the EU like so:
// val client = ApiClient(baseUrl = "")
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(

// 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 ="openstreetmap:address:way/109867749")).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 = ""

// 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:
func myFunction() async throws {
    let res = try await ["openstreetmap:address:way/109867749"])

    // Do something with the response...
curl ""
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
ids comma-delimited string array yes A list of Pelias GIDs to search for. none whosonfirst:borough:421205771

Notes and tips

  • Not all types of data have searchable GIDs. For example, interpolated addresses are derived data and are not searchable (but other attributes of the response, such as the localadmin and region generally will). Specifically, only GIDs of type osm, oa, gn, wof, openaddresses, openstreetmap, geonames, whosonfirst are searchable.
  • Some sources do not guarantee stability of IDs over time, so caching them may lead to unexpected results. In general, Geonames and Who's on First are more curated and try to ensure IDs remain stable, but OpenAddresses and OpenStreetMap IDs are inherently unstable.

Response format

All geocoding, autocomplete, and search endpoints share a common response format. See the response format documentation for details. This endpoint will likely be extended in the future.

Next Steps