Geocoding API

Using the API from JavaScript?

Geocoding (forward geocoding and reverse geocoding) is a 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 [ Coordinates, `ip`]	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-Language 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 return. For reverse geocoding with multiple types this must not be set or must be set to 1. `>= 1<= 10` Default: `5`
types	array [ `PlaceType`]	Filter types of which features to return. If not specified, features of all types except `poi` and `major_landform` are returned (`types = ["poi", "major_landform"]`, `excludeTypes = true`). 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. Unique values: `true`
excludeTypes	boolean	Set to `true` to use all available feature types except those specified 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: `true`

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-Language 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 return. For reverse geocoding with multiple types this must not be set or must be set to 1. `>= 1<= 10` Default: `5`
types	array [ `PlaceType`]	Filter types of which features to return. If not specified, features of all types except `poi` and `major_landform` are returned (`types = ["poi", "major_landform"]`, `excludeTypes = true`). 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. Unique values: `true`
excludeTypes	boolean	Set to `true` to use all available feature types except those specified 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-Language 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 [ Coordinates, `ip`]	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-Language 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 return. For reverse geocoding with multiple types this must not be set or must be set to 1. `>= 1<= 10` Default: `5`
types	array [ `PlaceType`]	Filter types of which features to return. If not specified, features of all types except `poi` and `major_landform` are returned (`types = ["poi", "major_landform"]`, `excludeTypes = true`). 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. Unique values: `true`
excludeTypes	boolean	Set to `true` to use all available feature types except those specified 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: `true`

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 of [ Feature Object ]	Array of features found
query	array [string]	Tokenized search query
attribution	string	Attribution of the result Example: `© MapTiler © OpenStreetMap contributors`

Feature Object

Array of features found

Property	Type	Description
id	string	Unique feature ID Example: `municipality.46425`
text	string	Localized feature name Example: `Paris`
language	string	Query’s primary ISO 639-1 language code Example: `en`
^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 Object, LineString Object, Polygon Object, MultiPoint Object, MultiLineString Object, MultiPolygon Object, GeometryCollection 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 Example: `osm:r71525`
country_code	string	ISO 3166-1 alpha-2 country code of the feature Example: `fr`
kind	string	(experimental) Kind of the feature Allowed values: `road` `road_relation` `admin_area` `place` `street` `virtual_street`
categories	array [`>= 1`string]	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 Example: `city`
name*	any

example


    {
  "ref": "osm:r71525",
  "country_code": "fr",
  "kind": null,
  "categories": ["restaurant"],
  "osm:tags": null,
  "osm:place_type": "city"
}

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 Object, LineString Object, Polygon Object, MultiPoint Object, MultiLineString Object, MultiPolygon 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 Example: `osm:r71525`
country_code	string	ISO 3166-1 alpha-2 country code of the feature Example: `fr`
kind	string	(experimental) Kind of the feature Allowed values: `road` `road_relation` `admin_area` `place` `street` `virtual_street`
categories	array [`>= 1`string]	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 Example: `city`
id	string	Unique feature ID Example: `municipality.46425`
text	string	Localized feature name Example: `Paris`
language	string	Query’s primary ISO 639-1 language code Example: `en`
^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	`continental_marine` `country` `major_landform` `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.

List of POIs categories definitions.

Using the OpenAPI Specification?

Get the openapi.yaml

APIs

Authentication

Admin API

On this page