Scalar API Reference
v4.8.0
OpenAPI 3.1.0

MapTiler Server API

Support
Terms of Service

API reference for the MapTiler Server.

The MapTiler Server API allows you to programmatically access all the data, maps, and resources in the MapTiler Server.

Through the API, you can add a map directly to your website, request map tiles, create an image with a location map for your business, and more.

Server:http://localhost:3650/api

MapTiler Server API

Client Libraries
Shell Curl

Maps

​
Maps Operations

Embeddable HTML viewer

​
Path Parameters
  • mapId
    Type: string
    required

    Identifier of the map. See MapTiler Server Maps http://localhost:3650/admin/.

Responses
  • text/html
  • 404

    The item does not exist

Request Example for get/maps/{mapId}/
curl http://localhost:3650/api/maps/streets/
No Body

OK

Style JSON of the map

​

Style JSON describing the map cartography. Can be used with various libraries to display a vector map (e.g. Mapbox GL JS, OpenLayers, ...).

Path Parameters
  • mapId
    Type: string
    required

    Identifier of the map. See MapTiler Server Maps http://localhost:3650/admin/.

Responses
  • application/json
  • 404

    The item does not exist

Request Example for get/maps/{mapId}/style.json
curl http://localhost:3650/api/maps/streets/style.json

{}

OK

Map symbols (sprites)

​

Map symbols (sprites) required to display the vector map.

Path Parameters
  • mapId
    Type: string
    required

    Identifier of the map. See MapTiler Server Maps http://localhost:3650/admin/.

  • scale
    enum
    const:  
    @2x

    Use "@2x" to get "retina"/HiDPI image.

    values
    • @2x
  • format
    Type: string enum
    required
    values
    • png
    • json
Responses
  • 404

    The item does not exist

Request Example for get/maps/{mapId}/sprite{scale}.{format}
curl http://localhost:3650/api/maps/streets/sprite@2x.png
No Body

OK

Raster XYZ tiles

​

Rasterized tiles (XYZ) of the map. Can be used with various libraries to display a raster map (e.g. Leaflet, OpenLayers, ...). It's usually better (if possible) to use the TileJSON rather than using the tile URL directly.

Path Parameters
  • tileSize
    enum
    const:  
    256

    Integer numbers.

    values
    • 256
  • z
    Type: integer
    required

    Zoom level. Specifies the tile's zoom level. See Tiles à la Google Maps

  • x
    Type: integer
    required

    Column. Specifies the tile's column. See Tiles à la Google Maps

  • y
    Type: integer
    required

    Row. Specifies the tile's row. See Tiles à la Google Maps

  • scale
    enum
    const:  
    @2x

    Use "@2x" to get "retina"/HiDPI image.

    values
    • @2x
  • format
    Type: string enum
    required

    The value depends on the Map settings.

    values
    • png
    • jpg
    • webp
  • mapId
Responses
  • image/*
  • 400

    Out of bounds / Invalid format

  • 404

    The item does not exist

Request Example for get/maps/{mapId}/{tileSize}/{z}/{x}/{y}{scale}.{format}
curl 'http://localhost:3650/api/maps/{mapId}/256/1/1/1@2x.png'

@filename

OK

TileJSON

​

TileJSON describing the metadata of the map as well as link to the XYZ tiles. Can be used with various libraries to display a raster map (e.g. Leaflet, OpenLayers, ...).

Path Parameters
  • mapId
    Type: string
    required

    Identifier of the map. See MapTiler Server Maps http://localhost:3650/admin/.

  • tileSize
    enum
    const:  
    256

    Integer numbers.

    values
    • 256
Responses
  • application/json
  • 404

    The item does not exist

Request Example for get/maps/{mapId}/{tileSize}/tiles.json
curl http://localhost:3650/api/maps/streets/256/tiles.json

{}

OK

OGC API - Tiles

​

Tileset landing page of the rasterized tiles. Can be used in software supporting the OGC API - Tiles v1.0 specification.

Path Parameters
  • mapId
    Type: string
    required

    Identifier of the map. See MapTiler Server Maps http://localhost:3650/admin/.

Responses
  • application/json
  • 404

    The item does not exist

Request Example for get/maps/{mapId}/tiles
curl http://localhost:3650/api/maps/streets/tiles

string

OK

OGC API TileMatrixSets

​

Description of the tileset tile matrix sets according to the OGC Web API. This resource is linked from the OGC API - Tiles endpoint.

Path Parameters
  • mapId
    Type: string
    required

    Identifier of the map. See MapTiler Server Maps http://localhost:3650/admin/.

Responses
  • application/json
  • 404

    The item does not exist

Request Example for get/maps/{mapId}/tileMatrixSet
curl http://localhost:3650/api/maps/streets/tileMatrixSet

string

OK

WMTS Capabilities

​

WMTS Capabilities XML document describing the metadata of the map as well as link to the XYZ tiles. Can be used with various GIS software (e.g. QGIS) to display the map.

Path Parameters
  • mapId
    Type: string
    required

    Identifier of the map. See MapTiler Server Maps http://localhost:3650/admin/.

Responses
  • text/xml
  • 404

    The item does not exist

Request Example for get/maps/{mapId}/WMTSCapabilities.xml
curl http://localhost:3650/api/maps/streets/WMTSCapabilities.xml

string

OK

WMTS Capabilities for all layers

​

WMTS Capabilities XML document describing the metadata of all map layers as well as link to the XYZ tiles. Can be used with various GIS software (e.g. QGIS) to display the map.

Responses
  • text/xml
  • 404

    The item does not exist

Request Example for get/WMTSCapabilities.xml
curl http://localhost:3650/api/WMTSCapabilities.xml

string

OK

WMS Capabilities

​

WMS Capabilities XML document describing the metadata of the map. Can be used with various GIS software (e.g. QGIS) to display the map.

Path Parameters
  • mapId
    Type: string
    required

    Identifier of the map. See MapTiler Server Maps http://localhost:3650/admin/.

Responses
  • text/xml
  • 404

    The item does not exist

Request Example for get/maps/{mapId}/wms?service=WMS&request=GetCapabilities
curl 'http://localhost:3650/api/maps/streets/wms?service=WMS&request=GetCapabilities'

string

OK

WMS Capabilities for all layers

​

WMS capabilities XML document describing the metadata of all map layers. Can be used with various GIS software (e.g. QGIS) to display the map.

Responses
  • text/xml
  • 404

    The item does not exist

Request Example for get/maps/wms?service=WMS&request=GetCapabilities
curl 'http://localhost:3650/api/maps/wms?service=WMS&request=GetCapabilities'

string

OK

Static maps

​
Static maps Operations

Center-based image

​

Generates a raster image based on the specified center and zoom level.

Path Parameters
  • mapId
    Type: string
    required

    Identifier of the map. See MapTiler Server Maps http://localhost:3650/admin/.

  • lon
    Type: number
    required

    Longitude of the center of the image.

  • lat
    Type: number
    required

    Latitude of the center of the image.

  • zoom
    Type: number
    required

    Zoom level of the resulting image (can be fractional). (In the tile pyramid based on 512x512 tiles.)

  • width
    Type: integer
    required

    Width of the image in pixels.

  • height
    Type: integer
    required

    Height of the image in pixels.

  • scale
    enum
    const:  
    @2x

    Use "@2x" to get "retina"/HiDPI image.

    values
    • @2x
  • format
    Type: string enum
    required

    The value depends on the Map settings.

    values
    • png
    • jpg
    • webp
Query Parameters
  • path
    Type: string

    Define path(s) to be drawn on top of the map. Can be used multiple times. See Static maps in MapTiler Server.

  • markers
    Type: string

    Define marker(s) to be drawn on top of the map. Can be used multiple times. See Static maps in MapTiler Server.

  • attribution
    Type: string enum

    Changes the position of map attribution. If you disable the attribution make sure to display it in your application yourself (visibly).

    values
    • bottomright
    • bottomleft
    • topleft
    • topright
    • false
  • shortest
    Type: boolean

    Draw the shortest paths, allow to cross the dateline.

Responses
  • image/*
  • 400

    Out of bounds / Invalid format

  • 404

    The item does not exist

  • 414

    URI Too Long. Maximum allowed length is 8192 bytes.

Request Example for get/maps/{mapId}/static/{lon},{lat},{zoom}/{width}x{height}{scale}.{format}
curl http://localhost:3650/api/maps/streets/static/1,1,1/1x1@2x.png

@filename

OK

Bounds-based image

​

Generates a raster image based on the given bounds.

Path Parameters
  • mapId
    Type: string
    required

    Identifier of the map. See MapTiler Server Maps http://localhost:3650/admin/.

  • minx
    Type: number
    required

    Longitude of the left (west) edge.

  • miny
    Type: number
    required

    Latitude of the bottom (south) edge.

  • maxx
    Type: number
    required

    Longitude of the right (east) edge.

  • maxy
    Type: number
    required

    Latitude of the top (north) edge.

  • width
    Type: integer
    required

    Width of the image in pixels.

  • height
    Type: integer
    required

    Height of the image in pixels.

  • scale
    enum
    const:  
    @2x

    Use "@2x" to get "retina"/HiDPI image.

    values
    • @2x
  • format
    Type: string enum
    required

    The value depends on the Map settings.

    values
    • png
    • jpg
    • webp
Query Parameters
  • padding
    Type: number

    Ensures the autofitted bounds or features are comfortably visible in the resulting area. E.g. use 0.1 to add 10% margin (at least) of the size to each side.

  • path
    Type: string

    Define path(s) to be drawn on top of the map. Can be used multiple times. See Static maps in MapTiler Server.

  • markers
    Type: string

    Define marker(s) to be drawn on top of the map. Can be used multiple times. See Static maps in MapTiler Server.

  • attribution
    Type: string enum

    Changes the position of map attribution. If you disable the attribution make sure to display it in your application yourself (visibly).

    values
    • bottomright
    • bottomleft
    • topleft
    • topright
    • false
  • shortest
    Type: boolean

    Draw the shortest paths, allow to cross the dateline.

Responses
  • image/*
  • 400

    Out of bounds / Invalid format

  • 404

    The item does not exist

  • 414

    URI Too Long. Maximum allowed length is 8192 bytes.

Request Example for get/maps/{mapId}/static/{minx},{miny},{maxx},{maxy}/{width}x{height}{scale}.{format}
curl http://localhost:3650/api/maps/streets/static/1,1,1,1/1x1@2x.png

@filename

OK

Auto-fitted image

​

Generates a raster image based on the given features. The area is calculated so that all the paths and markers given in query are visible.

Path Parameters
  • mapId
    Type: string
    required

    Identifier of the map. See MapTiler Server Maps http://localhost:3650/admin/.

  • width
    Type: integer
    required

    Width of the image in pixels.

  • height
    Type: integer
    required

    Height of the image in pixels.

  • scale
    enum
    const:  
    @2x

    Use "@2x" to get "retina"/HiDPI image.

    values
    • @2x
  • format
    Type: string enum
    required

    The value depends on the Map settings.

    values
    • png
    • jpg
    • webp
Query Parameters
  • padding
    Type: number

    Ensures the autofitted bounds or features are comfortably visible in the resulting area. E.g. use 0.1 to add 10% margin (at least) of the size to each side.

  • path
    Type: string

    Define path(s) to be drawn on top of the map. Can be used multiple times. See Static maps in MapTiler Server.

  • markers
    Type: string

    Define marker(s) to be drawn on top of the map. Can be used multiple times. See Static maps in MapTiler Server.

  • attribution
    Type: string enum

    Changes the position of map attribution. If you disable the attribution make sure to display it in your application yourself (visibly).

    values
    • bottomright
    • bottomleft
    • topleft
    • topright
    • false
  • shortest
    Type: boolean

    Draw the shortest paths, allow to cross the dateline.

Responses
  • image/*
  • 400

    Out of bounds / Invalid format

  • 404

    The item does not exist

  • 414

    URI Too Long. Maximum allowed length is 8192 bytes.

Request Example for get/maps/{mapId}/static/auto/{width}x{height}{scale}.{format}
curl http://localhost:3650/api/maps/streets/static/auto/1x1@2x.png

@filename

OK

Tiles

​
Tiles Operations

Embeddable HTML viewer

​
Path Parameters
  • tilesId
    Type: string
    required

    Identifier of the tiles. See MapTiler Server Tiles http://localhost:3650/admin/tiles/.

Responses
  • text/html
  • 404

    The item does not exist

Request Example for get/tiles/{tilesId}/
curl http://localhost:3650/api/tiles/maptiler-satellite/
No Body

OK

XYZ tiles

​

The individual tiles. Can be used with various libraries to display the tiles (e.g. Leaflet, OpenLayers, ...). It's usually better (if possible) to use the TileJSON rather than using the tile URL directly.

Path Parameters
  • tilesId
    Type: string
    required

    Identifier of the tiles. See MapTiler Server Tiles http://localhost:3650/admin/tiles/.

  • z
    Type: integer
    required

    Zoom level. Specifies the tile's zoom level. See Tiles à la Google Maps

  • x
    Type: integer
    required

    Column. Specifies the tile's column. See Tiles à la Google Maps

  • y
    Type: integer
    required

    Row. Specifies the tile's row. See Tiles à la Google Maps

Responses
  • *
  • 204

    Tile not present -- presumed empty (empty response)

  • 400

    Out of bounds

  • 404

    The item does not exist

Request Example for get/tiles/{tilesId}/{z}/{x}/{y}
curl http://localhost:3650/api/tiles/maptiler-satellite/1/1/1
No Body

OK

TileJSON

​

TileJSON describing the metadata of the tiles as well as link to the XYZ tiles. Can be used with various libraries to display the tiles (e.g. Leaflet, OpenLayers, ...).

Path Parameters
  • tilesId
    Type: string
    required

    Identifier of the tiles. See MapTiler Server Tiles http://localhost:3650/admin/tiles/.

Responses
  • application/json
  • 404

    The item does not exist

Request Example for get/tiles/{tilesId}/tiles.json
curl http://localhost:3650/api/tiles/maptiler-satellite/tiles.json

{}

OK

OGC API - Tiles

​

Tileset landing page of the tiles. Can be used in software supporting the OGC API - Tiles v1.0 specification.

Path Parameters
  • tilesId
    Type: string
    required

    Identifier of the tiles. See MapTiler Server Tiles http://localhost:3650/admin/tiles/.

Responses
  • application/json
  • 404

    The item does not exist

Request Example for get/tiles/{tilesId}/tiles
curl http://localhost:3650/api/tiles/maptiler-satellite/tiles

string

OK

OGC API TileMatrixSets

​

Description of the tileset tile matrix sets according to the OGC Web API. This resource is linked from the OGC API - Tiles endpoint.

Path Parameters
  • tilesId
    Type: string
    required

    Identifier of the tiles. See MapTiler Server Tiles http://localhost:3650/admin/tiles/.

Responses
  • application/json
  • 404

    The item does not exist

Request Example for get/tiles/{tilesId}/tileMatrixSet
curl http://localhost:3650/api/tiles/maptiler-satellite/tileMatrixSet

string

OK

WMTS Capabilities

​

WMTS Capabilities XML document describing the metadata of the tiles as well as link to the XYZ tiles. Can be used with various GIS software (e.g. QGIS) to display the tiles.

Path Parameters
  • tilesId
    Type: string
    required

    Identifier of the tiles. See MapTiler Server Tiles http://localhost:3650/admin/tiles/.

Responses
  • text/xml
  • 404

    The item does not exist

Request Example for get/tiles/{tilesId}/WMTSCapabilities.xml
curl http://localhost:3650/api/tiles/maptiler-satellite/WMTSCapabilities.xml

string

OK

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 to return. For reverse geocoding with multiple types this must not be set or must be set to 1.

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

    • 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 to return. For reverse geocoding with multiple types this must not be set or must be set to 1.

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

    • 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 to return. For reverse geocoding with multiple types this must not be set or must be set to 1.

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

    • 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

Other

​
Other Operations

Font glyphs

​

Generates the glyphs for the requested fonts. Used when displaying vector maps.

Path Parameters
  • fontstack
    Type: string
    required

    Font name, or more comma-separated names.

  • start
    Type: integer
    multiple of:  
    256
    required

    Start of the glyph range.

  • end
    Type: integer
    required

    End of the glyph range (last glyph index).

Responses
  • application/x-protobuf
  • 400

    Invalid glyph range

Request Example for get/fonts/{fontstack}/{start}-{end}.pbf
curl 'http://localhost:3650/api/fonts/{fontstack}/1-1.pbf'
No Body

OK

OGC API conformance classes

​

Declaration of the implemented conformance classes.

Responses
  • application/json
Request Example for get/ogc/conformance
curl http://localhost:3650/api/ogc/conformance

string

OK

Was this helpful?
MapTiler Server API Reference
MapTiler Server API