openapi: 3.0.0
info:
  contact:
    x-twitter: TomTom
  description: "The Maps API web services suite offers the following APIs:\n  - Raster\n  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.\n  - Vector\n  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.\n  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 Additional Data Routing API
  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
servers:
- url: https://api.tomtom.com
security:
- api_key: []
tags:
- name: Routing
  description: Route calculation between locations
paths:
  /routing/{versionNumber}/calculateRoute/{locations}/{contentType}:
    get:
      operationId: calculateRoute
      summary: Calculate Route
      description: Calculates a route between two or more locations. Supports optimization for fastest, shortest, or eco routes with traffic consideration.
      tags:
      - Routing
      parameters:
      - name: versionNumber
        in: path
        required: true
        schema:
          type: integer
          enum:
          - 1
        description: Service version number
      - name: locations
        in: path
        required: true
        schema:
          type: string
        description: Colon-separated list of coordinates (lat,lon:lat,lon)
        example: 52.50931,13.42936:52.50274,13.43872
      - name: contentType
        in: path
        required: true
        schema:
          type: string
          enum:
          - json
          - jsonp
          - xml
      - name: routeType
        in: query
        schema:
          type: string
          enum:
          - fastest
          - shortest
          - eco
          - thrilling
        description: Optimization type for route calculation
      - name: traffic
        in: query
        schema:
          type: boolean
        description: Use real-time traffic data
      - name: avoid
        in: query
        schema:
          type: string
        description: Comma-separated list of things to avoid (tollRoads, motorways, ferries, etc.)
      - name: travelMode
        in: query
        schema:
          type: string
          enum:
          - car
          - truck
          - taxi
          - bus
          - van
          - motorcycle
          - bicycle
          - pedestrian
      - name: departAt
        in: query
        schema:
          type: string
          format: date-time
        description: Departure time for historical traffic
      - name: arriveAt
        in: query
        schema:
          type: string
          format: date-time
        description: Desired arrival time
      - name: maxAlternatives
        in: query
        schema:
          type: integer
          minimum: 0
          maximum: 5
        description: Number of alternative routes to return
      - name: instructionsType
        in: query
        schema:
          type: string
          enum:
          - coded
          - text
          - tagged
      - name: language
        in: query
        schema:
          type: string
        description: Language tag for instructions (e.g., en-US)
      - name: vehicleMaxSpeed
        in: query
        schema:
          type: integer
        description: Maximum speed of the vehicle (km/h)
      - name: vehicleWeight
        in: query
        schema:
          type: integer
        description: Vehicle weight (kg)
      - name: vehicleAxleWeight
        in: query
        schema:
          type: integer
        description: Weight per axle (kg)
      - name: vehicleLength
        in: query
        schema:
          type: number
        description: Vehicle length (meters)
      - name: vehicleWidth
        in: query
        schema:
          type: number
        description: Vehicle width (meters)
      - name: vehicleHeight
        in: query
        schema:
          type: number
        description: Vehicle height (meters)
      - name: vehicleCommercial
        in: query
        schema:
          type: boolean
        description: Whether vehicle is used for commercial purposes
      - name: vehicleLoadType
        in: query
        schema:
          type: string
        description: Types of cargo carried
      - name: computeTravelTimeFor
        in: query
        schema:
          type: string
          enum:
          - none
          - all
      - name: sectionType
        in: query
        schema:
          type: string
      - name: report
        in: query
        schema:
          type: string
          enum:
          - effectiveSettings
      - name: callback
        in: query
        schema:
          type: string
        description: Callback function name for JSONP
      responses:
        '200':
          description: Route calculation result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RouteResponse'
    post:
      operationId: calculateRoutePost
      summary: Calculate Route (POST)
      description: Calculates a route using POST for complex requests with additional body parameters.
      tags:
      - Routing
      parameters:
      - name: versionNumber
        in: path
        required: true
        schema:
          type: integer
          enum:
          - 1
      - name: locations
        in: path
        required: true
        schema:
          type: string
      - name: contentType
        in: path
        required: true
        schema:
          type: string
          enum:
          - json
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                supportingPoints:
                  type: array
                  items:
                    $ref: '#/components/schemas/LatLon'
                avoidVignette:
                  type: array
                  items:
                    type: string
                allowVignette:
                  type: array
                  items:
                    type: string
                avoidAreas:
                  type: object
      responses:
        '200':
          description: Route calculation result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RouteResponse'
components:
  schemas:
    LatLon:
      type: object
      properties:
        latitude:
          type: number
          format: double
        longitude:
          type: number
          format: double
    RouteSummary:
      type: object
      properties:
        lengthInMeters:
          type: integer
        travelTimeInSeconds:
          type: integer
        trafficDelayInSeconds:
          type: integer
        trafficLengthInMeters:
          type: integer
        departureTime:
          type: string
          format: date-time
        arrivalTime:
          type: string
          format: date-time
        noTrafficTravelTimeInSeconds:
          type: integer
        historicTrafficTravelTimeInSeconds:
          type: integer
        liveTrafficIncidentsTravelTimeInSeconds:
          type: integer
    Route:
      type: object
      properties:
        summary:
          $ref: '#/components/schemas/RouteSummary'
        legs:
          type: array
          items:
            $ref: '#/components/schemas/RouteLeg'
        sections:
          type: array
          items:
            type: object
        guidance:
          type: object
    RouteResponse:
      type: object
      properties:
        formatVersion:
          type: string
        routes:
          type: array
          items:
            $ref: '#/components/schemas/Route'
    RouteLeg:
      type: object
      properties:
        summary:
          $ref: '#/components/schemas/RouteSummary'
        points:
          type: array
          items:
            $ref: '#/components/schemas/LatLon'
  securitySchemes:
    api_key:
      in: query
      name: key
      type: apiKey