MapTiler Geocoding API
The Geocoding API from MapTiler — 4 operation(s) for geocoding.
OpenAPI Specification
openapi: 3.1.0
info:
title: MapTiler Coordinates Geocoding API
version: '1.0'
description: "MapTiler API allows you to programmatically access all the data, maps, services, and resources available in your MapTiler account. \n\nAccess to your resources via MapTiler API is read-only, and therefore safe and well suited for public end-user applications. You can use it to add a map directly to your website, request map tiles, create an image with a location map for your business, search for addresses, and more. \n\nThe universal public API request format is:\n\n```\nhttps://api.maptiler.com/{METHOD}/{QUERY}.json?{PARAMS}&key=YOUR_MAPTILER_API_KEY_HERE\n```\n\n> [!KEY]\n> You need a **MapTiler API key** to use this service. [Get it here](https://cloud.maptiler.com/account/keys/){:target=\"_blank\" rel=\"noopener noreferrer\"} and [learn how to protect it](/guides/maps-apis/maps-platform/how-to-protect-your-map-key/).\n"
termsOfService: https://www.maptiler.com/terms/
contact:
name: Support
email: support@maptiler.com
url: https://docs.maptiler.com/support/requests/
premium: https://www.maptiler.com/support/
servers:
- description: MapTiler API
url: https://api.maptiler.com/
security:
- key: []
tags:
- name: Geocoding
paths:
/geocoding/{query}.json:
parameters:
- name: query
in: path
description: Place name to search. You can also use bare [POI category](https://docs.maptiler.com/cloud/api/geocoding/#PoiCategory) or mix it with a name to search for POIs of desired category, unless `poi` index is excluded.
examples:
place:
value: Zurich
summary: Search place name
poi:
value: restaurant mediterranean
summary: Search POI category
required: true
schema:
type: string
- $ref: '#/components/parameters/bbox'
- $ref: '#/components/parameters/proximity'
- $ref: '#/components/parameters/language'
- $ref: '#/components/parameters/country'
- $ref: '#/components/parameters/limit'
- $ref: '#/components/parameters/types'
- $ref: '#/components/parameters/excludeTypes'
- $ref: '#/components/parameters/fuzzyMatch'
- $ref: '#/components/parameters/autocomplete'
- $ref: '#/components/parameters/worldview'
get:
summary: Search by name (forward)
description: Forward <a href="https://www.maptiler.com/cloud/geocoding/">geocoding (search by place name)</a>.
tags:
- Geocoding
responses:
'200':
$ref: '#/components/responses/ok'
'400':
description: Query too long / Invalid parameters
'403':
$ref: '#/components/responses/403'
/geocoding/{longitude},{latitude}.json:
parameters:
- name: longitude
in: path
example: 8.528509
required: true
schema:
type: number
minimum: -180
maximum: 180
- name: latitude
in: path
example: 47.3774434
required: true
schema:
type: number
minimum: -90
maximum: 90
- $ref: '#/components/parameters/language'
- $ref: '#/components/parameters/limit'
- $ref: '#/components/parameters/types'
- $ref: '#/components/parameters/excludeTypes'
- $ref: '#/components/parameters/worldview'
get:
summary: Search by coordinates (reverse)
description: Reverse geocoding (search by coordinates).
tags:
- Geocoding
responses:
'200':
$ref: '#/components/responses/ok'
'400':
description: Query too long / Invalid parameters
'403':
$ref: '#/components/responses/403'
/geocoding/{id}.json:
parameters:
- name: id
in: path
example: country.26561650
required: true
schema:
type: string
pattern: ^(\S+)\.([0-9]+)$
description: Feature ID (found in response of forward or reverse geocoding)
- $ref: '#/components/parameters/language'
- $ref: '#/components/parameters/worldview'
get:
summary: Search by feature ID
description: Search feature by its ID (`id`) as returned in forward or reverse geocoding response and return its full geometry. Note that the feature ID is not stable and it changes when the database is re-indexed.
tags:
- Geocoding
responses:
'200':
$ref: '#/components/responses/ok'
'400':
description: Query too long / Invalid parameters
'403':
$ref: '#/components/responses/403'
/geocoding/{queries}.json:
parameters:
- in: path
name: queries
description: Semicolon-separated list of queries. Semicolon `;` must be provided verbatim and not be URL-encoded. Each query may be forward, reverse or by feature ID. Maximum of 50 queries are supported.
example: Paris;Berlin
required: true
schema:
type: string
- $ref: '#/components/parameters/bbox'
- $ref: '#/components/parameters/proximity'
- $ref: '#/components/parameters/language'
- $ref: '#/components/parameters/country'
- $ref: '#/components/parameters/limit'
- $ref: '#/components/parameters/types'
- $ref: '#/components/parameters/excludeTypes'
- $ref: '#/components/parameters/fuzzyMatch'
- $ref: '#/components/parameters/autocomplete'
- $ref: '#/components/parameters/worldview'
get:
summary: Batch geocoding API
description: Perform geocoding of more than one request in a single API call. Check out the <a href="https://docs.maptiler.com/guides/geocoding/batch-geocoding-api/">Batch Geocoding guide</a> for an example.
tags:
- Geocoding
responses:
'200':
description: Array of geocoding results where items are matching order of queries in the request. Every result is represented as FeatureCollection where every item is represented as a GeoJSON Feature
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/result'
'400':
description: Query too long / Invalid parameters
'403':
$ref: '#/components/responses/403'
components:
schemas:
placeType:
type: string
title: PlaceType
description: Check out the [descriptions and default values](https://docs.maptiler.com/cloud/api/geocoding/#PlaceTypeValues) of each of the PlaceType values
enum:
- continental_marine
- country
- major_landform
- region
- subregion
- county
- joint_municipality
- joint_submunicipality
- municipality
- municipal_district
- locality
- neighbourhood
- place
- postal_code
- address
- road
- poi
bbox:
example:
- 5.9559
- 45.818
- 10.4921
- 47.8084
type: array
title: BoundingBox
prefixItems:
- type: number
minimum: -180
maximum: 180
description: minimal longitude
- type: number
minimum: -90
maximum: 90
description: minimal latitude
- type: number
minimum: -180
maximum: 180
description: maximal longitude
- type: number
minimum: -90
maximum: 90
description: maximal latitude
featureProperties:
title: FeatureProperties
type: object
additionalProperties: true
properties:
ref:
description: (experimental) External reference of the feature used for debugging purposes. The exact format of this field may change without notice, and should not be relied on at the moment.
type: string
example: osm:r71525
country_code:
type: string
description: ISO 3166-1 alpha-2 country code of the feature
example: fr
kind:
type: string
description: (experimental) Kind of the feature
enum:
- road
- road_relation
- admin_area
- place
- street
- virtual_street
categories:
type: array
description: Array of [POI category](https://docs.maptiler.com/cloud/api/geocoding/#PoiCategory). Only available for `poi` type. Category values may change in the near future.
minItems: 1
items:
type: string
example: restaurant
feature_tags:
type: object
title: Feature tags
description: (experimental) Feature tags, only available for `poi` type. They can include e.g. working hours, type of amenity or wheelchair access.
additionalProperties:
type: string
place_designation:
type: string
title: Place designation
description: (experimental) Additional information about the place. The main use case is to determine if the administrative area represents a town, a city or a village. This field is especially useful in cases, where a large city is a region, land or prefecture from administrative point of view (typical examples are Berlin and Tokyo).
example: city
required:
- ref
- country_code
ip:
type: string
title: IP
description: Server-side IP based geolocation
const: ip
commonProperties:
title: CommonProperties
type: object
additionalProperties: true
properties:
id:
description: Unique feature ID
type: string
example: municipality.46425
text:
description: Localized feature name
type: string
example: Paris
language:
description: Query's primary ISO 639-1 language code
type: string
example: en
patternProperties:
^text_(\w\w):
type: string
description: A string analogous to the `text` field that matches the query in the requested language. This field is only returned when multiple languages are requested using the `language` parameter, and will be present for each requested language.
^language_(\w\w):
type: string
description: A ISO 639-1 query's fallback language code. This field is only returned when multiple languages are requested using the `language` parameter, and will be present for each requested language.
required:
- id
- text
coordinates:
example:
- 8.528509
- 47.3774434
type: array
title: Coordinates
prefixItems:
- type: number
minimum: -180
maximum: 180
description: longitude
- type: number
minimum: -90
maximum: 90
description: latitude
result:
description: Search result represented by FeatureCollection where every item is represented as a GeoJSON Feature
type: object
title: SearchResults
properties:
type:
type: string
const: FeatureCollection
features:
description: Array of features found
type: array
title: Feature
items:
allOf:
- $ref: '#/components/schemas/commonProperties'
- type: object
patternProperties:
^place_name_(\w\w):
type: string
description: A string analogous to the `place_name` field that matches the query in the requested language. This field is only returned when multiple languages are requested using the `language` parameter, and will be present for each requested language.
properties:
type:
type: string
const: Feature
properties:
description: Feature properties
$ref: '#/components/schemas/featureProperties'
geometry:
anyOf:
- type: object
title: Point
properties:
type:
type: string
const: Point
coordinates:
$ref: '#/components/schemas/coordinates'
required:
- type
- coordinates
- type: object
title: LineString
properties:
type:
type: string
const: LineString
coordinates:
minItems: 2
type: array
items:
$ref: '#/components/schemas/coordinates'
required:
- type
- coordinates
- type: object
title: Polygon
properties:
type:
type: string
const: Polygon
coordinates:
type: array
items:
minItems: 4
type: array
items:
$ref: '#/components/schemas/coordinates'
required:
- type
- coordinates
- type: object
title: MultiPoint
properties:
type:
type: string
const: MultiPoint
coordinates:
type: array
items:
$ref: '#/components/schemas/coordinates'
required:
- type
- coordinates
- type: object
title: MultiLineString
properties:
type:
type: string
const: MultiLineString
coordinates:
type: array
items:
minItems: 2
type: array
items:
$ref: '#/components/schemas/coordinates'
required:
- type
- coordinates
- type: object
title: MultiPolygon
properties:
type:
type: string
const: MultiPolygon
coordinates:
type: array
items:
type: array
items:
minItems: 4
type: array
items:
$ref: '#/components/schemas/coordinates'
required:
- type
- coordinates
- type: object
title: GeometryCollection
properties:
type:
type: string
const: GeometryCollection
geometries:
type: array
items:
anyOf:
- type: object
title: Point
properties:
type:
type: string
const: Point
coordinates:
$ref: '#/components/schemas/coordinates'
required:
- type
- coordinates
- type: object
title: LineString
properties:
type:
type: string
const: LineString
coordinates:
minItems: 2
type: array
items:
$ref: '#/components/schemas/coordinates'
required:
- type
- coordinates
- type: object
title: Polygon
properties:
type:
type: string
const: Polygon
coordinates:
type: array
items:
minItems: 4
type: array
items:
$ref: '#/components/schemas/coordinates'
required:
- type
- coordinates
- type: object
title: MultiPoint
properties:
type:
type: string
const: MultiPoint
coordinates:
type: array
items:
$ref: '#/components/schemas/coordinates'
required:
- type
- coordinates
- type: object
title: MultiLineString
properties:
type:
type: string
const: MultiLineString
coordinates:
type: array
items:
minItems: 2
type: array
items:
$ref: '#/components/schemas/coordinates'
required:
- type
- coordinates
- type: object
title: MultiPolygon
properties:
type:
type: string
const: MultiPolygon
coordinates:
type: array
items:
type: array
items:
minItems: 4
type: array
items:
$ref: '#/components/schemas/coordinates'
required:
- type
- coordinates
required:
- type
- geometries
bbox:
description: Bounding box of the original feature as `[w, s, e, n]` array
$ref: '#/components/schemas/bbox'
center:
description: A `[lon, lat]` array of the original feature centeroid
$ref: '#/components/schemas/coordinates'
place_name:
description: Formatted (including the hierarchy) and localized feature full name
type: string
matching_place_name:
description: A string analogous to the `place_name` field that matches the query. This field is only returned to help you understand how the response aligns with the submitted query.
type: string
matching_text:
description: A string analogous to the `text` field that matches the query. This field is only returned to help you understand how the response aligns with the submitted query.
type: string
place_type:
description: An array of feature types describing the feature. Currently each feature has only single type but this may change in the future.
type: array
items:
$ref: '#/components/schemas/placeType'
place_type_name:
type: array
description: Localized type of the place name, matches `place_type` property.
items:
type: string
relevance:
description: Indicates how well the returned feature matches the user's query on a scale from 0 to 1. 0 means the result does not match the query text at all, while 1 means the result fully matches the query text. You can use the relevance property to remove results that don't fully match the query.
type: number
context:
description: Feature hierarchy
type: array
title: Context
items:
allOf:
- $ref: '#/components/schemas/featureProperties'
- $ref: '#/components/schemas/commonProperties'
address:
description: Address number, if applicable
type: string
required:
- type
- properties
- geometry
- bbox
- center
- place_name
- place_type
- place_type_name
- relevance
query:
description: Tokenized search query
type: array
items:
type: string
attribution:
description: Attribution of the result
type: string
example: <a href="https://www.maptiler.com/copyright/" target="_blank">© MapTiler</a> <a href="https://www.openstreetmap.org/copyright" target="_blank">© OpenStreetMap contributors</a>
required:
- type
- features
- query
- attribution
parameters:
fuzzyMatch:
schema:
type: boolean
default: true
in: query
name: fuzzyMatch
required: false
description: Set to `false` to disable fuzzy search.
excludeTypes:
schema:
type: boolean
default: false
in: query
name: excludeTypes
required: false
description: Set to `true` to use all available feature types except those specified in `types`.
country:
schema:
type: array
uniqueItems: true
items:
type: string
example: sk,cz
example: sk,cz
in: query
name: country
required: false
description: Limit search to specific country/countries.
explode: false
language:
schema:
type: array
maxItems: 20
uniqueItems: true
items:
type: string
example: en
enum:
- aa
- ab
- ae
- af
- ak
- am
- an
- ar
- as
- av
- ay
- az
- ba
- be
- bg
- bh
- bi
- bm
- bn
- bo
- br
- bs
- ca
- ce
- ch
- co
- cr
- cs
- cu
- cv
- cy
- da
- de
- dv
- dz
- ee
- el
- en
- eo
- es
- et
- eu
- fa
- ff
- fi
- fj
- fo
- fr
- fy
- ga
- gd
- gl
- gn
- gu
- gv
- ha
- he
- hi
- ho
- hr
- ht
- hu
- hy
- hz
- ia
- id
- ie
- ig
- ii
- ik
- io
- is
- it
- iu
- ja
- jv
- ka
- kg
- ki
- kj
- kk
- kl
- km
- kn
- ko
- kr
- ks
- ku
- kv
- kw
- ky
- la
- lb
- lg
- li
- ln
- lo
- lt
- lu
- lv
- mg
- mh
- mi
- mk
- ml
- mn
- mr
- ms
- mt
- my
- na
- nb
- nd
- ne
- ng
- nl
- nn
- 'no'
- nr
- nv
- ny
- oc
- oj
- om
- or
- os
- pa
- pi
- pl
- ps
- pt
- qu
- rm
- rn
- ro
- ru
- rw
- sa
- sc
- sd
- se
- sg
- si
- sk
- sl
- sm
- sn
- so
- sq
- sr
- ss
- st
- su
- sv
- sw
- ta
- te
- tg
- th
- ti
- tk
- tl
- tn
- to
- tr
- ts
- tt
- tw
- ty
- ug
- uk
- ur
- uz
- ve
- vi
- vo
- wa
- wo
- xh
- yi
- yo
- za
- zh
- zu
example: de,en
example: de,en
in: query
name: language
required: false
description: Prefer results in specific language specified as ISO 639-1 code. Only the first language code is used when prioritizing forward geocode results to be matched. If this query parameter is omited then Accept-Language HTTP header will be analyzed. If the parameter is provided but is empty then no language preference is made.
explode: false
worldview:
schema:
type: string
example: ch
enum:
- default
- auto
- ch
- us
name: worldview
required: false
in: query
description: 'Some of the geographical boundaries and names are disputed. When `worldview` option is selected, the Geocoding API responses will be aligned with the borders and names recognized by the selected country (US or Switzerland). This affects filtering by country, the context returned with the given feature and also some of the labels (e.g., Gulf of Mexico vs. Gulf of America). Special values include: `auto` - the worldview is determined by the location of the client, `default` - disputed areas are returned without country information, countries with disputed borders are returned without full geometry.
'
example: ch
default: default
autocomplete:
schema:
type: boolean
in: query
name: autocomplete
required: false
description: Set to `true` to use autocomplete, `false` to disable autocomplete.
default: true
proximity:
schema:
anyOf:
- $ref: '#/components/schemas/coordinates'
- $ref: '#/components/schemas/ip'
example: 8.528509,47.3774434
in: query
name: proximity
required: false
description: A `[lon, lat]` array to use for biasing search results or the string `ip` to do server-side IP based geolocation. Specify to prefer results close to a specific location - features closer to the proximity value will be given priority over those further from the proximity value.
explode: false
types:
schema:
type: array
uniqueItems: true
items:
$ref: '#/components/schemas/placeType'
in: query
name: types
required: false
description: Filter types of which features to return. If not specified, default configuration of API is used (see [PlaceTypeValues](https://docs.maptiler.com/cloud/api/geocoding/#PlaceTypeValues) for the list). In case of reverse geocoding if just a single type is specified, then multiple nearby features of the single type can be returned, otherwise single feature for every specified type (or default types) can be returned.
bbox:
schema:
$ref: '#/components/schemas/bbox'
example: 5.9559,45.818,10.4921,47.8084
in: query
name: bbox
required: false
description: A `[w, s, e, n]` bounding box array to use for limiting search results. Only features inside the provided bounding box will be included.
explode: false
limit:
schema:
type: integer
default: 5
minimum: 1
maximum: 10
in: query
name: limit
required: false
description: Maximum number of results to return. For reverse geocoding with multiple types this must not be set or must be set to 1.
responses:
ok:
description: Search result represented as FeatureCollection where every item is represented as a GeoJSON Feature
content:
application/json:
schema:
$ref: '#/components/schemas/result'
'403':
description: Key is missing, invalid or restricted
securitySchemes:
key:
description: Your own API key from https://cloud.maptiler.com/
type: apiKey
name: key
in: query