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).

Geocoding API reference

Scalar API Reference
v4.8.0
OpenAPI 3.1.0

MapTiler Server API

Support
Terms of Service
Server:http://localhost:3650/api

MapTiler Server API

Client Libraries
Shell Curl

Geocoding

​
Geocoding Operations

Search by name (forward)

​

Forward geocoding (search by place name).

Path Parameters
  • query
    Type: string
    required

    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.

Query Parameters
  • bbox
    Type: array · bbox

    A [w, s, e, n] bounding box array to use for limiting search results. Only features inside the provided bounding box will be included.

  • proximity

    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.

    • Type: array · Coordinates
  • language
    Type: array string[] …20 unique!enum

    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.

    values
    • aa
    • ab
    • ae
    • af
    • ak
  • country
    Type: array string[] unique!

    Limit search to specific country/countries.

  • limit
    Type: integer
    min:  
    1
    max:  
    10

    Maximum number of results. Default: 5 for forward geocoding, 1 for reverse geocoding. For reverse geocoding, limit > 1 requires exactly one types value and switches to a nearest-neighbour search (N closest features of that type within 1 km). Without limit, reverse geocoding returns a single best match per layer at the queried point

  • types
    Type: array string[] · PlaceType[] unique!enum

    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 - see also the limit parameter.

    • Type: string · PlaceTypeenum

      Check out the descriptions and default values of each of the PlaceType values

      values
      • continental_marine
      • country
      • major_landform
      • region
      • subregion
  • excludeTypes
    Type: boolean

    Set to true to use all available feature types except those specified in types.

  • fuzzyMatch
    Type: boolean

    Set to false to disable fuzzy search.

  • autocomplete
    Type: boolean

    Set to true to use autocomplete, false to disable autocomplete.

  • worldview
    Type: string enum

    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 (e.g., 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.

    values
    • default
    • auto
    • ae
    • ch
    • jp
    • kr
    • us
Responses
  • application/json
  • 400

    Query too long / Invalid parameters

Request Example for get/geocoding/{query}.json
curl http://localhost:3650/api/geocoding/Zurich.json

{
  "type": "FeatureCollection",
  "features": [
    {
      "id": "municipality.46425",
      "text": "Paris",
      "language": "en",
      "^text_(\\w\\w)": "string",
      "^language_(\\w\\w)": "string",
      "additionalProperty": "anything",
      "type": "Feature",
      "properties": {
        "ref": "osm:r71525",
        "country_code": "fr",
        "kind": "road",
        "categories": [
          "restaurant"
        ],
        "feature_tags": {
          "additionalProperty": "string"
        },
        "place_designation": "city",
        "additionalProperty": "anything"
      },
      "geometry": {
        "type": "Point",
        "coordinates": [
          8.528509,
          47.3774434
        ]
      },
      "bbox": [
        5.9559,
        45.818,
        10.4921,
        47.8084
      ],
      "center": [
        8.528509,
        47.3774434
      ],
      "place_name": "string",
      "matching_place_name": "string",
      "matching_text": "string",
      "place_type": [
        "continental_marine"
      ],
      "place_type_name": [
        "string"
      ],
      "relevance": 1,
      "context": [
        {
          "ref": "osm:r71525",
          "country_code": "fr",
          "kind": "road",
          "categories": [
            "restaurant"
          ],
          "feature_tags": {
            "additionalProperty": "string"
          },
          "place_designation": "city",
          "additionalProperty": "anything",
          "id": "municipality.46425",
          "text": "Paris",
          "language": "en",
          "^text_(\\w\\w)": "string",
          "^language_(\\w\\w)": "string"
        }
      ],
      "address": "string",
      "^place_name_(\\w\\w)": "string"
    }
  ],
  "query": [
    "string"
  ],
  "attribution": "<a href=\"https://www.maptiler.com/copyright/\" target=\"_blank\">&copy; MapTiler</a> <a href=\"https://www.openstreetmap.org/copyright\" target=\"_blank\">&copy; OpenStreetMap contributors</a>"
}

Search result represented as FeatureCollection where every item is represented as a GeoJSON Feature

Search by coordinates (reverse)

​

Reverse geocoding (search by coordinates).

Path Parameters
  • longitude
    Type: number
    min:  
    -180
    max:  
    180
    required
  • latitude
    Type: number
    min:  
    -90
    max:  
    90
    required
Query Parameters
  • language
    Type: array string[] …20 unique!enum

    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.

    values
    • aa
    • ab
    • ae
    • af
    • ak
  • limit
    Type: integer
    min:  
    1
    max:  
    10

    Maximum number of results. Default: 5 for forward geocoding, 1 for reverse geocoding. For reverse geocoding, limit > 1 requires exactly one types value and switches to a nearest-neighbour search (N closest features of that type within 1 km). Without limit, reverse geocoding returns a single best match per layer at the queried point

  • types
    Type: array string[] · PlaceType[] unique!enum

    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 - see also the limit parameter.

    • Type: string · PlaceTypeenum

      Check out the descriptions and default values of each of the PlaceType values

      values
      • continental_marine
      • country
      • major_landform
      • region
      • subregion
  • excludeTypes
    Type: boolean

    Set to true to use all available feature types except those specified in types.

  • worldview
    Type: string enum

    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 (e.g., 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.

    values
    • default
    • auto
    • ae
    • ch
    • jp
    • kr
    • us
Responses
  • application/json
  • 400

    Query too long / Invalid parameters

Request Example for get/geocoding/{longitude},{latitude}.json
curl http://localhost:3650/api/geocoding/8.528509,47.3774434.json

{
  "type": "FeatureCollection",
  "features": [
    {
      "id": "municipality.46425",
      "text": "Paris",
      "language": "en",
      "^text_(\\w\\w)": "string",
      "^language_(\\w\\w)": "string",
      "additionalProperty": "anything",
      "type": "Feature",
      "properties": {
        "ref": "osm:r71525",
        "country_code": "fr",
        "kind": "road",
        "categories": [
          "restaurant"
        ],
        "feature_tags": {
          "additionalProperty": "string"
        },
        "place_designation": "city",
        "additionalProperty": "anything"
      },
      "geometry": {
        "type": "Point",
        "coordinates": [
          8.528509,
          47.3774434
        ]
      },
      "bbox": [
        5.9559,
        45.818,
        10.4921,
        47.8084
      ],
      "center": [
        8.528509,
        47.3774434
      ],
      "place_name": "string",
      "matching_place_name": "string",
      "matching_text": "string",
      "place_type": [
        "continental_marine"
      ],
      "place_type_name": [
        "string"
      ],
      "relevance": 1,
      "context": [
        {
          "ref": "osm:r71525",
          "country_code": "fr",
          "kind": "road",
          "categories": [
            "restaurant"
          ],
          "feature_tags": {
            "additionalProperty": "string"
          },
          "place_designation": "city",
          "additionalProperty": "anything",
          "id": "municipality.46425",
          "text": "Paris",
          "language": "en",
          "^text_(\\w\\w)": "string",
          "^language_(\\w\\w)": "string"
        }
      ],
      "address": "string",
      "^place_name_(\\w\\w)": "string"
    }
  ],
  "query": [
    "string"
  ],
  "attribution": "<a href=\"https://www.maptiler.com/copyright/\" target=\"_blank\">&copy; MapTiler</a> <a href=\"https://www.openstreetmap.org/copyright\" target=\"_blank\">&copy; OpenStreetMap contributors</a>"
}

Search result represented as FeatureCollection where every item is represented as a GeoJSON Feature

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.

Path Parameters
  • id
    Type: string
    required

    Feature ID (found in response of forward or reverse geocoding)

Query Parameters
  • language
    Type: array string[] …20 unique!enum

    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.

    values
    • aa
    • ab
    • ae
    • af
    • ak
  • worldview
    Type: string enum

    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 (e.g., 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.

    values
    • default
    • auto
    • ae
    • ch
    • jp
    • kr
    • us
Responses
  • application/json
  • 400

    Query too long / Invalid parameters

Request Example for get/geocoding/{id}.json
curl http://localhost:3650/api/geocoding/country.26561650.json

{
  "type": "FeatureCollection",
  "features": [
    {
      "id": "municipality.46425",
      "text": "Paris",
      "language": "en",
      "^text_(\\w\\w)": "string",
      "^language_(\\w\\w)": "string",
      "additionalProperty": "anything",
      "type": "Feature",
      "properties": {
        "ref": "osm:r71525",
        "country_code": "fr",
        "kind": "road",
        "categories": [
          "restaurant"
        ],
        "feature_tags": {
          "additionalProperty": "string"
        },
        "place_designation": "city",
        "additionalProperty": "anything"
      },
      "geometry": {
        "type": "Point",
        "coordinates": [
          8.528509,
          47.3774434
        ]
      },
      "bbox": [
        5.9559,
        45.818,
        10.4921,
        47.8084
      ],
      "center": [
        8.528509,
        47.3774434
      ],
      "place_name": "string",
      "matching_place_name": "string",
      "matching_text": "string",
      "place_type": [
        "continental_marine"
      ],
      "place_type_name": [
        "string"
      ],
      "relevance": 1,
      "context": [
        {
          "ref": "osm:r71525",
          "country_code": "fr",
          "kind": "road",
          "categories": [
            "restaurant"
          ],
          "feature_tags": {
            "additionalProperty": "string"
          },
          "place_designation": "city",
          "additionalProperty": "anything",
          "id": "municipality.46425",
          "text": "Paris",
          "language": "en",
          "^text_(\\w\\w)": "string",
          "^language_(\\w\\w)": "string"
        }
      ],
      "address": "string",
      "^place_name_(\\w\\w)": "string"
    }
  ],
  "query": [
    "string"
  ],
  "attribution": "<a href=\"https://www.maptiler.com/copyright/\" target=\"_blank\">&copy; MapTiler</a> <a href=\"https://www.openstreetmap.org/copyright\" target=\"_blank\">&copy; OpenStreetMap contributors</a>"
}

Search result represented as FeatureCollection where every item is represented as a GeoJSON Feature

Batch geocoding API

​

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

Path Parameters
  • queries
    Type: string
    required

    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.

Query Parameters
  • bbox
    Type: array · bbox

    A [w, s, e, n] bounding box array to use for limiting search results. Only features inside the provided bounding box will be included.

  • proximity

    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.

    • Type: array · Coordinates
  • language
    Type: array string[] …20 unique!enum

    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.

    values
    • aa
    • ab
    • ae
    • af
    • ak
  • country
    Type: array string[] unique!

    Limit search to specific country/countries.

  • limit
    Type: integer
    min:  
    1
    max:  
    10

    Maximum number of results. Default: 5 for forward geocoding, 1 for reverse geocoding. For reverse geocoding, limit > 1 requires exactly one types value and switches to a nearest-neighbour search (N closest features of that type within 1 km). Without limit, reverse geocoding returns a single best match per layer at the queried point

  • types
    Type: array string[] · PlaceType[] unique!enum

    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 - see also the limit parameter.

    • Type: string · PlaceTypeenum

      Check out the descriptions and default values of each of the PlaceType values

      values
      • continental_marine
      • country
      • major_landform
      • region
      • subregion
  • excludeTypes
    Type: boolean

    Set to true to use all available feature types except those specified in types.

  • fuzzyMatch
    Type: boolean

    Set to false to disable fuzzy search.

  • autocomplete
    Type: boolean

    Set to true to use autocomplete, false to disable autocomplete.

  • worldview
    Type: string enum

    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 (e.g., 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.

    values
    • default
    • auto
    • ae
    • ch
    • jp
    • kr
    • us
Responses
  • application/json
  • 400

    Query too long / Invalid parameters

Request Example for get/geocoding/{queries}.json
curl 'http://localhost:3650/api/geocoding/Paris;Berlin.json'

[
  {
    "type": "FeatureCollection",
    "features": [
      {
        "id": "municipality.46425",
        "text": "Paris",
        "language": "en",
        "^text_(\\w\\w)": "string",
        "^language_(\\w\\w)": "string",
        "additionalProperty": "anything",
        "type": "Feature",
        "properties": {
          "ref": "osm:r71525",
          "country_code": "fr",
          "kind": "road",
          "categories": [
            "restaurant"
          ],
          "feature_tags": {
            "additionalProperty": "string"
          },
          "place_designation": "city",
          "additionalProperty": "anything"
        },
        "geometry": {
          "type": "Point",
          "coordinates": [
            8.528509,
            47.3774434
          ]
        },
        "bbox": [
          5.9559,
          45.818,
          10.4921,
          47.8084
        ],
        "center": [
          8.528509,
          47.3774434
        ],
        "place_name": "string",
        "matching_place_name": "string",
        "matching_text": "string",
        "place_type": [
          "continental_marine"
        ],
        "place_type_name": [
          "string"
        ],
        "relevance": 1,
        "context": [
          {
            "ref": "osm:r71525",
            "country_code": "fr",
            "kind": "road",
            "categories": [
              "restaurant"
            ],
            "feature_tags": {
              "additionalProperty": "string"
            },
            "place_designation": "city",
            "additionalProperty": "anything",
            "id": "municipality.46425",
            "text": "Paris",
            "language": "en",
            "^text_(\\w\\w)": "string",
            "^language_(\\w\\w)": "string"
          }
        ],
        "address": "string",
        "^place_name_(\\w\\w)": "string"
      }
    ],
    "query": [
      "string"
    ],
    "attribution": "<a href=\"https://www.maptiler.com/copyright/\" target=\"_blank\">&copy; MapTiler</a> <a href=\"https://www.openstreetmap.org/copyright\" target=\"_blank\">&copy; OpenStreetMap contributors</a>"
  }
]

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

Using the OpenAPI Specification?
Get the openapi.yaml
Was this helpful?
MapTiler Server API
Geocoding API | MapTiler Server API
Geocoding API