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	BoundingBox Object	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	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 [PlaceType Object]	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 [PlaceType Object]	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

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 Object	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	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 [PlaceType Object]	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/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 array [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	Properties Object	Feature properties
geometry	Any Of [Point Object, LineString Object, Polygon Object, MultiPoint Object, MultiLineString Object, MultiPolygon Object, GeometryCollection Object]
bbox	BoundingBox 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
place_type	array [PlaceType Object]	An array of feature types describing the feature. Currently each feature has only single type but this may change in the future.
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.
text	string	Localized feature name
language	string	Query’s primary ISO 639-1 language code
context	array [FeatureHierarchy Object]	Feature hierarchy
address	string	Address number, if applicable
^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.
^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

Properties Object

Feature properties

Property	Type	Description
country_code	string	ISO 3166-1 alpha-2 country code of the feature
place_type_name	array [string]	Localized type of the place name, matches `feature.place_type` property.
ref	string	External reference of the feature used for debugging purposes
name*	any

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
ref	string	External reference of the feature used for debugging purposes
text	string	Localized feature name
name*	any

PlaceType Object

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

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]

BoundingBox 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`

BoundingBox example


  [5.9559, 45.818, 10.4921, 47.8084]

APIs

Authentication

Admin API

On this page