openapi: 3.0.3
info:
description: 'Confidently create beautiful maps for all your users with our tools. Choose your style from our library or build your own. With a rich palette of choices to fit any context and support for dozens of languages and scripts, you can deliver a quality experience for your customers no matter what part of the globe they call home. '
version: 7.1.0
title: Stadia Maps Autocomplete API
contact:
name: Stadia Maps Support
url: https://www.stadiamaps.com
email: support@stadiamaps.com
servers:
- url: https://api.stadiamaps.com
- url: https://api-eu.stadiamaps.com
tags:
- name: Autocomplete
paths:
/geocoding/v1/autocomplete:
get:
tags:
- Autocomplete
operationId: autocomplete
summary: Search and geocode quickly based on partial input.
description: Autocomplete enables interactive search-as-you-type user experiences, suggesting places as you type, along with information that will help your users find the correct place quickly.
security:
- ApiKeyAuth: []
parameters:
- $ref: '#/components/parameters/searchText'
- $ref: '#/components/parameters/searchFocusLat'
- $ref: '#/components/parameters/searchFocusLon'
- $ref: '#/components/parameters/searchBoundaryRectMinLat'
- $ref: '#/components/parameters/searchBoundaryRectMaxLat'
- $ref: '#/components/parameters/searchBoundaryRectMinLon'
- $ref: '#/components/parameters/searchBoundaryRectMaxLon'
- $ref: '#/components/parameters/searchBoundaryCircleLat'
- $ref: '#/components/parameters/searchBoundaryCircleLon'
- $ref: '#/components/parameters/searchBoundaryCircleRadius'
- $ref: '#/components/parameters/searchBoundaryCountry'
- $ref: '#/components/parameters/searchBoundaryGID'
- $ref: '#/components/parameters/searchLayers'
- $ref: '#/components/parameters/searchSources'
- $ref: '#/components/parameters/size'
- $ref: '#/components/parameters/peliasLang'
responses:
'200':
description: A GeoJSON collection of autocomplete search results.
content:
application/json:
schema:
$ref: '#/components/schemas/peliasResponse'
'400':
description: Bad request
components:
parameters:
peliasLang:
name: lang
in: query
schema:
$ref: '#/components/schemas/peliasLang'
description: A BCP47 language tag which specifies a preference for localization of results. By default, results are in the default locale of the source data, but specifying a language will attempt to localize the results. Note that while a `langtag` (in RFC 5646 terms) can contain script, region, etc., only the `language` portion, an ISO 639 code, will be considered. So `en-US` and `en-GB` will both be treated as English.
searchBoundaryCircleRadius:
name: boundary.circle.radius
in: query
schema:
$ref: '#/components/schemas/searchBoundaryCircleRadius'
description: The radius of the circle (in kilometers) to limit the search to. Defaults to 50km if unspecified.
searchFocusLat:
name: focus.point.lat
in: query
schema:
$ref: '#/components/schemas/searchFocusLat'
description: The latitude of the point to focus the search on. This will bias results toward the focus point. Requires `focus.point.lon`.
required: false
searchBoundaryGID:
name: boundary.gid
in: query
schema:
$ref: '#/components/schemas/searchBoundaryGID'
description: The Pelias GID of an area to limit the search to.
searchBoundaryRectMinLat:
name: boundary.rect.min_lat
in: query
schema:
$ref: '#/components/schemas/searchBoundaryRectMinLat'
description: Defines the min latitude component of a bounding box to limit the search to. Requires all other `boundary.rect` parameters to be specified.
required: false
size:
name: size
in: query
schema:
$ref: '#/components/schemas/limit'
description: The maximum number of results to return.
searchFocusLon:
name: focus.point.lon
in: query
schema:
$ref: '#/components/schemas/searchFocusLon'
description: The longitude of the point to focus the search on. This will bias results toward the focus point. Requires `focus.point.lat`.
required: false
searchBoundaryCountry:
name: boundary.country
in: query
schema:
$ref: '#/components/schemas/searchBoundaryCountry'
description: 'A list of countries to limit the search to. These may be either full names (ex: Canada), or an ISO 3116-1 alpha-2 or alpha-3 code. Prefer ISO codes when possible.'
style: form
explode: false
searchText:
name: text
in: query
schema:
$ref: '#/components/schemas/searchText'
description: The place name (address, venue name, etc.) to search for.
required: true
searchSources:
name: sources
in: query
schema:
$ref: '#/components/schemas/searchSources'
description: A list of sources to limit the search to.
style: form
explode: false
searchBoundaryRectMinLon:
name: boundary.rect.min_lon
in: query
schema:
$ref: '#/components/schemas/searchBoundaryRectMinLon'
description: Defines the min longitude component of a bounding box to limit the search to. Requires all other `boundary.rect` parameters to be specified.
required: false
searchLayers:
name: layers
in: query
schema:
$ref: '#/components/schemas/searchLayers'
description: A list of layers to limit the search to.
style: form
explode: false
searchBoundaryCircleLat:
name: boundary.circle.lat
in: query
schema:
$ref: '#/components/schemas/searchBoundaryCircleLat'
description: The latitude of the center of a circle to limit the search to. Requires `boundary.circle.lon`.
searchBoundaryRectMaxLat:
name: boundary.rect.max_lat
in: query
schema:
$ref: '#/components/schemas/searchBoundaryRectMaxLat'
description: Defines the max latitude component of a bounding box to limit the search to. Requires all other `boundary.rect` parameters to be specified.
required: false
searchBoundaryRectMaxLon:
name: boundary.rect.max_lon
in: query
schema:
$ref: '#/components/schemas/searchBoundaryRectMaxLon'
description: Defines the max longitude component of a bounding box to limit the search to. Requires all other `boundary.rect` parameters to be specified.
required: false
searchBoundaryCircleLon:
name: boundary.circle.lon
in: query
schema:
$ref: '#/components/schemas/searchBoundaryCircleLon'
description: The longitude of the center of a circle to limit the search to. Requires `boundary.circle.lat`.
schemas:
limit:
type: integer
description: The maximum number of results to return.
peliasLayer:
type: string
enum:
- venue
- address
- street
- country
- macroregion
- region
- macrocounty
- county
- locality
- localadmin
- borough
- neighbourhood
- postalcode
- coarse
- dependency
- macrohood
- marinearea
- disputed
- empire
- continent
- ocean
description: 'Our database is organized into several layers (in the GIS sense of the term) as follows:
- `venue`: Points of interest, businesses, and things with walls
- `address`: Places with a street address
- `street`: Streets, roads, highways
- `county`: Places that issue passports, nations, nation-states
- `macroregion`: A related group of regions (mostly in Europe)
- `region`: The first administrative division within a country (usually states and provinces)
- `macrocounty`: A related group of counties (mostly in Europe)
- `county`: Official governmental areas; usually bigger than a locality, but almost always smaller than a region
- `locality`: Towns, hamlets, cities, etc.
- `localadmin`: Local administrative boundaries
- `borough`: Local administrative boundaries within cities (not widely used, but present in places such as NYC and Mexico City)
- `neighbourhood`: Social communities and neighborhoods (note the British spelling in the API!)
- `postalcode`: Postal codes used by mail services (note: not used for reverse geocoding)
- `coarse`: An alias for simultaneously using all administrative layers (everything except `venue` and `address`)
- `marinearea`: Places with fishes and boats.
- `ocean`: A really big marine area.
'
peliasGeoJSONFeature:
type: object
required:
- type
- geometry
properties:
type:
type: string
enum:
- Feature
geometry:
$ref: '#/components/schemas/geoJSONPoint'
properties:
$ref: '#/components/schemas/peliasGeoJSONProperties'
bbox:
type: array
minItems: 4
maxItems: 4
items:
type: number
format: double
description: An array of 4 floating point numbers representing the (W, S, E, N) extremes of the features found.
searchBoundaryCountry:
type: array
items:
type: string
description: 'A list of countries to limit the search to. These may be either full names (ex: Canada), or an ISO 3116-1 alpha-2 or alpha-3 code. Prefer ISO codes when possible.'
searchFocusLon:
type: number
description: The longitude of the point to focus the search on. This will bias results toward the focus point. Requires `focus.point.lat`.
format: double
minimum: -180
maximum: 180
peliasResponse:
type: object
properties:
geocoding:
allOf:
- $ref: '#/components/schemas/geocodingObject'
bbox:
type: array
minItems: 4
maxItems: 4
items:
type: number
format: double
description: An array of 4 floating point numbers representing the (W, S, E, N) extremes of the features found.
features:
type: array
items:
$ref: '#/components/schemas/peliasGeoJSONFeature'
required:
- geocoding
- features
example:
geocoding:
version: '0.2'
attribution: https://stadiamaps.com/attribution
query:
text: 1600 Pennsylvania Ave NW
size: 10
private: false
lang:
name: English
iso6391: en
iso6393: eng
via: default
defaulted: true
querySize: 20
parser: libpostal
parsed_text:
housenumber: '1600'
street: pennsylvania ave nw
engine:
name: Pelias
author: Mapzen
version: '1.0'
timestamp: 1679043782383
type: FeatureCollection
features:
- type: Feature
geometry:
type: Point
coordinates:
- -77.036547
- 38.897675
properties:
id: us/dc/statewide:aa53d4bd0fe295be
gid: openaddresses:address:us/dc/statewide:aa53d4bd0fe295be
layer: address
source: openaddresses
source_id: us/dc/statewide:aa53d4bd0fe295be
country_code: US
name: 1600 Pennsylvania Avenue NW
housenumber: '1600'
street: Pennsylvania Avenue NW
postalcode: '20500'
confidence: 1
match_type: exact
accuracy: point
country: United States
country_gid: whosonfirst:country:85633793
country_a: USA
region: District of Columbia
region_gid: whosonfirst:region:85688741
region_a: DC
county: District of Columbia
county_gid: whosonfirst:county:1377370667
county_a: DI
locality: Washington
locality_gid: whosonfirst:locality:85931779
neighbourhood: White House Grounds
neighbourhood_gid: whosonfirst:neighbourhood:1108724059
continent: North America
continent_gid: whosonfirst:continent:102191575
label: 1600 Pennsylvania Avenue NW, Washington, DC, USA
bbox:
- -77.036547
- 38.897675
- -77.036547
- 38.897675
peliasSource:
type: string
enum:
- openstreetmap
- openaddresses
- whosonfirst
- geonames
description: Our database contains info from multiple sources. These identifiers can be used to either limit search results or to determine the relevance of a result.
geoJSONGeometryBase:
type: object
required:
- type
properties:
type:
type: string
enum:
- Point
- MultiPoint
- LineString
- MultiLineString
- Polygon
- MultiPolygon
searchBoundaryCircleRadius:
type: number
description: The radius of the circle (in kilometers) to limit the search to. Defaults to 50km if unspecified.
format: double
searchBoundaryCircleLon:
type: number
description: The longitude of the center of a circle to limit the search to. Requires `boundary.circle.lat`.
format: double
minimum: -180
maximum: 180
searchLayers:
type: array
description: A list of layers to limit the search to.
items:
$ref: '#/components/schemas/peliasLayer'
peliasGeoJSONProperties:
type: object
additionalProperties: true
properties:
gid:
type: string
description: A scoped GID for this result. This can be passed to the place endpoint. Note that these are not always stable. For Geonames and Who's on First, these are usually stable, but for other sources like OSM, no stability is guaranteed.
source_id:
type: string
description: An ID referencing the original data source (specified via source) for the result. These IDs are specific to the source that they originated from. For example, in the case of OSM, these typically look like way/123 or point/123.
label:
type: string
description: 'A full, human-readable label. However, you may not necessarily want to use this; be sure to read the docs for name, locality, and region before making a decision. This field is mostly localized. The order of components is generally locally correct (ex: for an address in South Korea, the house number appears after the street name). However, components will use a request language equivalent if one exists (ex: Seoul instead of � if lang=en).'
layer:
$ref: '#/components/schemas/peliasLayer'
name:
type: string
description: The name of the place, the street address including house number, or label of similar relevance. If your app is localized to a specific region, you may get better display results by combining name, locality OR region (or neither?), and postal code together in the local format. Experiment with what works best for your use case.
accuracy:
type: string
enum:
- point
- centroid
description: 'The accuracy of the geographic coordinates in the result. This value is a property of the result itself and won''t change based on the query.
A point result means that the record can reasonably be represented by a single geographic point. Addresses, venues, or interpolated addresses usually have point accuracy.
Larger areas, such as a city or country, cannot be represented by a single point, so a centroid is given instead.'
addendum:
type: object
additionalProperties: true
description: 'Optional additional information from the underlying data source (ex: OSM). This includes select fields. The most useful fields are mapped in the definition here, but others may be available.'
properties:
osm:
type: object
additionalProperties: true
properties:
website:
type: string
format: uri
wikipedia:
type: string
wikidata:
type: string
phone:
type: string
continent:
type: string
continent_gid:
type: string
country:
type: string
country_gid:
type: string
neighbourhood:
type: string
neighbourhood_gid:
type: string
borough:
type: string
borough_gid:
type: string
postalcode:
type: string
street:
type: string
housenumber:
type: string
locality:
type: string
description: The city, village, town, etc. that the place / address is part of. Note that values may not always match postal or local conventions perfectly.
locality_gid:
type: string
county:
type: string
description: Administrative divisions between localities and regions. Useful for disambiguating nearby results with similar names.
region:
type: string
description: Typically the first administrative division within a country. For example, a US state or a Canadian province.
region_a:
type: string
description: The abbreviation for the region.
searchBoundaryGID:
type: string
description: The Pelias GID of an area to limit the search to.
searchSources:
type: array
description: A list of sources to limit the search to.
items:
$ref: '#/components/schemas/peliasSource'
searchBoundaryRectMaxLat:
type: number
description: Defines the max latitude component of a bounding box to limit the search to. Requires all other `boundary.rect` parameters to be specified.
format: double
minimum: -90
maximum: 90
searchFocusLat:
type: number
description: The latitude of the point to focus the search on. This will bias results toward the focus point. Requires `focus.point.lon`.
format: double
minimum: -90
maximum: 90
searchBoundaryRectMinLat:
type: number
description: Defines the min latitude component of a bounding box to limit the search to. Requires all other `boundary.rect` parameters to be specified.
format: double
minimum: -90
maximum: 90
geoJSONPoint:
allOf:
- $ref: '#/components/schemas/geoJSONGeometryBase'
- type: object
required:
- coordinates
properties:
coordinates:
type: array
minItems: 2
maxItems: 3
items:
type: number
format: double
searchBoundaryRectMaxLon:
type: number
description: Defines the max longitude component of a bounding box to limit the search to. Requires all other `boundary.rect` parameters to be specified.
format: double
minimum: -180
maximum: 180
searchBoundaryRectMinLon:
type: number
description: Defines the min longitude component of a bounding box to limit the search to. Requires all other `boundary.rect` parameters to be specified.
format: double
minimum: -180
maximum: 180
peliasLang:
type: string
description: A BCP47 language tag which specifies a preference for localization of results. By default, results are in the default locale of the source data, but specifying a language will attempt to localize the results. Note that while a `langtag` (in RFC 5646 terms) can contain script, region, etc., only the `language` portion, an ISO 639 code, will be considered. So `en-US` and `en-GB` will both be treated as English.
geocodingObject:
type: object
properties:
attribution:
type: string
format: uri
description: A URL containing attribution information. If you are not using Stadia Maps and our standard attribution already for your basemaps, you must include this attribution link somewhere in your website/app.
query:
type: object
additionalProperties: true
description: Technical details of the query. This is most useful for debugging during development. See the full example for the list of properties; these should be self-explanatory, so we don't enumerate them in the spec.
warnings:
type: array
items:
type: string
description: An array of non-critical warnings. This is normally for informational/debugging purposes and not a serious problem.
errors:
type: array
items:
type: string
description: An array of more serious errors (for example, omitting a required parameter). Dont ignore these.
searchBoundaryCircleLat:
type: number
description: The latitude of the center of a circle to limit the search to. Requires `boundary.circle.lon`.
format: double
minimum: -90
maximum: 90
searchText:
type: string
description: The place name (address, venue name, etc.) to search for.
example: 1600 Pennsylvania Ave NW
securitySchemes:
ApiKeyAuth:
type: apiKey
in: query
name: api_key