On this page

    Geocoding API

    On-prem geocoding makes it possible to add place search to your self-hosted maps. It includes both forward geocoding (search by place name) and reverse geocoding (search by coordinates).

    Search by name (forward)

    Added in v4.7.0
    GET http://localhost:3650/api/geocoding/{query}.json

    Forward geocoding (search by place name).

    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, default configuration of API is used (see PlaceTypeValues for the list). 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
    worldview
    		 string
    Some of the geographical boundaries and names are disputed. When worldview option is selected, the Geocoding API responses will be aligned with the borders and names recognized by the selected country (US or Switzerland). This affects filtering by country, the context returned with the given feature and also some of the labels (e.g., Gulf of Mexico vs. Gulf of America). Special values include: auto - the worldview is determined by the location of the client, default - disputed areas are returned without country information, countries with disputed borders are returned without full geometry.
    Example: ch
    Allowed values: default auto ch us
    Default: default
    Added in v4.8.0
    Request example
    
  http://localhost:3650/api/geocoding/Zurich.json

    Responses

    Code Content Description
    200 application/json SearchResults
    400

    Query too long / Invalid parameters

    Search by coordinates (reverse)

    Added in v4.7.0
    GET http://localhost:3650/api/geocoding/{longitude},{latitude}.json

    Reverse geocoding (search by coordinates).

    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, default configuration of API is used (see PlaceTypeValues for the list). 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
    worldview
    		 string
    Some of the geographical boundaries and names are disputed. When worldview option is selected, the Geocoding API responses will be aligned with the borders and names recognized by the selected country (US or Switzerland). This affects filtering by country, the context returned with the given feature and also some of the labels (e.g., Gulf of Mexico vs. Gulf of America). Special values include: auto - the worldview is determined by the location of the client, default - disputed areas are returned without country information, countries with disputed borders are returned without full geometry.
    Example: ch
    Allowed values: default auto ch us
    Default: default
    Added in v4.8.0
    Request example
    
  http://localhost:3650/api/geocoding/8.528509,47.3774434.json

    Responses

    Code Content Description
    200 application/json SearchResults
    400

    Query too long / Invalid parameters

    Search by feature ID

    Added in v4.7.0
    GET http://localhost:3650/api/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

    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
    worldview
    		 string
    Some of the geographical boundaries and names are disputed. When worldview option is selected, the Geocoding API responses will be aligned with the borders and names recognized by the selected country (US or Switzerland). This affects filtering by country, the context returned with the given feature and also some of the labels (e.g., Gulf of Mexico vs. Gulf of America). Special values include: auto - the worldview is determined by the location of the client, default - disputed areas are returned without country information, countries with disputed borders are returned without full geometry.
    Example: ch
    Allowed values: default auto ch us
    Default: default
    Added in v4.8.0
    Request example
    
  http://localhost:3650/api/geocoding/country.26561650.json

    Responses

    Code Content Description
    200 application/json SearchResults
    400

    Query too long / Invalid parameters

    Batch geocoding API

    Added in v4.7.0
    GET http://localhost:3650/api/geocoding/{queries}.json

    Perform geocoding of more than one request in a single API call. Check out the Batch Geocoding guide for an example.

    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, default configuration of API is used (see PlaceTypeValues for the list). 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
    worldview
    		 string
    Some of the geographical boundaries and names are disputed. When worldview option is selected, the Geocoding API responses will be aligned with the borders and names recognized by the selected country (US or Switzerland). This affects filtering by country, the context returned with the given feature and also some of the labels (e.g., Gulf of Mexico vs. Gulf of America). Special values include: auto - the worldview is determined by the location of the client, default - disputed areas are returned without country information, countries with disputed borders are returned without full geometry.
    Example: ch
    Allowed values: default auto ch us
    Default: default
    Added in v4.8.0
    Request example
    
  http://localhost:3650/api/geocoding/Paris;Berlin.json

    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
    400

    Query too long / Invalid parameters

    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
    (experimental) External reference of the feature used for debugging purposes. The exact format of this field may change without notice, and should not be relied on at the moment.
    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 [>= 1string]
    Array of POI category. Only available for poi type. Category values may change in the near future.
    feature_tags
    		 Feature tags
    (experimental) Feature tags, only available for poi type. They can include e.g. working hours, type of amenity or wheelchair access.
    place_designation
    		 string
    (experimental) Additional information about the place. The main use case is to determine if the administrative area represents a town, a city or a village. This field is especially useful in cases, where a large city is a region, land or prefecture from administrative point of view (typical examples are Berlin and Tokyo).
    Example: city
    name*
    		any

    FeatureProperties example

    
    {
  "ref": "osm:r71525",
  "country_code": "fr",
  "kind": null,
  "categories": ["restaurant"],
  "feature_tags": null,
  "place_designation": "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
    (experimental) External reference of the feature used for debugging purposes. The exact format of this field may change without notice, and should not be relied on at the moment.
    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 [>= 1string]
    Array of POI category. Only available for poi type. Category values may change in the near future.
    feature_tags
    		 Feature tags
    (experimental) Feature tags, only available for poi type. They can include e.g. working hours, type of amenity or wheelchair access.
    place_designation
    		 string
    (experimental) Additional information about the place. The main use case is to determine if the administrative area represents a town, a city or a village. This field is especially useful in cases, where a large city is a region, land or prefecture from administrative point of view (typical examples are Berlin and Tokyo).
    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

    Feature tags

    (experimental) Feature tags, only available for poi type. They can include e.g. working hours, type of amenity or wheelchair access.

    Property Type Description
    name*
    		any

    PlaceType

    Type ValuesDescription
    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 true 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.

    Using the OpenAPI Specification?
    Get the openapi.yaml

    Was this helpful?

    MapTiler Server API
    Geocoding API | MapTiler Server API
    Geocoding API