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 Object, LineString Object, Polygon Object, MultiPoint Object, MultiLineString Object, MultiPolygon Object, GeometryCollection 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 Object, LineString Object, Polygon Object, MultiPoint Object, MultiLineString Object, MultiPolygon 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]

Geocoding API

Search by name (forward)

Request

Path Parameters

Query Parameters

Request example

Responses

Search by coordinates (reverse)

Request

Path Parameters

Query Parameters

Request example

Responses

Search by feature ID

Request

Path Parameters

Query Parameters

Request example

Responses

SearchResults Object

Feature Object

Point Object

LineString Object

Polygon Object

MultiPoint Object

MultiLineString Object

MultiPolygon Object

GeometryCollection Object

FeatureHierarchy Object

coordinates Object

coordinates example

bbox Object

bbox example

APIs

Authentication

Admin API

On This Page