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 for.
Example: Zurich

Query Parameters

Parameters Type Description
bbox
bbox Object
A [w, s, e, n] bbox array to use for limiting search results. Only features inside the provided bbox will be included.
Example: 5.9559,45.818,10.4921,47.8084
proximity
coordinates Object
A [lon, lat] array to use for biasing search results. 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 [string]
Filter of feature types to return. If not specified, all available feature types are returned.
Unique values: true
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 [string]
Filter of feature types to return. If not specified, all available feature types are returned.
Unique values: true
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

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 [Feature Object]
Array of features found
query
array [string]
Tokenized search query
attribution
string
Attribution of the result

Feature Object

Property Type Description
type
string
Value: "Feature"
id
Any Of [number, string]
Unique feature ID
properties
object
Feature properties
geometry
Any Of [Point ObjectLineString ObjectPolygon ObjectMultiPoint ObjectMultiLineString ObjectMultiPolygon ObjectGeometryCollection Object]
bbox
bbox Object
Bounding box of the original feature as [w, s, e, n] array
center
coordinates Object
A [lon, lat] array of the original feature centeroid
place_name
string
Formatted (including the hierarchy) and localized feature full name
text
string
Localized feature name
context
array [FeatureHierarchy Object]
Feature hierarchy
address
string
Address number, if applicable

Point Object

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

LineString Object

Property Type Description
type
string
Value: "LineString"
coordinates
array [coordinates Object]

Polygon Object

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

MultiPoint Object

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

MultiLineString Object

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

MultiPolygon Object

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

GeometryCollection Object

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

FeatureHierarchy Object

Property Type Description
id
string
Unique feature ID
text
string
Localized feature name

coordinates Object

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]

bbox Object

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

bbox example


  [5.9559, 45.818, 10.4921, 47.8084]