openapi: 3.0.0
servers:
  - url: https://api.tomtom.com
info:
  contact:
    x-twitter: TomTom
  description: |-
    The Maps API web services suite offers the following APIs:
      - Raster
      The Maps Raster API renders map data that is divided into gridded sections called tiles. Tiles are square images (png or jpg format) in various sizes which are available at 19 different zoom levels, ranging from 0 to 20. For zoom level 0, the entire earth is displayed on one single tile, while at zoom level 20, the world is divided into 2<sup>40</sup> tiles.
      - Vector
      Similar to Maps Raster API, the Maps Vector API serves data on different zoom level ranging from 0 to 22. For zoom level 0, the entire earth is displayed on one single tile, while at zoom level 22, the world is divided into 2<sup>44</sup> tiles.
      The Maps Vector Service delivers geographic map data packaged in a vector representation of squared sections called vector tiles. Each tile includes pre-defined collections of map features (points, lines, road shapes, water polygons, building footprints, ect.) delivered in one of the specified vector formats. Format of the tile is formally described using protobuf schema.
  title: Maps
  version: 1.0.0
  x-apisguru-categories:
    - location
  x-logo:
    url: https://twitter.com/TomTom/profile_image?size=original
  x-origin:
    - converter:
        url: https://github.com/lucybot/api-spec-converter
        version: 2.7.31
      format: openapi
      url: https://developer.tomtom.com/system/files/swagger_models/maps_api_0.yaml
      version: "3.0"
  x-providerName: tomtom.com
  x-serviceName: maps
security:
  - api_key: []
paths:
  "/map/{versionNumber}/copyrights.{format}":
    get:
      description: |-
        The Copyrights API returns copyright information for
        the Maps API Raster Tile Service in JSON, JSONP, or XML format.
        This call returns copyright information for the whole world.
      parameters:
        - description: Version of the service to call. The current version is 1
          in: path
          name: versionNumber
          required: true
          schema:
            enum:
              - 1
            type: integer
        - description: Format of the response
          in: path
          name: format
          required: true
          schema:
            default: xml
            enum:
              - json
              - jsonp
              - xml
            type: string
        - description: Specifies the jsonp callback method. Only used when format is jsonp
          in: query
          name: callback
          required: false
          schema:
            type: string
      responses:
        "200":
          description: <b>OK</b>
        "304":
          description: <b>Not Modified</b>
        "400":
          description: |-
            <b>Malformed request</b>: malformed syntax. Possible causes include:
              - requested syntax is not available
        "403":
          description: "<b>Forbidden</b>: Supplied API key is not valid for this request"
        "410":
          description: "<b>Gone</b>: Request for unsupported format"
        "500":
          description: |-
            <b>Internal Server Error</b>: There is a problem with the TomTom Copyrights
            API service
      summary: Copyrights Whole World
      tags:
        - Copyrights
  "/map/{versionNumber}/copyrights/caption.{format}":
    get:
      description: This API returns copyright captions for the map service.
      parameters:
        - description: Version of the service to call. The current version is 1.
          in: path
          name: versionNumber
          required: true
          schema:
            enum:
              - 1
            type: integer
        - description: Format of the response
          in: path
          name: format
          required: true
          schema:
            default: xml
            enum:
              - json
              - jsonp
              - xml
            type: string
        - description: Specifies the jsonp callback method. Only used when format is jsonp
          in: query
          name: callback
          required: false
          schema:
            type: string
      responses:
        "200":
          description: <b>OK</b>
        "304":
          description: <b>Not Modified</b>
        "400":
          description: |-
            <b>Malformed request</b>: malformed syntax. Possible causes include:
              - requested syntax is not available
        "403":
          description: "<b>Forbidden</b>: Supplied API key is not valid for this request"
        "410":
          description: "<b>Gone</b>: Request for unsupported format"
        "500":
          description: |-
            <b>Internal Server Error</b>: There is a problem with the TomTom Copyrights
            API service
      summary: Captions
      tags:
        - Copyrights
  "/map/{versionNumber}/copyrights/{minLon}/{minLat}/{maxLon}/{maxLat}.{format}":
    get:
      description: |-
        The Copyrights API returns copyright information for
        the Maps API Raster Tile Service in JSON, JSONP, or XML format.
        This call returns copyright information for a specific bounding box.
      parameters:
        - description: Version of the service to call. The current version is 1
          in: path
          name: versionNumber
          required: true
          schema:
            enum:
              - 1
            type: integer
        - description: Format of the response
          in: path
          name: format
          required: true
          schema:
            default: xml
            enum:
              - json
              - jsonp
              - xml
            type: string
        - description: Minimum longitude coordinate of bounding box defined in terms of latitude/longitude.
          example: -179.1506
          in: path
          name: minLon
          required: true
          schema:
            type: number
        - description: Minimum latitude coordinate of bounding box defined in terms of latitude/longitude.
          example: 18.9117
          in: path
          name: minLat
          required: true
          schema:
            type: number
        - description: Maximum longitude coordinate of bounding box defined in terms of latitude/longitude.
          example: -66.9406
          in: path
          name: maxLon
          required: true
          schema:
            type: number
        - description: Maximum latitude coordinate of bounding box defined in terms of latitude/longitude.
          example: 71.441
          in: path
          name: maxLat
          required: true
          schema:
            type: number
        - description: Specifies the jsonp callback method. Only used when format is jsonp.
          in: query
          name: callback
          required: false
          schema:
            type: string
      responses:
        "200":
          description: <b>OK</b>
        "304":
          description: <b>Not Modified</b>
        "400":
          description: |-
            <b>Malformed request</b>: malformed syntax. Possible causes include:
              - requested syntax is not available
        "401":
          description: |-
            <b>Bad request</b>: Parameters out of range. Possible causes include:
              - minLon n is out of range [-180,180]: the requested minimum longitude coordinate is out of possible range
              - minLat n is out of range [-90,90]: the requested minimum latitude coordinate is out of possible range
              - maxLon n is out of range [-180,180]: the requested maximum longitude coordinate is out of possible range
              - maxLat n is out of range [-90,90]: the requested minimum latitude coordinate is out of possible range
        "403":
          description: "<b>Forbidden</b>: Supplied API key is not valid for this request"
        "410":
          description: "<b>Gone</b>: Request for unsupported format"
        "500":
          description: |-
            <b>Internal Server Error</b>: There is a problem with the TomTom Copyrights
            API service
      summary: Copyrights Bounding Box
      tags:
        - Copyrights
  "/map/{versionNumber}/copyrights/{zoom}/{X}/{Y}.{format}":
    get:
      description: |-
        The Copyrights API returns copyright information for
        the Maps API Raster Tile Service in JSON, JSONP, or XML format.
        This call returns copyright information for the a specific map tile.
      parameters:
        - description: Version of the service to call. The current version is 1
          in: path
          name: versionNumber
          required: true
          schema:
            enum:
              - 1
            type: integer
        - description: Format of the response
          in: path
          name: format
          required: true
          schema:
            default: xml
            enum:
              - json
              - jsonp
              - xml
            type: string
        - description: |-
            Zoom level of tile to be rendered. Only used for tile-level
            copyright calls.
          example: 0
          in: path
          name: zoom
          required: true
          schema:
            enum:
              - 0
              - 1
              - 2
              - 3
              - 4
              - 5
              - 6
              - 7
              - 8
              - 9
              - 10
              - 11
              - 12
              - 13
              - 14
              - 15
              - 16
              - 17
              - 18
            type: integer
        - description: |-
            X coordinate of the tile on zoom grid. Only used for tile-level
            copyright calls.
          example: 0
          in: path
          name: X
          required: true
          schema:
            type: integer
        - description: |-
            Y coordinate of the tile on zoom grid. Only used for tile-level
            copyright calls.
          example: 0
          in: path
          name: Y
          required: true
          schema:
            type: integer
        - description: Specifies the jsonp callback method. Only used when format is jsonp.
          in: query
          name: callback
          required: false
          schema:
            type: string
      responses:
        "200":
          description: <b>OK</b>
        "304":
          description: <b>Not Modified</b>
        "400":
          description: |-
            <b>Malformed request</b>: malformed syntax. Possible causes include:
              - requested syntax is not available
        "401":
          description: |-
            <b>Bad request</b>: Parameters out of range. Possible causes include:
              - zoom n is out of range 0 <= zoom < 19: the requested zoom level is out of the possible range
              - x n is out of range [0,m]: the requested x coordinate is out of the possible range (the value of m will vary depending on zoom level)
              - y n is out of range [0,m]: the requested y coordinate is out of the possible range (the value of m will vary depending on zoom level)
        "403":
          description: "<b>Forbidden</b>: Supplied API key is not valid for this request"
        "410":
          description: "<b>Gone</b>: Request for unsupported format"
        "500":
          description: |-
            <b>Internal Server Error</b>: There is a problem with the TomTom Copyrights
            API service
      summary: Copyrights Tile
      tags:
        - Copyrights
  "/map/{versionNumber}/staticimage":
    get:
      description: |-
        The Static Image service renders a rectangular raster image
        in the style, size, and zoom level specified. The image can be requested
        using either a center point plus width and height or a bounding box.
      parameters:
        - description: Version of the service to call. The current version is 1.
          in: path
          name: versionNumber
          required: true
          schema:
            enum:
              - 1
            type: integer
        - description: |-
            Layer of image to be rendered. <em>Hybrid</em> and <em>labels</em>
            are intended for layering with other data and are only available in <em>png</em> format.
          example: basic
          in: query
          name: layer
          required: false
          schema:
            default: basic
            enum:
              - basic
              - hybrid
              - labels
            type: string
        - description: Map style to be returned
          example: main
          in: query
          name: style
          required: false
          schema:
            default: main
            enum:
              - main
              - night
            type: string
        - description: Image format to be returned
          example: png
          in: query
          name: format
          required: false
          schema:
            default: png
            enum:
              - png
              - jpg
              - jpeg
            type: string
        - description: Zoom level of map image to be returned.
          in: query
          name: zoom
          required: false
          schema:
            default: 12
            enum:
              - 0
              - 1
              - 2
              - 3
              - 4
              - 5
              - 6
              - 7
              - 8
              - 9
              - 10
              - 11
              - 12
              - 13
              - 14
              - 15
              - 16
              - 17
              - 18
              - 19
              - 20
              - 21
              - 22
            type: integer
        - description: |-
            Coordinates for the center point of the image.
            Must be used with the <strong>width</strong> and
            <strong>height</strong> parameters; cannot be used with <strong>bbox</strong>.
            Uses EPSG:3857 projection (functionally equivalent to EPSG:900910).
          example: 4.899886, 52.379031
          in: query
          name: center
          required: false
          schema:
            pattern: ^-*\d+\.*\d*, *-*\d+\.*\d*$
            type: string
        - description: Width of the resulting image in pixels. Width must be a positive integer between 1 and 8192.
          example: 512
          in: query
          name: width
          required: false
          schema:
            default: 512
            maximum: 8192
            minimum: 1
            type: integer
        - description: Height of the resulting image in pixels. Height must be a positive integer between 1 and 8192.
          example: 512
          in: query
          name: height
          required: false
          schema:
            default: 512
            maximum: 8192
            minimum: 1
            type: integer
        - description: |-
            Bounding box for the image, using EPSG:3857 projection (functionally equivalent to EPSG:900910).
            Values <strong>must</strong> be in the order of minLon, minLat, maxLon, maxLat.
            MaxLat must be greater than minLat. Longitude values can be on both sides of the 180th meridian.
            Cannot be used with <strong>center</strong>, <strong>width</strong>, or <strong>height</strong> parameters.
          in: query
          name: bbox
          required: false
          schema:
            pattern: ^(-*\d+\.*\d*,){3}(-*\d+\.*\d*)$
            type: string
        - description: Geopolitical view. Determines rendering of disputed areas. See the <a href="/maps-api/maps-api-documentation-raster/raster-tile">documentation</a> for an explanation of how this works in live services.
          example: Unified
          in: query
          name: view
          required: false
          schema:
            enum:
              - Unified
              - IN
            type: string
      responses:
        "200":
          description: <b>OK</b>
        "400":
          description: |-
            <b>Bad Request</b>: Received by the interface, but there is an error
            in the request, such as:
              - one or more of the required parameters is missing
              - unsupported or unrecognized parameter value
              - two or more mutually exclusive parameters are used in the same query (e.g. mixing center/width/height and bbox.)
              - minimum latitude is greater than maximum latitude in a bbox call
              - layer containing alpha channel is requested in format not supporting the alpha channel
            This code is returned if the required parameters of the request were
            malformed. A detailed exception explanation is returned in a
            response in form of Service Exception Report.
        "403":
          description: |-
            <b>Forbidden</b>:
              - supplied API key is not valid for the request
              - the requested view is not available in the country where the request was sent from
        "500":
          description: |-
            <b>Internal Server Error</b>: There is a problem with the Static Map
            Service.
        "503":
          description: <b>Service currently unavailable.</b>
      summary: Static Image
      tags:
        - Raster
  "/map/{versionNumber}/tile/{layer}/{style}/{zoom}/{X}/{Y}.pbf":
    get:
      description: The Maps API Vector Service delivers vector tiles, which are representations of square sections of map data.
      parameters:
        - description: Version of the service to call. The current version is 1
          in: path
          name: versionNumber
          required: true
          schema:
            enum:
              - 1
            type: integer
        - description: Layer of tile to be rendered
          example: basic
          in: path
          name: layer
          required: true
          schema:
            enum:
              - basic
              - hybrid
              - labels
            type: string
        - description: Style of tile to be rendered
          example: main
          in: path
          name: style
          required: true
          schema:
            enum:
              - main
            type: string
        - description: Zoom level of tile to be rendered
          example: 0
          in: path
          name: zoom
          required: true
          schema:
            enum:
              - 0
              - 1
              - 2
              - 3
              - 4
              - 5
              - 6
              - 7
              - 8
              - 9
              - 10
              - 11
              - 12
              - 13
              - 14
              - 15
              - 16
              - 17
              - 18
              - 19
              - 20
              - 21
              - 22
            type: integer
        - description: x coordinate of tile on zoom grid
          example: 0
          in: path
          name: X
          required: true
          schema:
            type: integer
        - description: y coordinate of tile on zoom grid
          example: 0
          in: path
          name: Y
          required: true
          schema:
            type: integer
        - description: Geopolitical view. Determines rendering of disputed areas. See the <a href="/maps-api/maps-api-documentation-vector/tile">documentation</a> for an explanation of how this works in live services.
          example: Unified
          in: query
          name: view
          required: false
          schema:
            enum:
              - Unified
              - IL
              - IN
            type: string
        - description: "Language to be used for labels in the response. The default is NGT: Neutral Ground Truth, which uses each place's local official language and script (where available). See the <a href=\"/maps-api/maps-api-documentation-vector/tile\">documentation</a> for a full list of options."
          in: query
          name: language
          schema:
            default: NGT
            type: string
      responses:
        "200":
          description: <b>OK</b>
        "400":
          description: |-
            <b>Bad request</b>: Usually the result of malformed syntax:
              - the given combination of layer, style, and query parameters is not supported
              - zoom n is out of range 0 <= zoom <= 22: the requested zoom level is out of the possible range
              - x n is out of range [0,m]: the requested x coordinate is out of the possible range (the value of m will vary depending on zoom level)
              - y n is out of range [0,m]: the requested y coordinate is out of the possible range (the value of m will vary depending on zoom level)
              - the requested view is not supported
        "403":
          description: |-
            <b>Forbidden</b>: 
              - the supplied API key is not valid for this request
              - the requested view is not available in your country
        "500":
          description: |-
            <b>Internal Server Error</b>: There is a problem with the TomTom
            Maps API Vector Tile service
        "503":
          description: <b>Service currently unavailable</b>.
      summary: Tile
      tags:
        - Vector
  "/map/{versionNumber}/tile/{layer}/{style}/{zoom}/{X}/{Y}.{format}":
    get:
      description: The Maps API Raster Service delivers raster tiles, which are representations of square sections of map data.
      parameters:
        - description: Version of the service to call. The current version is 1.
          in: path
          name: versionNumber
          required: true
          schema:
            enum:
              - 1
            type: integer
        - description: Layer of tile to be rendered. <em>Hybrid</em> and <em>labels</em> are intended for layering with other data and are only available in <em>png</em> format.
          example: basic
          in: path
          name: layer
          required: true
          schema:
            enum:
              - basic
              - hybrid
              - labels
            type: string
        - description: Style of tile to be rendered
          example: main
          in: path
          name: style
          required: true
          schema:
            enum:
              - main
              - night
            type: string
        - description: Zoom level of tile to be rendered
          example: 0
          in: path
          name: zoom
          required: true
          schema:
            enum:
              - 0
              - 1
              - 2
              - 3
              - 4
              - 5
              - 6
              - 7
              - 8
              - 9
              - 10
              - 11
              - 12
              - 13
              - 14
              - 15
              - 16
              - 17
              - 18
              - 19
              - 20
              - 21
              - 22
            type: integer
        - description: x coordinate of tile on zoom grid
          example: 0
          in: path
          name: X
          required: true
          schema:
            type: integer
        - description: y coordinate of tile on zoom grid
          example: 0
          in: path
          name: Y
          required: true
          schema:
            type: integer
        - description: Format of the response.
          example: png
          in: path
          name: format
          required: true
          schema:
            enum:
              - jpg
              - png
            type: string
        - description: Tile dimensions in pixels. <em>512</em> is only available for the <em>main</em> style and <em>basic</em> or <em>labels</em> layers.
          in: query
          name: tileSize
          required: false
          schema:
            default: 256
            enum:
              - 256
              - 512
            type: integer
        - description: Geopolitical view. Determines rendering of disputed areas. See the <a href="/maps-sdk-web/functional-examples#geopolitical-views">documentation</a> for an explanation of how this works in live services.
          example: Unified
          in: query
          name: view
          required: false
          schema:
            enum:
              - Unified
              - IN
            type: string
      responses:
        "200":
          description: <b>OK</b>
        "302":
          description: "<b>Found</b>: URL redirection"
        "400":
          description: |-
            <b>Bad request</b>: Usually the result of malformed syntax:
              - the given combination of layer, style, and query parameters is not supported
              - zoom n is out of range 0 <= zoom < 19: the requested zoom level is out of the possible range
              - x n is out of range [0,m]: the requested x coordinate is out of the possible range (the value of m will vary depending on zoom level)
              - y n is out of range [0,m]: the requested y coordinate is out of the possible range (the value of m will vary depending on zoom level)
              - the requested view is not supported
        "403":
          description: |-
            <b>Forbidden</b>:
              - the supplied API key is not valid for this request
              - the requested view is not available in the country where the request was sent from
        "410":
          description: "<b>Gone</b>: Request for unsupported format"
        "500":
          description: |-
            <b>Internal Server Error</b>: There is a problem with the TomTom
            Maps API Raster Tile service
      summary: Tile
      tags:
        - Raster
  "/map/{versionNumber}/wms/":
    get:
      description: |-
        The GetMap call implements the Web Map Service 1.1.1 standard
        to access TomTom raster map tiles. This service is described
        in the response to the GetCapabilities API call.
      operationId: GetMap
      parameters:
        - description: Version of the service to call. The current version is 1
          in: path
          name: versionNumber
          required: true
          schema:
            enum:
              - 1
            type: integer
        - description: Request type
          in: query
          name: request
          required: true
          schema:
            enum:
              - GetMap
            type: string
        - description: |-
            Projection used in describing the <b>bbox</b> EPSG:3857 is
            recommended, particularly at higher zoom levels. (Note that
            EPSG:3857 is functionally equivalent to EPSG:900913/EPSG:3785)
          example: EPSG:4326
          in: query
          name: srs
          required: true
          schema:
            enum:
              - EPSG:3857
              - EPSG:4326
            type: string
        - description: |-
            Bounding box in the projection stated in <b>srs</b>
            (minLon,minLat,maxLon,maxLat)
          example: -0.489,51.28,0.236,51.686
          in: query
          name: bbox
          required: true
          schema:
            pattern: ^(-*\d+\.*\d*, *){3}(-*\d+\.*\d*)$
            type: string
        - description: Width of the resulting image, in pixels Maximum value is 2048
          example: 512
          in: query
          name: width
          required: true
          schema:
            type: integer
        - description: Height of the resulting image, in pixels Maximum value is 2048
          example: 512
          in: query
          name: height
          required: true
          schema:
            type: integer
        - description: Image format to be returned
          example: image/png
          in: query
          name: format
          required: true
          schema:
            enum:
              - image/jpeg
              - image/png
            type: string
        - description: Map layers requested Currently only the basic layer is available
          in: query
          name: layers
          required: true
          schema:
            enum:
              - basic
            type: string
        - allowEmptyValue: true
          description: |-
            Map styles to be returned. Currently, no styles are available. This
            parameter is present for forward compatibility; it must be used and
            left blank.
          in: query
          name: styles
          required: false
          schema:
            enum:
              - ""
            type: string
        - description: Service type
          in: query
          name: service
          required: false
          schema:
            enum:
              - WMS
            type: string
        - description: WMS service version
          in: query
          name: version
          required: true
          schema:
            enum:
              - 1.1.1
            type: string
      responses:
        "200":
          description: <b>OK</b>
        "202":
          description: |-
            <b>Accepted</b>: Received by the interface, but there is a WMS exception in
            processing it. Possible causes include:
              - one or more required parameters is missing
              - unsupported or unrecognized parameter value
              - malformed bounding box requested
              - invalid map dimensions requested































              
            This code is returned if the parameters of the request were malformed.
            The response includes a detailed explanation in the Service Exception Report.
        "401":
          description: "<b>Unauthorized</b>: Supplied API key is not valid for the request"
        "500":
          description: |-
            <b>Internal Server Error</b>: There is a problem with the TomTom WMS
            service
      summary: GetMap
      tags:
        - WMS / WMTS
  "/map/{versionNumber}/wms//":
    get:
      description: |-
        The GetCapabilities call is part of TomTom's implementation of version 1.1.1
        the Web Map Service (WMS). It provides descriptions of the other calls
        that are available in the implementation.
      operationId: GetCapabilities
      parameters:
        - in: path
          name: versionNumber
          required: true
          schema:
            enum:
              - 1
            type: integer
        - in: query
          name: service
          required: true
          schema:
            enum:
              - WMS
            type: string
        - in: query
          name: request
          required: true
          schema:
            enum:
              - GetCapabilities
            type: string
        - description: WMS service version
          in: query
          name: version
          required: false
          schema:
            enum:
              - 1.1.1
            type: string
      responses:
        "200":
          description: <b>OK</b>
        "202":
          description: |-
            <b>Accepted</b>: Received by the interface, but there is a WMS exception in
            processing it. Possible causes include:
              - one or more required parameters is missing
              - unsupported or unrecognized parameter value
              - malformed bounding box requested
              - invalid map dimensions requested































              
            This code is returned if the parameters of the request were malformed.
            The response includes a detailed explanation in the Service Exception Report.
        "401":
          description: "<b>Unauthorized</b>: Supplied API key is not valid for the request"
        "500":
          description: |-
            <b>Internal Server Error</b>: There is a problem with the TomTom WMS
            service
      summary: GetCapabilities
      tags:
        - WMS / WMTS
  "/map/{versionNumber}/wmts/{key}/{wmtsVersion}/WMTSCapabilities.xml":
    get:
      description: |-
        The WMTS GetCapabilities call implements version 1.0.0 of
        the <a href="http://www.opengeospatial.org/standards/wmts">Web Map Tile Service</a>
        (WMTS) standard. It returns metadata that allows compatible calling systems to construct
        calls to TomTom's raster map tile service. See the
        <a href="/maps-api/maps-api-documentation-raster/wmts">documentation</a>
        for more information on WMTS.
      parameters:
        - description: Version of the service to call. The current version is 1
          in: path
          name: versionNumber
          required: true
          schema:
            enum:
              - 1
            type: integer
        - description: Your API key for calling this service.
          in: path
          name: key
          required: true
          schema:
            type: string
        - in: path
          name: wmtsVersion
          required: true
          schema:
            enum:
              - 1.0.0
            type: string
      responses:
        "200":
          description: <b>OK</b>
        "400":
          description: "<b>Bad request</b>: Probably malformed syntax"
        "401":
          description: "<b>Unauthorized</b>: Supplied API key is not valid for this request"
        "500":
          description: "<b>Internal Server Error</b>: There is a problem with the TomTom WMTS service"
      security: []
      summary: WMTS
      tags:
        - WMS / WMTS
components:
  securitySchemes:
    api_key:
      in: query
      name: key
      type: apiKey