Geocoding API

Using the API from JavaScript?

Geocoding (forward geocoding and reverse geocoding) is technique for place identification - either by name or coordinates. See the Geocoding page for more details.

Search by name (forward)

GET https://api.maptiler.com/geocoding/{query}.json

Forward geocoding (search by place name).

Request

You must include an API Key with every API request

Path Parameters

Parameters Type Description
query
string
Place name to search. You can also use bare POI category or mix it with a name to search for POIs of desired category, unless poi index is excluded.
Examples:
Zurich - Search place name
restaurant mediterranean - Search POI category

Query Parameters

Parameters Type Description
bbox
BoundingBox
A [w, s, e, n] bounding box array to use for limiting search results. Only features inside the provided bounding box will be included.
Example: 5.9559,45.818,10.4921,47.8084
proximity
Any Of [ Coordinatesip]
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.
Example: 8.528509,47.3774434
language
array [string]
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-Langyage HTTP header will be analyzed. If the parameter is provided but is empty then no language preference is made.
Example: de,en
<= 20 items
Allowed values: 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
Unique values: true
country
array [string]
Limit search to specific country/countries.
Example: sk,cz
Unique values: true
limit
integer
Maximum number of results to show.
>= 1<= 10
Default: 5
types
array [ PlaceType]
Filter of feature types to return. If not specified, all available feature types except poi are returned (types=poi&excludeTypes=true).
Unique values: true
excludeTypes
boolean
Set to true to use all available feature types except those mentioned in types.
Default: false
fuzzyMatch
boolean
Set to false to disable fuzzy search.
Default: true
autocomplete
boolean
Set to true to use autocomplete, false to disable autocomplete. Default is to combine autocomplete with non-autocomplete results.
Request example

  https://api.maptiler.com/geocoding/Zurich.json?key=YOUR_MAPTILER_API_KEY

Get your FREE API key in the MapTiler Cloud.

Responses

Code Content Description
200 application/json SearchResults Object
400

Query too long / Invalid parameters

403

Key is missing, invalid or restricted

Search by coordinates (reverse)

GET https://api.maptiler.com/geocoding/{longitude},{latitude}.json

Reverse geocoding (search by coordinates).

Request

You must include an API Key with every API request

Path Parameters

Parameters Type Description
longitude
number
Example: 8.528509
>= -180<= 180
latitude
number
Example: 47.3774434
>= -90<= 90

Query Parameters

Parameters Type Description
language
array [string]
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-Langyage HTTP header will be analyzed. If the parameter is provided but is empty then no language preference is made.
Example: de,en
<= 20 items
Allowed values: 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
Unique values: true
limit
integer
Maximum number of results to show.
>= 1<= 10
Default: 5
types
array [ PlaceType]
Filter of feature types to return. If not specified, all available feature types except poi are returned (types=poi&excludeTypes=true).
Unique values: true
excludeTypes
boolean
Set to true to use all available feature types except those mentioned in types.
Default: false
Request example

  https://api.maptiler.com/geocoding/8.528509,47.3774434.json?key=YOUR_MAPTILER_API_KEY

Get your FREE API key in the MapTiler Cloud.

Responses

Code Content Description
200 application/json SearchResults Object
400

Query too long / Invalid parameters

403

Key is missing, invalid or restricted

Search by feature ID

GET https://api.maptiler.com/geocoding/{id}.json

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.

Request

You must include an API Key with every API request

Path Parameters

Parameters Type Description
id
string
Feature ID (found in response of forward or reverse geocoding)
Example: country.26561650
Match pattern: ^(\S+)\.([0-9]+)$

Query Parameters

Parameters Type Description
language
array [string]
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-Langyage HTTP header will be analyzed. If the parameter is provided but is empty then no language preference is made.
Example: de,en
<= 20 items
Allowed values: 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
Unique values: true
Request example

  https://api.maptiler.com/geocoding/country.26561650.json?key=YOUR_MAPTILER_API_KEY

Get your FREE API key in the MapTiler Cloud.

Responses

Code Content Description
200 application/json SearchResults Object
400

Query too long / Invalid parameters

403

Key is missing, invalid or restricted

Batch geocoding

GET https://api.maptiler.com/geocoding/{queries}.json

Perform multiple geocoding searches in one request.

Request

You must include an API Key with every API request

Path Parameters

Parameters Type Description
queries
string
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

Query Parameters

Parameters Type Description
bbox
BoundingBox
A [w, s, e, n] bounding box array to use for limiting search results. Only features inside the provided bounding box will be included.
Example: 5.9559,45.818,10.4921,47.8084
proximity
Any Of [ Coordinatesip]
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.
Example: 8.528509,47.3774434
language
array [string]
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-Langyage HTTP header will be analyzed. If the parameter is provided but is empty then no language preference is made.
Example: de,en
<= 20 items
Allowed values: 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
Unique values: true
country
array [string]
Limit search to specific country/countries.
Example: sk,cz
Unique values: true
limit
integer
Maximum number of results to show.
>= 1<= 10
Default: 5
types
array [ PlaceType]
Filter of feature types to return. If not specified, all available feature types except poi are returned (types=poi&excludeTypes=true).
Unique values: true
excludeTypes
boolean
Set to true to use all available feature types except those mentioned in types.
Default: false
fuzzyMatch
boolean
Set to false to disable fuzzy search.
Default: true
autocomplete
boolean
Set to true to use autocomplete, false to disable autocomplete. Default is to combine autocomplete with non-autocomplete results.
Request example

  https://api.maptiler.com/geocoding/Paris;Berlin.json?key=YOUR_MAPTILER_API_KEY

Get your FREE API key in the MapTiler Cloud.

Responses

Code Content Description
200 application/json 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
400

Query too long / Invalid parameters

403

Key is missing, invalid or restricted

SearchResults Object

Search result represented by FeatureCollection where every item is represented as a GeoJSON Feature

Property Type Description
type
string
Value: "FeatureCollection"
features
array of [ Feature Object ]
Array of features found
query
array [string]
Tokenized search query
attribution
string
Attribution of the result

Feature Object

Array of features found

Property Type Description
id
string
Unique feature ID
text
string
Localized feature name
language
string
Query’s primary ISO 639-1 language code
^text_(\w\w)
string
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)
string
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.
type
string
Value: "Feature"
properties
FeatureProperties Object
Feature properties
geometry
Any Of [ Point ObjectLineString ObjectPolygon ObjectMultiPoint ObjectMultiLineString ObjectMultiPolygon ObjectGeometryCollection Object]
bbox
BoundingBox
Bounding box of the original feature as [w, s, e, n] array
center
Coordinates
A [lon, lat] array of the original feature centeroid
place_name
string
Formatted (including the hierarchy) and localized feature full name
matching_place_name
string
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.
matching_text
string
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.
place_type
array [ PlaceType]
An array of feature types describing the feature. Currently each feature has only single type but this may change in the future.
place_type_name
array [string]
Localized type of the place name, matches place_type property.
relevance
number
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.
context
array of [ Context Object ]
Feature hierarchy
address
string
Address number, if applicable
^place_name_(\w\w)
string
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.
name*
any

FeatureProperties Object

Property Type Description
ref
string
External reference of the feature used for debugging purposes
country_code
string
ISO 3166-1 alpha-2 country code of the feature
kind
string
(experimental) Kind of the feature
Allowed values: road road_relation admin_area place street virtual_street
categories
array [>= 1string]
Array of POI category. Only available for poi type. Category values may change in the near future.
osm:tags
OSMtags Object
(experimental) Feature tags from OpenStreetMap. Only available for poi type.
osm:place_type
string
(experimental) Value of place=* tag from OpenStreetMap feature if kind=place
name*
any

Point Object

Property Type Description
type
string
Value: "Point"
coordinates
Coordinates

LineString Object

Property Type Description
type
string
Value: "LineString"
coordinates
array>= 2 [ Coordinates]

Polygon Object

Property Type Description
type
string
Value: "Polygon"
coordinates
array [>= 4 array>= 4 [ Coordinates] ]

MultiPoint Object

Property Type Description
type
string
Value: "MultiPoint"
coordinates
array [ Coordinates]

MultiLineString Object

Property Type Description
type
string
Value: "MultiLineString"
coordinates
array [>= 2 array>= 2 [ Coordinates] ]

MultiPolygon Object

Property Type Description
type
string
Value: "MultiPolygon"
coordinates
array [>= 4 array [>= 4 array>= 4 [ Coordinates] ] ]

GeometryCollection Object

Property Type Description
type
string
Value: "GeometryCollection"
geometries
array Any Of [ Point ObjectLineString ObjectPolygon ObjectMultiPoint ObjectMultiLineString ObjectMultiPolygon Object]

BoundingBox

Description Type Constraint
minimal longitude number
Minimum value: -180
Maximum value: 180
minimal latitude number
Minimum value: -90
Maximum value: 90
maximal longitude number
Minimum value: -180
Maximum value: 180
maximal latitude number
Minimum value: -90
Maximum value: 90

BoundingBox example


    [5.9559, 45.818, 10.4921, 47.8084]
  

Coordinates

Description Type Constraint
longitude number
Minimum value: -180
Maximum value: 180
latitude number
Minimum value: -90
Maximum value: 90

Coordinates example


    [8.528509, 47.3774434]
  

Context Object

Feature hierarchy

Property Type Description
ref
string
External reference of the feature used for debugging purposes
country_code
string
ISO 3166-1 alpha-2 country code of the feature
kind
string
(experimental) Kind of the feature
Allowed values: road road_relation admin_area place street virtual_street
categories
array [>= 1string]
Array of POI category. Only available for poi type. Category values may change in the near future.
osm:tags
OSMtags Object
(experimental) Feature tags from OpenStreetMap. Only available for poi type.
osm:place_type
string
(experimental) Value of place=* tag from OpenStreetMap feature if kind=place
id
string
Unique feature ID
text
string
Localized feature name
language
string
Query’s primary ISO 639-1 language code
^text_(\w\w)
string
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)
string
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.
name*
any

OSMtags Object

(experimental) Feature tags from OpenStreetMap. Only available for poi type.

Property Type Description
name*
any

PlaceType

Type Values
string
  • country
  • region
  • subregion
  • county
  • joint_municipality
  • joint_submunicipality
  • municipality
  • municipal_district
  • locality
  • neighbourhood
  • place
  • postal_code
  • address
  • road
  • poi

POI Category

Category values may change in the near future.

Type: string.