---
title: "Routing and directions API"
description: "Turn by turn directions routing service, calculates optimal routes and produces precise navigation instructions between coordinates"
---

> For AI agents: a documentation index is available at [/llms.txt](https://docs.maptiler.com/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](https://cloud.maptiler.com/account/keys/) and [learn how to secure it](https://docs.maptiler.com/guides/developer/credentials/api-key/#secure-key).

## 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](https://docs.maptiler.com/guides/api/eu-based-api-endpoint/).
-   **Authentication** – enter your [API key](https://docs.maptiler.com/guides/credentials/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

-   [
    
    Introduction
    
    ](#description/introduction)
-   [
    
    Routing
    
    ](#tag/routing)
    
    Close Group - Routing
    
    -   [
        
        Turn\-by\-turn directions API (POST)
        
        HTTP Method:  POST](#tag/routing/POST/routing/v1/directions)
    -   [
        
        Turn\-by\-turn directions API (GET)
        
        HTTP Method:  GET](#tag/routing/GET/routing/v1/directions)

[Powered by Scalar](https://www.scalar.com)

v1.0

OpenAPI 3.1.0

# MapTiler API reference

[Support](mailto:support@maptiler.com)

[](https://docs.maptiler.com/support/requests/)

[Terms of Service](https://www.maptiler.com/terms/)

Server

Server:https://api.maptiler.com

MapTiler API

## 

AuthenticationRequired

Selected Auth Type: key

<table class="mb-0 grid min-h-8 auto-rows-auto" role="presentation" style="grid-template-columns:1fr;"><tbody><tr class="group contents"><td class="box-content min-h-8 min-w-8 border-l-0 border-t border-b-0 border-r flex text-base/5 last:border-r-0 group-last:border-b-transparent p-0 m-0 relative max-h-[auto] group-[.alert]:bg-b-alert group-[.error]:bg-b-danger" style="" aria-label="Your own API key from https://cloud.maptiler.com/"><div class="group/summary flex gap-0.5 flex-row items-baseline auth-description bg-b-1 text-c-2 min-w-0 flex-1 px-3 py-1.25" style=""><div class="markdown line-clamp-(--markdown-clamp) markdown-summary truncate" style="--markdown-clamp:1;" controlled="false" modelvalue="false" truncated="false" id="scalar-refs-0-9"><p>Your own API key from <a href="https://cloud.maptiler.com/" rel="nofollow" target="_blank">https://cloud.maptiler.com/</a></p></div></div></td></tr><tr class="group contents"><td class="box-content max-h-8 min-h-8 min-w-8 border-l-0 border-b-0 border-r text-base/5 last:border-r-0 group-last:border-b-transparent p-0 m-0 relative flex border-t group-[.alert]:bg-b-alert group-[.error]:bg-b-danger" style="" data-v-a6f4752a=""><div class="text-c-1 flex items-center pr-0 pl-3" for="scalar-refs-0-10" data-v-a6f4752a=""><label for="scalar-refs-0-10">Name </label>:</div><div class="relative flex min-w-0 flex-1" data-v-a6f4752a=""><div id="scalar-refs-0-10" class="text-c-1 disabled:text-c-2 peer w-full min-w-0 border-none -outline-offset-1 code-input-lite group/code-input-lite peer relative w-full leading-[1.44] -outline-offset-1 has-[:focus-visible]:rounded-[4px] has-[:focus-visible]:outline code-input-lite--empty" data-v-4dfd05a3=""><div aria-autocomplete="list" class="code-input-lite__editor" contenteditable="true" data-placeholder="api-key" role="combobox" spellcheck="false" data-v-4dfd05a3=""></div></div></div><button aria-disabled="false" type="button" class="scalar-icon-button grid aspect-square cursor-pointer scalar-button-ghost bg-transparent text-c-2 active:text-c-1 hover:text-c-1 size-8 m-1 -outline-offset-2 rounded-lg -ml-.25 h-6 w-6 self-center p-1.25" style="" data-v-a6f4752a=""><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 256 256" fill="currentColor" width="1em" height="1em" aria-hidden="true" role="presentation" class="size-full" style=""><g><path d="M205.66,194.34a8,8,0,0,1-11.32,11.32L128,139.31,61.66,205.66a8,8,0,0,1-11.32-11.32L116.69,128,50.34,61.66A8,8,0,0,1,61.66,50.34L128,116.69l66.34-66.35a8,8,0,0,1,11.32,11.32L139.31,128Z"></path></g></svg><span class="sr-only">Clear Value</span></button></td></tr><tr class="group contents"><td class="box-content max-h-8 min-h-8 min-w-8 border-l-0 border-t border-b-0 border-r text-base/5 last:border-r-0 group-last:border-b-transparent p-0 m-0 relative flex group-[.alert]:bg-b-alert group-[.error]:bg-b-danger" style="" data-v-a6f4752a=""><div class="text-c-1 flex items-center pr-0 pl-3" for="scalar-refs-0-11" data-v-a6f4752a=""><label for="scalar-refs-0-11">Value </label>:</div><div class="relative flex min-w-0 flex-1" data-v-a6f4752a=""><input placeholder="QUxMIFlPVVIgQkFTRSBBUkUgQkVMT05HIFRPIFVT" id="scalar-refs-0-11" autocomplete="off" class="text-c-1 disabled:text-c-2 peer w-full min-w-0 border-none px-2 py-1.25 -outline-offset-1 scalar-password-input" data-1p-ignore="" spellcheck="false" type="text" value="YOUR_MAPTILER_API_KEY" data-v-a6f4752a=""></div><button aria-disabled="false" type="button" class="scalar-icon-button grid aspect-square cursor-pointer scalar-button-ghost bg-transparent text-c-2 active:text-c-1 hover:text-c-1 size-8 m-1 -outline-offset-2 rounded-lg -ml-.25 h-6 w-6 self-center p-1.25" style="" data-v-a6f4752a=""><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 256 256" fill="currentColor" width="1em" height="1em" aria-hidden="true" role="presentation" class="size-full" style=""><g><path d="M205.66,194.34a8,8,0,0,1-11.32,11.32L128,139.31,61.66,205.66a8,8,0,0,1-11.32-11.32L116.69,128,50.34,61.66A8,8,0,0,1,61.66,50.34L128,116.69l66.34-66.35a8,8,0,0,1,11.32,11.32L139.31,128Z"></path></g></svg><span class="sr-only">Clear Value</span></button><button aria-disabled="false" type="button" class="scalar-icon-button grid aspect-square cursor-pointer scalar-button-ghost bg-transparent text-c-2 active:text-c-1 hover:text-c-1 size-8 m-1 -outline-offset-2 rounded-lg -ml-.5 mr-1.25 h-6 w-6 self-center p-1.25" style="" data-testid="data-table-password-toggle" data-v-a6f4752a=""><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 256 256" fill="currentColor" width="1em" height="1em" aria-hidden="true" role="presentation" class="size-full" style=""><g><path d="M247.31,124.76c-.35-.79-8.82-19.58-27.65-38.41C194.57,61.26,162.88,48,128,48S61.43,61.26,36.34,86.35C17.51,105.18,9,124,8.69,124.76a8,8,0,0,0,0,6.5c.35.79,8.82,19.57,27.65,38.4C61.43,194.74,93.12,208,128,208s66.57-13.26,91.66-38.34c18.83-18.83,27.3-37.61,27.65-38.4A8,8,0,0,0,247.31,124.76ZM128,192c-30.78,0-57.67-11.19-79.93-33.25A133.47,133.47,0,0,1,25,128,133.33,133.33,0,0,1,48.07,97.25C70.33,75.19,97.22,64,128,64s57.67,11.19,79.93,33.25A133.46,133.46,0,0,1,231.05,128C223.84,141.46,192.43,192,128,192Zm0-112a48,48,0,1,0,48,48A48.05,48.05,0,0,0,128,80Zm0,80a32,32,0,1,1,32-32A32,32,0,0,1,128,160Z"></path></g></svg><span class="sr-only">Show Password</span></button></td></tr></tbody></table>

Client Libraries

Shell

Ruby

Node.js

PHP

Python

MoreSelect from all clients

Shell Curl

## Routing

​Copy link

Routing Operations

-   post/routing/v1/directions
-   get/routing/v1/directions

### Turn-by-turn directions API (POST)

​Copy link

Auth Required

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
    
    -   locationsCopy link to locations
        
        Type: array object\[\] · location\[\] 2…
        
        required
        
        Show Child Attributesfor locations
        
    -   profileCopy link to profile
        
        enum
        
        required
        
        values
        
        -   car
            
        -   truck
            
        -   bicycle
            
        -   pedestrian
            
        
    -   arrivalTimeCopy link to arrivalTime
        
        Type: string · time
        
        Pattern
        
        `^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}$`
        
        Example
        
        2026-02-03T10:20
        
        The time of the desired arrival. Cannot be combined with 'departureTime'
        
    -   avoidLocationsCopy link to 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.
        
        One ofAvoidLocations
        
        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.
            
            One ofAvoidLocations
            
            Show Schema Details
            
        
    -   departureTimeCopy link to departureTime
        
        Type: string · time
        
        Pattern
        
        `^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}$`
        
        Example
        
        2026-02-03T10:20
        
        The time of the departure. Cannot be combined with 'arrivalTime'
        
    -   idCopy link to id
        
        Type: string
        
        Pass through identifier
        
    -   profileOptionsCopy link to profileOptions
        
        Any ofcarOptions
        
        -   avoidances
            
            Type: object · avoidances
            
            Flags specifying various types of objects to avoid when routing
            
            Show Child Attributesfor avoidances
            
        -   mode
            
            enum
            
            values
            
            -   fastest
                
            -   shortest
                
            -   balanced
                
            
        -   topSpeed
            
            Type: integer
            
            max:  
            
            252
            
            Default
            
            140
            
            Maximal speed of the car, in km/h
            
        
    -   responseCopy link to response
        
        Type: object · responseOptions
        
        Show Child Attributesfor response
        
    

Responses

-   200
    
    Successful response
    
    application/json
    
-   400
    
    This error code means that the request was not correct
    
    application/json
    
-   403
    
    Key is missing, invalid or restricted
    
-   500
    
    Internal server error
    
    application/json
    

Request Example for post/routing/v1/directions

Shell Curl

```curl
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
  }
}'
```

cURLCopy

cURLCopy

Select an example

Test Request(post /routing/v1/directions)

Status: 200Status: 400Status: 403Status: 500

Show Schema 

```json
{
  "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>"
}
```

JSONCopy

JSONCopy

Response containing all the details (for simplicity, a fake, simplified geometry is returned).

Successful response

### Turn-by-turn directions API (GET)

​Copy link

Auth Required

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

Query Parameters

-   locationCopy link to location
    
    Type: array string\[\] 2…
    
    required
    
    Example
    
    \["12.414,51.131", "3.867,48.224"\]
    
    Route locations, each location is comma separated pair: `longitude,latitude`. NOTE: The heading parameter is not available in GET
    
-   profileCopy link to profile
    
    enum
    
    required
    
    values
    
    -   car
        
    -   truck
        
    -   bicycle
        
    -   pedestrian
        
    
-   response.unitsCopy link to response.units
    
    enum
    
    Default
    
    km
    
    values
    
    -   km
        
    -   mi
        
    
-   response.languageCopy link to response.language
    
    enum
    
    Default
    
    en
    
    Language of navigation instructions
    
    values
    
    -   bg
        
    -   ca
        
    -   cs
        
    -   da
        
    -   de
        
    -   Show all values
    
-   response.additionalData.detailLevelCopy link to response.additionalData.detailLevel
    
    enum
    
    Default
    
    instructions
    
    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.modeCopy link to car.mode
    
    enum
    
    Available only for car profile
    
    values
    
    -   fastest
        
    -   shortest
        
    -   balanced
        
    
-   avoidances.tollsCopy link to avoidances.tolls
    
    Type: boolean
    
    Available only for car/truck profiles
    
-   avoidances.ferryCopy link to avoidances.ferry
    
    Type: boolean
    
    Available only for car/truck profiles
    
-   avoidances.highwayCopy link to avoidances.highway
    
    Type: boolean
    
    Available only for car/truck profiles
    
-   topSpeedCopy link to topSpeed
    
    Type: number
    
    Available only for car/truck profiles
    
-   truck.heightCopy link to truck.height
    
    Type: number
    
    Available only for truck profile
    
-   truck.weightCopy link to truck.weight
    
    Type: number
    
    Available only for truck profile
    
-   truck.axleLoadCopy link to truck.axleLoad
    
    Type: number
    
    Available only for truck profile
    
-   truck.lengthCopy link to truck.length
    
    Type: number
    
    Available only for truck profile
    
-   truck.hazmatCopy link to truck.hazmat
    
    Type: boolean
    
    Available only for truck profile
    
-   bicycle.typeCopy link to bicycle.type
    
    enum
    
    Available only for bicycle profile
    
    values
    
    -   road
        
    -   gravel
        
    -   mountain
        
    -   city
        
    
-   bicycle.cyclingSpeedCopy link to bicycle.cyclingSpeed
    
    Type: number
    
    Available only for bicycle profile
    
-   pedestrian.walkingSpeedCopy link to pedestrian.walkingSpeed
    
    Type: number
    
    Available only for pedestrian profile
    
-   idCopy link to id
    
    Type: string
    
    Request identifier, will be passed back in response
    
-   departureTimeCopy link to departureTime
    
    Type: string · time
    
    Pattern
    
    `^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}$`
    
    Example
    
    2026-02-03T10:20
    
    The time of the departure. Cannot be combined with `arrivalTime`
    
    Local date and time, with minute resolution
    
-   arrivalTimeCopy link to arrivalTime
    
    Type: string · time
    
    Pattern
    
    `^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}$`
    
    Example
    
    2026-02-03T10:20
    
    The time of the desired arrival. Cannot be combined with `departureTime`
    
    Local date and time, with minute resolution
    
-   alternatesCopy link to alternates
    
    Type: integer · alternates
    
    min:  
    
    0
    
    max:  
    
    3
    
    Default
    
    0
    
    The number of alternate routes to generate. Note that the alternates are not generated when the request contains more than two locations
    

Responses

-   200
    
    Successful response
    
    application/json
    
-   400
    
    This error code means that the request was not correct
    
    application/json
    
-   403
    
    Key is missing, invalid or restricted
    
-   500
    
    Internal server error
    
    application/json
    

Request Example for get/routing/v1/directions

Shell Curl

```curl
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'
```

Copy

Copy

Test Request(get /routing/v1/directions)

Status: 200Status: 400Status: 403Status: 500

Show Schema 

```json
{
  "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"
}
```

JSONCopy

JSONCopy

Successful response
