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
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
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
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 ]
400		Query too long / Invalid parameters
403		Key is missing, invalid or restricted

SearchResults

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

Feature

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	Feature properties
geometry	Any Of [Point , LineString , Polygon , MultiPoint , MultiLineString , MultiPolygon , GeometryCollection ]
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 ]	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

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	(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

FeatureProperties example


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

Point

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

LineString

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

Polygon

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

MultiPoint

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

MultiLineString

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

MultiPolygon

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

GeometryCollection

Property	Type	Description
type	string	Value: `"GeometryCollection"`
geometries	array Any Of [Point , LineString , Polygon , MultiPoint , MultiLineString , MultiPolygon ]

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

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	(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

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

Property	Type	Description
name*	any

PlaceType

Type	Values	Description
string	`continental_marine` `country` `major_landform` `region` `subregion` `county` `joint_municipality` `joint_submunicipality` `municipality` `municipal_district` `locality` `neighbourhood` `place` `postal_code` `address` `road` `poi`	Check out the descriptions and default values of each of the PlaceType values

PlaceType Values

PlaceType value	Default status	Description
continental_marine	`true`	Continents, oceans, seas and other forms of marine water bodies.
country	`true`	A sovereign territory with defined borders, a permanent population, and its own government.
major_landform	`false`	Major landforms.
region	`true`	Administrative units and settlements.
subregion	`true`
county	`true`
joint_municipality	`true`
joint_submunicipality	`true`
municipality	`true`
municipal_district	`true`
locality	`true`
neighbourhood	`true`
place	`true`
postal_code	`true`	A series of letters, numbers, or both, assigned to specific geographic areas to help sort and deliver mail efficiently. It is also known as a ZIP code (in the United States), postcode (in the UK), or PIN code (in India), depending on the country.
address	`true`	Roof top address point or residential street names.
road	`true`	Roads defined by their name or number. From highways to residential streets.
poi	`false`	Points of interests can be found by their name or other attributes. Categories search is not enabled at the moment.

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