Geocoding API
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)
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 itemsAllowed 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)
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 itemsAllowed 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
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 itemsAllowed 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]
APIs
- Maps API
- Static Maps API
- Tiles API
- Data API
- Geocoding API
- Geolocation API
- Coordinates API
- Other
- Description