Join us online - 19th of November
Save your spot
For AI agents: a documentation index is available at /llms.txt. Markdown versions of all pages are available by appending .md to any URL.

Routing and directions API

The MapTiler Routing API calculates optimal routes and produces precise turn-by-turn navigation instructions between coordinates. Built on top of high-performance routing engines, it supports various modes of transport, advanced routing parameters, and localization.

Features

  • Costing Profiles: Highly tailored routing algorithms for different modes of travel:
    • 🚗 Car: Optimized for passenger vehicles with configurable costing modes (fastest, shortest, balanced) and top-speed limits.
    • 🚛 Truck: Enterprise routing supporting physical restrictions (weight, height, length, axle load) and hazardous materials (hazmat).
    • 🚲 Bicycle: Specialized cycling routes with selectable bicycle types (road, gravel, mountain, city) and custom average speeds.
    • 🚶 Pedestrian: Safe walking paths with configurable walking speeds.
  • Alternative Routes: Calculate up to 3 alternate routes (alternates) alongside the primary route for comparison.
  • Time-aware Routing: Specify planned departure (departureTime) or arrival (arrivalTime) times for time-dependent routing.
  • Dynamic Avoidances: Avoid specific road categories (like tolls, highways, or ferries) or define geographic avoidLocations using GeoJSON polygons to steer clear of custom areas.
  • Multi-point Routing: Add intermediate waypoints to define complex routes with precise heading preferences for starting or passing through coordinates.
  • Internationalization: Turn-by-turn maneuver instructions localized in over 25 languages (including English, Spanish, German, French, Czech, Polish, etc.).
  • Efficient Geometries: Retrieve the route path as clean coordinate arrays or highly compressed Encoded Polylines for fast network transmission.

Key

You need a MapTiler API key to use this service. Get it here and learn how to secure it.

Units of measurement

Important

The units request parameter (km by default, or mi) directly alters the numeric values returned for distances, while all other dimensions and speeds remain metric.

  • Route distances (totalLength, length): Expressed in the requested unit (km by default, or mi). Total distance is returned in totalLength for route and leg summaries, and in length for individual maneuver steps.
  • Vehicle dimensions & restrictions: Always metric, regardless of the units parameter:
    • Vehicle length and height: meters (m)
    • Weight and axle load: metric tonnes (t)
    • Speed limits and travel speeds (topSpeed, walkingSpeed, cyclingSpeed): km/h
  • Durations (totalTime, time): Always returned in seconds.

Routing API reference

The MapTiler Routing API supports both HTTP POST and GET methods:

  • POST (primary): The recommended method for invoking the API. It uses a JSON request body and supports the full range of advanced routing parameters, costing profiles, dynamic avoidances, and waypoints.
  • GET: A simpler alternative where parameters are passed as URL query parameters. It does not support some advanced options, such as starting headings or complex avoid zones.

Configure your environment settings below to update code samples and live API tests:

  • Server – select where your requests go. Keep the default api.maptiler.com or use the EU-based endpoint.
  • Authentication – enter your API key. It will automatically populate code snippets and test requests (otherwise, placeholders are shown).
  • Client Libraries – select your preferred programming language of the code examples.
Scalar API Reference
v1.0
OpenAPI 3.1.0

MapTiler API reference

MapTiler API

Client Libraries

Routing

​

Turn-by-turn directions API (POST)

​

Use POST API endpoint to be able to set all of the configuration options.

Body·Schema of the routing request
required
application/json

Only one of the times can be used, the routing engine treats them as alternative time types

  • Type: object · Schema of the routing request
    • locations
      Type: array object[] · location[] 2…
      required
    • profile
      enum
      required
      values
      • car
      • truck
      • bicycle
      • pedestrian
    • arrivalTime
      Type: string · time

      The time of the desired arrival. Cannot be combined with 'departureTime'

    • avoidLocations

      Locations to avoid, the value can be passed in the GeoJSON format, either as a MultiPoint or as a MultiPolygon. Note that the MultiPolygon cannot have holes.

      Locations to avoid, the value can be passed in the GeoJSON format, either as a MultiPoint or as a MultiPolygon. Note that the MultiPolygon cannot have holes.

      • Locations to avoid, the value can be passed in the GeoJSON format, either as a MultiPoint or as a MultiPolygon. Note that the MultiPolygon cannot have holes.

    • departureTime
      Type: string · time

      The time of the departure. Cannot be combined with 'arrivalTime'

    • id
      Type: string

      Pass through identifier

    • profileOptions
      • avoidances
        Type: object · avoidances

        Flags specifying various types of objects to avoid when routing

      • mode
        enum
        values
        • fastest
        • shortest
        • balanced
      • topSpeed
        Type: integer
        max:  
        252

        Maximal speed of the car, in km/h

    • response
      Type: object · responseOptions
Responses
  • application/json
  • application/json
  • 403

    Key is missing, invalid or restricted

  • application/json
Request Example for post/routing/v1/directions
curl 'https://api.maptiler.com/routing/v1/directions?key=YOUR_MAPTILER_API_KEY' \
  --request POST \
  --header 'Content-Type: application/json' \
  --data '{
  "profile": "pedestrian",
  "locations": [
    {
      "lon": 16.626597,
      "lat": 49.212572
    },
    {
      "lon": 16.613041,
      "lat": 49.191073
    }
  ],
  "response": {
    "language": "cs",
    "alternates": 1
  }
}'
{
  "route": {
    "summary": {
      "cost": 49.692,
      "bbox": [
        16.62652,
        49.211787,
        16.627168,
        49.212574
      ],
      "totalTime": 32.575,
      "totalLength": 0.122,
      "toll": false,
      "highway": false,
      "ferry": false
    },
    "legs": [
      {
        "summary": {
          "cost": 49.692,
          "bbox": [
            16.62652,
            49.211787,
            16.627168,
            49.212574
          ],
          "totalTime": 32.575,
          "totalLength": 0.122,
          "toll": false,
          "highway": false,
          "ferry": false
        },
        "geometry": [
          [
            16.626853,
            49.212574
          ],
          [
            16.626549,
            49.21203
          ],
          [
            16.62652,
            49.211977
          ],
          [
            16.627169,
            49.211787
          ]
        ],
        "steps": [
          {
            "time": 15.946,
            "length": 0.07,
            "streetName": "Tišnovská",
            "maneuver": {
              "instruction": "Drive south on Tišnovská.",
              "type": "start"
            },
            "beginIndex": 0,
            "endIndex": 2,
            "details": {}
          },
          {
            "time": 16.629,
            "length": 0.052,
            "streetName": "Venhudova",
            "maneuver": {
              "instruction": "Turn left onto Venhudova.",
              "turnAngle": -86,
              "type": "leftTurn"
            },
            "beginIndex": 2,
            "endIndex": 3,
            "details": {}
          },
          {
            "time": 0,
            "length": 0,
            "maneuver": {
              "instruction": "You have arrived at your destination.",
              "type": "destination"
            },
            "beginIndex": 3,
            "endIndex": 3,
            "details": {}
          }
        ]
      }
    ]
  },
  "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>"
}

Turn-by-turn directions API (GET)

​

Use GET API endpoint for simple cases. GET doesn't support some of the advanced options (e.g., avoidLocations, heading, waypoint).

Query Parameters
  • location
    Type: array string[] 2…
    required

    Route locations, each location is comma separated pair: longitude,latitude. NOTE: The heading parameter is not available in GET

  • profile
    enum
    required
    values
    • car
    • truck
    • bicycle
    • pedestrian
  • response.units
    enum
    values
    • km
    • mi
  • response.language
    enum

    Language of navigation instructions

    values
    • bg
    • ca
    • cs
    • da
    • de
  • response.additionalData.detailLevel
    enum

    Which additional information will be returned together with the routes

    How much routing detail should be returned. 'legs' returns only the summary of each leg. 'steps' additionally returns the steps of each leg, but without the human readable instructions. 'instructions' returns the full data, including the instructions.

    values
    • legs
    • steps
    • instructions
  • car.mode
    enum

    Available only for car profile

    values
    • fastest
    • shortest
    • balanced
  • avoidances.tolls
    Type: boolean

    Available only for car/truck profiles

  • avoidances.ferry
    Type: boolean

    Available only for car/truck profiles

  • avoidances.highway
    Type: boolean

    Available only for car/truck profiles

  • topSpeed
    Type: number

    Available only for car/truck profiles

  • truck.height
    Type: number

    Available only for truck profile

  • truck.weight
    Type: number

    Available only for truck profile

  • truck.axleLoad
    Type: number

    Available only for truck profile

  • truck.length
    Type: number

    Available only for truck profile

  • truck.hazmat
    Type: boolean

    Available only for truck profile

  • bicycle.type
    enum

    Available only for bicycle profile

    values
    • road
    • gravel
    • mountain
    • city
  • bicycle.cyclingSpeed
    Type: number

    Available only for bicycle profile

  • pedestrian.walkingSpeed
    Type: number

    Available only for pedestrian profile

  • id
    Type: string

    Request identifier, will be passed back in response

  • departureTime
    Type: string · time

    The time of the departure. Cannot be combined with arrivalTime

    Local date and time, with minute resolution

  • arrivalTime
    Type: string · time

    The time of the desired arrival. Cannot be combined with departureTime

    Local date and time, with minute resolution

  • alternates
    Type: integer · alternates
    min:  
    0
    max:  
    3

    The number of alternate routes to generate. Note that the alternates are not generated when the request contains more than two locations

Responses
  • application/json
  • application/json
  • 403

    Key is missing, invalid or restricted

  • application/json
Request Example for get/routing/v1/directions
curl 'https://api.maptiler.com/routing/v1/directions?location=12.414%2C51.131&location=3.867%2C48.224&profile=car&key=YOUR_MAPTILER_API_KEY'
{
  "id": "string",
  "route": {
    "summary": {
      "cost": 1,
      "bbox": [],
      "totalTime": 1,
      "totalLength": 1,
      "toll": true,
      "highway": true,
      "ferry": true
    },
    "legs": [
      {
        "summary": {
          "cost": 1,
          "bbox": [],
          "totalTime": 1,
          "totalLength": 1,
          "toll": true,
          "highway": true,
          "ferry": true
        },
        "geometry": [
          [
            1
          ]
        ],
        "steps": [
          {
            "time": 1,
            "length": 1,
            "streetName": "string",
            "maneuver": {
              "instruction": "string",
              "exitNumber": 1,
              "turnAngle": 1,
              "type": "none"
            },
            "beginIndex": 1,
            "endIndex": 1,
            "details": {
              "toll": true,
              "highway": true,
              "rough": true,
              "ferry": true
            }
          }
        ]
      }
    ]
  },
  "alternates": [
    {
      "summary": {
        "cost": 1,
        "bbox": [],
        "totalTime": 1,
        "totalLength": 1,
        "toll": true,
        "highway": true,
        "ferry": true
      },
      "legs": [
        {
          "summary": {
            "cost": 1,
            "bbox": [],
            "totalTime": 1,
            "totalLength": 1,
            "toll": true,
            "highway": true,
            "ferry": true
          },
          "geometry": [
            [
              1
            ]
          ],
          "steps": [
            {
              "time": 1,
              "length": 1,
              "streetName": "string",
              "maneuver": {
                "instruction": "string",
                "exitNumber": 1,
                "turnAngle": 1,
                "type": "none"
              },
              "beginIndex": 1,
              "endIndex": 1,
              "details": {
                "toll": true,
                "highway": true,
                "rough": true,
                "ferry": true
              }
            }
          ]
        }
      ]
    }
  ],
  "attribution": "© MapTiler © OpenStreetMap contributors",
  "units": "km",
  "language": "en"
}
Was this helpful?