openapi: 3.1.0
info:
title: MapTiler Server API
version: 4.8.0
description: |
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.
termsOfService: https://www.maptiler.com/server/license/
contact:
name: Support
email: support@maptiler.com
url: https://support.maptiler.com
premium: https://www.maptiler.com/support/
servers:
- description: MapTiler Server API
url: http://localhost:3650/api/
tags:
- name: Maps
- name: Static maps
- name: Tiles
- name: Geocoding
- name: Other
paths:
/maps/{mapId}/:
parameters:
- $ref: '#/components/parameters/mapId'
get:
summary: Embeddable HTML viewer
x-since: 1.0.0
tags:
- Maps
responses:
'200':
description: OK
content:
text/html: {}
'404':
$ref: '#/components/responses/404'
/maps/{mapId}/style.json:
parameters:
- $ref: '#/components/parameters/mapId'
get:
summary: Style JSON of the map
description: Style JSON describing the map cartography. Can be used with various libraries to display a vector map (e.g. Mapbox GL JS, OpenLayers, ...).
x-since: 1.0.0
tags:
- Maps
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/StyleJSON'
'404':
$ref: '#/components/responses/404'
/maps/{mapId}/sprite{scale}.{format}:
parameters:
- $ref: '#/components/parameters/mapId'
- $ref: '#/components/parameters/rasterizationScale'
- name: format
in: path
required: true
x-since: 1.0.0
schema:
type: string
enum:
- png
- json
get:
summary: Map symbols (sprites)
description: Map symbols (sprites) required to display the vector map.
x-since: 1.0.0
tags:
- Maps
responses:
'200':
description: OK
content:
application/json: {}
image/png: {}
'404':
$ref: '#/components/responses/404'
/maps/{mapId}/{tileSize}/{z}/{x}/{y}{scale}.{format}:
parameters:
- $ref: '#/components/parameters/tileSize'
- $ref: '#/components/parameters/z'
- $ref: '#/components/parameters/x'
- $ref: '#/components/parameters/y'
- $ref: '#/components/parameters/rasterizationScale'
- $ref: '#/components/parameters/rasterizationFormat'
get:
summary: Raster XYZ tiles
description: 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.
x-since: 1.0.0
tags:
- Maps
responses:
'200':
$ref: '#/components/responses/RasterizedImage'
'400':
description: Out of bounds / Invalid format
'404':
$ref: '#/components/responses/404'
/maps/{mapId}/{tileSize}/tiles.json:
parameters:
- $ref: '#/components/parameters/mapId'
- $ref: '#/components/parameters/tileSize'
get:
summary: TileJSON
description: 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, ...).
x-since: 1.0.0
tags:
- Maps
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/TileJSON'
'404':
$ref: '#/components/responses/404'
/maps/{mapId}/tiles:
parameters:
- $ref: '#/components/parameters/mapId'
get:
summary: OGC API - Tiles
description: Tileset landing page of the rasterized tiles. Can be used in software supporting the OGC API - Tiles v1.0 specification.
x-since: 4.6.0
tags:
- Maps
responses:
'200':
description: OK
content:
application/json:
schema:
type: string
'404':
$ref: '#/components/responses/404'
/maps/{mapId}/tileMatrixSet:
parameters:
- $ref: '#/components/parameters/mapId'
get:
summary: OGC API TileMatrixSets
description: Description of the tileset tile matrix sets according to the OGC Web API. This resource is linked from the OGC API - Tiles endpoint.
x-since: 4.6.0
tags:
- Maps
responses:
'200':
description: OK
content:
application/json:
schema:
type: string
'404':
$ref: '#/components/responses/404'
/maps/{mapId}/WMTSCapabilities.xml:
parameters:
- $ref: '#/components/parameters/mapId'
get:
summary: WMTS Capabilities
description: 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.
x-since: 1.0.0
tags:
- Maps
responses:
'200':
description: OK
content:
text/xml:
schema:
type: string
'404':
$ref: '#/components/responses/404'
/WMTSCapabilities.xml:
get:
summary: WMTS Capabilities for all layers
description: 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.
x-since: 1.0.0
tags:
- Maps
responses:
'200':
description: OK
content:
text/xml:
schema:
type: string
'404':
$ref: '#/components/responses/404'
/maps/{mapId}/wms?service=WMS&request=GetCapabilities:
parameters:
- $ref: '#/components/parameters/mapId'
get:
summary: WMS Capabilities
description: WMS Capabilities XML document describing the metadata of the map. Can be used with various GIS software (e.g. QGIS) to display the map.
x-since: 4.2.0
tags:
- Maps
responses:
'200':
description: OK
content:
text/xml:
schema:
type: string
'404':
$ref: '#/components/responses/404'
/maps/wms?service=WMS&request=GetCapabilities:
get:
summary: WMS Capabilities for all layers
description: 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.
x-since: 4.2.0
tags:
- Maps
responses:
'200':
description: OK
content:
text/xml:
schema:
type: string
'404':
$ref: '#/components/responses/404'
/maps/{mapId}/static/{lon},{lat},{zoom}/{width}x{height}{scale}.{format}:
parameters:
- $ref: '#/components/parameters/mapId'
- name: lon
in: path
description: Longitude of the center of the image.
required: true
x-since: 4.2.0
schema:
type: number
- name: lat
in: path
description: Latitude of the center of the image.
required: true
x-since: 4.2.0
schema:
type: number
- name: zoom
in: path
description: Zoom level of the resulting image (can be fractional). (In the tile pyramid based on 512x512 tiles.)
required: true
x-since: 4.2.0
schema:
type: number
- $ref: '#/components/parameters/imageWidth'
- $ref: '#/components/parameters/imageHeight'
- $ref: '#/components/parameters/rasterizationScale'
- $ref: '#/components/parameters/rasterizationFormat'
- $ref: '#/components/parameters/path'
- $ref: '#/components/parameters/markers'
- $ref: '#/components/parameters/attribution'
- $ref: '#/components/parameters/shortest'
get:
summary: Center-based image
description: Generates a raster image based on the specified center and zoom level.
x-since: 4.2.0
tags:
- Static maps
responses:
'200':
$ref: '#/components/responses/RasterizedImage'
'400':
$ref: '#/components/responses/400'
'404':
$ref: '#/components/responses/404'
'414':
$ref: '#/components/responses/414'
/maps/{mapId}/static/{minx},{miny},{maxx},{maxy}/{width}x{height}{scale}.{format}:
parameters:
- $ref: '#/components/parameters/mapId'
- name: minx
in: path
description: Longitude of the left (west) edge.
required: true
x-since: 4.2.0
schema:
type: number
- name: miny
in: path
description: Latitude of the bottom (south) edge.
required: true
x-since: 4.2.0
schema:
type: number
- name: maxx
in: path
description: Longitude of the right (east) edge.
required: true
x-since: 4.2.0
schema:
type: number
- name: maxy
in: path
description: Latitude of the top (north) edge.
required: true
x-since: 4.2.0
schema:
type: number
- $ref: '#/components/parameters/imageWidth'
- $ref: '#/components/parameters/imageHeight'
- $ref: '#/components/parameters/rasterizationScale'
- $ref: '#/components/parameters/rasterizationFormat'
- $ref: '#/components/parameters/padding'
- $ref: '#/components/parameters/path'
- $ref: '#/components/parameters/markers'
- $ref: '#/components/parameters/attribution'
- $ref: '#/components/parameters/shortest'
get:
summary: Bounds-based image
description: Generates a raster image based on the given bounds.
x-since: 4.2.0
tags:
- Static maps
responses:
'200':
$ref: '#/components/responses/RasterizedImage'
'400':
$ref: '#/components/responses/400'
'404':
$ref: '#/components/responses/404'
'414':
$ref: '#/components/responses/414'
/maps/{mapId}/static/auto/{width}x{height}{scale}.{format}:
parameters:
- $ref: '#/components/parameters/mapId'
- $ref: '#/components/parameters/imageWidth'
- $ref: '#/components/parameters/imageHeight'
- $ref: '#/components/parameters/rasterizationScale'
- $ref: '#/components/parameters/rasterizationFormat'
- $ref: '#/components/parameters/padding'
- $ref: '#/components/parameters/path'
- $ref: '#/components/parameters/markers'
- $ref: '#/components/parameters/attribution'
- $ref: '#/components/parameters/shortest'
get:
summary: Auto-fitted image
description: 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.
x-since: 4.4.0
tags:
- Static maps
responses:
'200':
$ref: '#/components/responses/RasterizedImage'
'400':
$ref: '#/components/responses/400'
'404':
$ref: '#/components/responses/404'
'414':
$ref: '#/components/responses/414'
/tiles/{tilesId}/:
parameters:
- $ref: '#/components/parameters/tilesId'
get:
summary: Embeddable HTML viewer
x-since: 1.0.0
tags:
- Tiles
responses:
'200':
description: OK
content:
text/html: {}
'404':
$ref: '#/components/responses/404'
/tiles/{tilesId}/{z}/{x}/{y}:
parameters:
- $ref: '#/components/parameters/tilesId'
- $ref: '#/components/parameters/z'
- $ref: '#/components/parameters/x'
- $ref: '#/components/parameters/y'
get:
summary: XYZ tiles
description: 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.
x-since: 1.0.0
tags:
- Tiles
responses:
'200':
description: OK
content:
'*': {}
'204':
description: Tile not present -- presumed empty (empty response)
'400':
description: Out of bounds
'404':
$ref: '#/components/responses/404'
/tiles/{tilesId}/tiles.json:
parameters:
- $ref: '#/components/parameters/tilesId'
get:
summary: TileJSON
description: 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, ...).
x-since: 1.0.0
tags:
- Tiles
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/TileJSON'
'404':
$ref: '#/components/responses/404'
/tiles/{tilesId}/tiles:
parameters:
- $ref: '#/components/parameters/tilesId'
get:
summary: OGC API - Tiles
description: Tileset landing page of the tiles. Can be used in software supporting the OGC API - Tiles v1.0 specification.
x-since: 4.6.0
tags:
- Tiles
responses:
'200':
description: OK
content:
application/json:
schema:
type: string
'404':
$ref: '#/components/responses/404'
/tiles/{tilesId}/tileMatrixSet:
parameters:
- $ref: '#/components/parameters/tilesId'
get:
summary: OGC API TileMatrixSets
description: Description of the tileset tile matrix sets according to the OGC Web API. This resource is linked from the OGC API - Tiles endpoint.
x-since: 4.6.0
tags:
- Tiles
responses:
'200':
description: OK
content:
application/json:
schema:
type: string
'404':
$ref: '#/components/responses/404'
/tiles/{tilesId}/WMTSCapabilities.xml:
parameters:
- $ref: '#/components/parameters/tilesId'
get:
summary: WMTS Capabilities
description: 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.
x-since: 1.0.0
tags:
- Tiles
responses:
'200':
description: OK
content:
text/xml:
schema:
type: string
'404':
$ref: '#/components/responses/404'
/geocoding/{query}.json:
parameters:
- name: query
in: path
description: Place name to search. You can also use bare [POI category](/server/api/geocoding/#PoiCategory) or mix it with a name to search for POIs of desired category, unless `poi` index is excluded.
examples:
place:
value: Zurich
summary: Search place name
poi:
value: restaurant mediterranean
summary: Search POI category
required: true
schema:
type: string
- $ref: '#/components/parameters/bbox'
- $ref: '#/components/parameters/proximity'
- $ref: '#/components/parameters/language'
- $ref: '#/components/parameters/country'
- $ref: '#/components/parameters/limit'
- $ref: '#/components/parameters/types'
- $ref: '#/components/parameters/excludeTypes'
- $ref: '#/components/parameters/fuzzyMatch'
- $ref: '#/components/parameters/autocomplete'
- $ref: '#/components/parameters/worldview'
get:
summary: Search by name (forward)
description: Forward geocoding (search by place name).
x-since: 4.7.0
tags:
- Geocoding
responses:
'200':
$ref: '#/components/responses/ok'
'400':
description: Query too long / Invalid parameters
/geocoding/{longitude},{latitude}.json:
parameters:
- name: longitude
in: path
example: 8.528509
required: true
schema:
type: number
minimum: -180
maximum: 180
- name: latitude
in: path
example: 47.3774434
required: true
schema:
type: number
minimum: -90
maximum: 90
- $ref: '#/components/parameters/language'
- $ref: '#/components/parameters/limit'
- $ref: '#/components/parameters/types'
- $ref: '#/components/parameters/excludeTypes'
- $ref: '#/components/parameters/worldview'
get:
summary: Search by coordinates (reverse)
description: Reverse geocoding (search by coordinates).
x-since: 4.7.0
tags:
- Geocoding
responses:
'200':
$ref: '#/components/responses/ok'
'400':
description: Query too long / Invalid parameters
/geocoding/{id}.json:
parameters:
- name: id
in: path
example: country.26561650
required: true
schema:
type: string
pattern: ^(\S+)\.([0-9]+)$
description: Feature ID (found in response of forward or reverse geocoding)
- $ref: '#/components/parameters/language'
- $ref: '#/components/parameters/worldview'
get:
summary: Search by feature ID
description: 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.
x-since: 4.7.0
tags:
- Geocoding
responses:
'200':
$ref: '#/components/responses/ok'
'400':
description: Query too long / Invalid parameters
/geocoding/{queries}.json:
parameters:
- in: path
name: queries
description: 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
required: true
schema:
type: string
- $ref: '#/components/parameters/bbox'
- $ref: '#/components/parameters/proximity'
- $ref: '#/components/parameters/language'
- $ref: '#/components/parameters/country'
- $ref: '#/components/parameters/limit'
- $ref: '#/components/parameters/types'
- $ref: '#/components/parameters/excludeTypes'
- $ref: '#/components/parameters/fuzzyMatch'
- $ref: '#/components/parameters/autocomplete'
- $ref: '#/components/parameters/worldview'
get:
summary: Batch geocoding API
description: Perform geocoding of more than one request in a single API call. Check out the Batch Geocoding guide for an example.
x-since: 4.7.0
tags:
- Geocoding
responses:
'200':
description: 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
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/result'
'400':
description: Query too long / Invalid parameters
/fonts/{fontstack}/{start}-{end}.pbf:
parameters:
- name: fontstack
in: path
description: Font name, or more comma-separated names.
required: true
x-since: 1.0.0
schema:
type: string
- name: start
in: path
description: Start of the glyph range.
required: true
x-since: 1.0.0
schema:
type: integer
multipleOf: 256
- name: end
in: path
description: End of the glyph range (last glyph index).
required: true
x-since: 1.0.0
schema:
type: integer
get:
summary: Font glyphs
description: Generates the glyphs for the requested fonts. Used when displaying vector maps.
x-since: 1.0.0
tags:
- Other
responses:
'200':
description: OK
content:
application/x-protobuf: {}
'400':
description: Invalid glyph range
/ogc/conformance:
get:
summary: OGC API conformance classes
description: Declaration of the implemented conformance classes.
x-since: 4.6.0
tags:
- Other
responses:
'200':
description: OK
content:
application/json:
schema:
type: string
components:
parameters:
mapId:
name: mapId
in: path
description: Identifier of the map. See MapTiler Server Maps `http://localhost:3650/admin/`.
example: streets
required: true
x-since: 1.0.0
schema:
type: string
rasterizationScale:
name: scale
in: path
description: Use "@2x" to get "retina"/HiDPI image.
required: false
x-since: 4.2.0
schema:
type: string
enum:
- '@2x'
tileSize:
name: tileSize
in: path
required: false
x-since: 1.0.0
schema:
type: integer
enum:
- '256'
z:
name: z
description: Zoom level. Specifies the tile's zoom level. See [Tiles à la Google Maps](https://docs.maptiler.com/google-maps-coordinates-tile-bounds-projection/)
in: path
required: true
x-since: 1.0.0
schema:
type: integer
x:
name: x
description: Column. Specifies the tile's column. See [Tiles à la Google Maps](https://docs.maptiler.com/google-maps-coordinates-tile-bounds-projection/)
in: path
required: true
x-since: 1.0.0
schema:
type: integer
'y':
name: 'y'
description: Row. Specifies the tile's row. See [Tiles à la Google Maps](https://docs.maptiler.com/google-maps-coordinates-tile-bounds-projection/)
in: path
required: true
x-since: 1.0.0
schema:
type: integer
rasterizationFormat:
name: format
in: path
description: The value depends on the Map settings.
required: true
x-since: 4.2.0
schema:
type: string
enum:
- png
- jpg
- webp
imageWidth:
name: width
in: path
description: Width of the image in pixels.
required: true
x-since: 4.2.0
schema:
type: integer
imageHeight:
name: height
in: path
description: Height of the image in pixels.
required: true
x-since: 4.2.0
schema:
type: integer
path:
name: path
in: query
description: Define path(s) to be drawn on top of the map. Can be used multiple times. See [Static maps in MapTiler Server](/guides/self-hosting/map-server/static-maps-in-maptiler-server).
required: false
x-since: 4.4.0
schema:
type: string
pattern: ((fill|stroke|width|shortest)\:[^\|]+\|)*((enc:.+)|((-?\d+\.?\d*,-?\d+\.?\d*\|)+(-?\d+\.?\d*,-?\d+\.?\d*)))
markers:
name: markers
in: query
description: Define marker(s) to be drawn on top of the map. Can be used multiple times. See [Static maps in MapTiler Server](/guides/self-hosting/map-server/static-maps-in-maptiler-server).
required: false
x-since: 4.4.0
schema:
type: string
pattern: ((icon|anchor|scale)\:[^\|]+\|)*((-?\d+\.?\d*,-?\d+\.?\d*(,[^\|]+)?\|)+(-?\d+\.?\d*,-?\d+\.?\d*(,[^\|]+)?))
attribution:
name: attribution
in: query
description: Changes the position of map attribution. If you disable the attribution make sure to display it in your application yourself (visibly).
required: false
x-since: 4.4.0
default: bottomright
schema:
type: string
enum:
- bottomright
- bottomleft
- topleft
- topright
- 'false'
shortest:
name: shortest
in: query
description: Draw the shortest paths, allow to cross the dateline.
required: false
x-since: 4.4.0
default: false
schema:
type: boolean
padding:
name: padding
in: query
description: 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.
required: false
x-since: 4.4.0
default: 0.1
schema:
type: number
tilesId:
name: tilesId
in: path
description: Identifier of the tiles. See MapTiler Server Tiles `http://localhost:3650/admin/tiles/`.
example: maptiler-satellite
required: true
x-since: 1.0.0
schema:
type: string
bbox:
schema:
$ref: '#/components/schemas/bbox'
example: 5.9559,45.818,10.4921,47.8084
in: query
name: bbox
required: false
description: A `[w, s, e, n]` bounding box array to use for limiting search results. Only features inside the provided bounding box will be included.
explode: false
proximity:
schema:
anyOf:
- $ref: '#/components/schemas/coordinates'
- $ref: '#/components/schemas/ip'
example: 8.528509,47.3774434
in: query
name: proximity
required: false
description: 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.
explode: false
language:
schema:
type: array
maxItems: 20
uniqueItems: true
items:
type: string
example: en
enum:
- 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
example: de,en
example: de,en
in: query
name: language
required: false
description: 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.
explode: false
country:
schema:
type: array
uniqueItems: true
items:
type: string
example: sk,cz
example: sk,cz
in: query
name: country
required: false
description: Limit search to specific country/countries.
explode: false
limit:
schema:
type: integer
default: 5
minimum: 1
maximum: 10
in: query
name: limit
required: false
description: Maximum number of results to return. For reverse geocoding with multiple types this must not be set or must be set to 1.
types:
schema:
type: array
uniqueItems: true
items:
$ref: '#/components/schemas/placeType'
in: query
name: types
required: false
description: Filter types of which features to return. If not specified, default configuration of API is used (see [PlaceTypeValues](/server/api/geocoding/#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.
excludeTypes:
schema:
type: boolean
default: false
in: query
name: excludeTypes
required: false
description: Set to `true` to use all available feature types except those specified in `types`.
fuzzyMatch:
schema:
type: boolean
default: true
in: query
name: fuzzyMatch
required: false
description: Set to `false` to disable fuzzy search.
autocomplete:
schema:
type: boolean
in: query
name: autocomplete
required: false
description: Set to `true` to use autocomplete, `false` to disable autocomplete.
default: true
worldview:
schema:
type: string
example: ch
enum:
- default
- auto
- ae
- ch
- jp
- kr
- us
name: worldview
required: false
x-since: 4.8.0
in: query
description: |
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.
example: ch
default: default
responses:
'400':
description: Out of bounds / Invalid format
'403':
description: Key is missing, invalid or restricted
'404':
description: The item does not exist
'414':
description: URI Too Long. Maximum allowed length is 8192 bytes.
RasterizedImage:
description: OK
content:
image/*:
schema:
type: string
format: binary
ok:
description: Search result represented as FeatureCollection where every item is represented as a GeoJSON Feature
content:
application/json:
schema:
$ref: '#/components/schemas/result'
schemas:
StyleJSON:
type: object
description: Style JSON object
externalDocs:
url: https://docs.maptiler.com/gl-style-specification/
TileJSON:
type: object
externalDocs:
url: https://raw.githubusercontent.com/maptiler/tilejson-spec/master/2.2.0/schema.json
bbox:
example:
- 5.9559
- 45.818
- 10.4921
- 47.8084
type: array
title: BoundingBox
prefixItems:
- type: number
minimum: -180
maximum: 180
description: minimal longitude
- type: number
minimum: -90
maximum: 90
description: minimal latitude
- type: number
minimum: -180
maximum: 180
description: maximal longitude
- type: number
minimum: -90
maximum: 90
description: maximal latitude
coordinates:
example:
- 8.528509
- 47.3774434
type: array
title: Coordinates
prefixItems:
- type: number
minimum: -180
maximum: 180
description: longitude
- type: number
minimum: -90
maximum: 90
description: latitude
ip:
type: string
title: IP
description: Server-side IP based geolocation
const: ip
placeType:
type: string
title: PlaceType
description: Check out the [descriptions and default values](https://docs.maptiler.com/server/api/geocoding/#PlaceTypeValues) of each of the PlaceType values
enum:
- continental_marine
- country
- major_landform
- region
- subregion
- county
- joint_municipality
- joint_submunicipality
- municipality
- municipal_district
- locality
- neighbourhood
- place
- postal_code
- address
- road
- poi
commonProperties:
title: CommonProperties
type: object
additionalProperties: true
properties:
id:
description: Unique feature ID
type: string
example: municipality.46425
text:
description: Localized feature name
type: string
example: Paris
language:
description: Query's primary ISO 639-1 language code
type: string
example: en
patternProperties:
^text_(\w\w):
type: string
description: 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):
type: string
description: 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.
required:
- id
- text
featureProperties:
title: FeatureProperties
type: object
additionalProperties: true
properties:
ref:
description: (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.
type: string
example: osm:r71525
country_code:
type: string
description: ISO 3166-1 alpha-2 country code of the feature
example: fr
kind:
type: string
description: (experimental) Kind of the feature
enum:
- road
- road_relation
- admin_area
- place
- street
- virtual_street
categories:
type: array
description: Array of [POI category](/server/api/geocoding/#PoiCategory). Only available for `poi` type. Category values may change in the near future.
minItems: 1
items:
type: string
example: restaurant
feature_tags:
type: object
title: Feature tags
description: (experimental) Feature tags, only available for `poi` type. They can include e.g. working hours, type of amenity or wheelchair access.
additionalProperties:
type: string
place_designation:
type: string
title: Place designation
enum:
- allotments
- borough
- city
- city_block
- farm
- hamlet
- isolated_dwelling
- neighbourhood
- plot
- quarter
- suburb
- town
- village
description:
(experimental) Additional information about the feature. The main use case is to determine if the administrative area represents an inhabited place (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). Please note
that this field is not always filled.
example: city
required:
- ref
- country_code
result:
description: Search result represented by FeatureCollection where every item is represented as a GeoJSON Feature
type: object
title: SearchResults
properties:
type:
type: string
const: FeatureCollection
features:
description: Array of features found
type: array
title: Feature
items:
allOf:
- $ref: '#/components/schemas/commonProperties'
- type: object
patternProperties:
^place_name_(\w\w):
type: string
description: 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.
properties:
type:
type: string
const: Feature
properties:
description: Feature properties
$ref: '#/components/schemas/featureProperties'
geometry:
anyOf:
- type: object
title: Point
properties:
type:
type: string
const: Point
coordinates:
$ref: '#/components/schemas/coordinates'
required:
- type
- coordinates
- type: object
title: LineString
properties:
type:
type: string
const: LineString
coordinates:
minItems: 2
type: array
items:
$ref: '#/components/schemas/coordinates'
required:
- type
- coordinates
- type: object
title: Polygon
properties:
type:
type: string
const: Polygon
coordinates:
type: array
items:
minItems: 4
type: array
items:
$ref: '#/components/schemas/coordinates'
required:
- type
- coordinates
- type: object
title: MultiPoint
properties:
type:
type: string
const: MultiPoint
coordinates:
type: array
items:
$ref: '#/components/schemas/coordinates'
required:
- type
- coordinates
- type: object
title: MultiLineString
properties:
type:
type: string
const: MultiLineString
coordinates:
type: array
items:
minItems: 2
type: array
items:
$ref: '#/components/schemas/coordinates'
required:
- type
- coordinates
- type: object
title: MultiPolygon
properties:
type:
type: string
const: MultiPolygon
coordinates:
type: array
items:
type: array
items:
minItems: 4
type: array
items:
$ref: '#/components/schemas/coordinates'
required:
- type
- coordinates
- type: object
title: GeometryCollection
properties:
type:
type: string
const: GeometryCollection
geometries:
type: array
items:
anyOf:
- type: object
title: Point
properties:
type:
type: string
const: Point
coordinates:
$ref: '#/components/schemas/coordinates'
required:
- type
- coordinates
- type: object
title: LineString
properties:
type:
type: string
const: LineString
coordinates:
minItems: 2
type: array
items:
$ref: '#/components/schemas/coordinates'
required:
- type
- coordinates
- type: object
title: Polygon
properties:
type:
type: string
const: Polygon
coordinates:
type: array
items:
minItems: 4
type: array
items:
$ref: '#/components/schemas/coordinates'
required:
- type
- coordinates
- type: object
title: MultiPoint
properties:
type:
type: string
const: MultiPoint
coordinates:
type: array
items:
$ref: '#/components/schemas/coordinates'
required:
- type
- coordinates
- type: object
title: MultiLineString
properties:
type:
type: string
const: MultiLineString
coordinates:
type: array
items:
minItems: 2
type: array
items:
$ref: '#/components/schemas/coordinates'
required:
- type
- coordinates
- type: object
title: MultiPolygon
properties:
type:
type: string
const: MultiPolygon
coordinates:
type: array
items:
type: array
items:
minItems: 4
type: array
items:
$ref: '#/components/schemas/coordinates'
required:
- type
- coordinates
required:
- type
- geometries
bbox:
description: Bounding box of the original feature as `[w, s, e, n]` array
$ref: '#/components/schemas/bbox'
center:
description: A `[lon, lat]` array of the original feature centeroid
$ref: '#/components/schemas/coordinates'
place_name:
description: Formatted (including the hierarchy) and localized feature full name
type: string
matching_place_name:
description: 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.
type: string
matching_text:
description: 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.
type: string
place_type:
description: An array of feature types describing the feature. Currently each feature has only single type but this may change in the future.
type: array
items:
$ref: '#/components/schemas/placeType'
place_type_name:
type: array
description: Localized type of the place name, matches `place_type` property.
items:
type: string
relevance:
description: 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.
type: number
context:
description: Feature hierarchy
type: array
title: Context
items:
allOf:
- $ref: '#/components/schemas/featureProperties'
- $ref: '#/components/schemas/commonProperties'
address:
description: Address number, if applicable
type: string
required:
- type
- properties
- geometry
- bbox
- center
- place_name
- place_type
- place_type_name
- relevance
query:
description: Tokenized search query
type: array
items:
type: string
attribution:
description: Attribution of the result
type: string
example: © MapTiler © OpenStreetMap contributors
required:
- type
- features
- query
- attribution
GeoJSON:
type: object
externalDocs:
url: https://tools.ietf.org/html/rfc7946