Mapbox provides a collection of APIs to add directions-related services to your application. Generate a route with trip durations, estimated distances, and turn-by-turn directions with the Mapbox Directions API, retrieve travel times between many points with the Mapbox Matrix API, retrieve duration-optimized trips between points with the Mapbox Optimization API, or align existing fuzzy routes to the routeable network with the Mapbox Map Matching API. From routing deliveries efficiently to providing navigation steps for wayfinding, Mapbox provides the tools necessary to integrate directions into your application.

This guide provides an overview of how the routing network is created, how to add directions services to applications across platforms, how to provide feedback, and relevant documentation to help you get started.

This example uses the Mapbox GL Directions plugin to add driving, cycling, or walking directions to a web application built with Mapbox GL JS. Type in two locations to view the raw JSON response for that query.

The Mapbox Directions API returns a JSON object containing a route with trip durations, estimated distances, and turn-by-turn instructions. When using the Mapbox GL Directions plugin, all this information will be automatically added to the map when a request is complete. By default, the plugin will also display turn-by-turn instructions. This example hides the turn-by-turn instructions and displays the raw JSON response to illustrate what information is included in the directions response object.

How directions work

When you provide two or more points to the Mapbox Directions API, it returns a route as a GeoJSON line that you can add to your map, text for turn-by-turn instructions that you can choose to display in your application, and the distance and estimated travel times for the mode of transportation you selected. There are many other services that extend Mapbox directions that allow you to fix messy GPS traces to the network or optimize trips to multiple stops on a single journey.

The routing network

The Mapbox routing network can create routes and optimized trips, and is used to calculate the most efficient path for a given mode of transportation (driving, cycling, and walking). The routing network includes a robust network of roads and paths (also known as ways) with distinct attributes like speed limits, turn lane restrictions, mode of travel, and accessibility for bikes and pedestrians.


A way is an OpenStreetMap term used to describe an ordered list of nodes (points) which normally also has at least one tag, or description. For the purposes of the Mapbox Navigation service APIs, ways can be roads, foot paths, or bicycle lanes.

Travel times

The Mapbox Directions API, Matrix API, and Optimization API all provide estimated trip durations. The time it takes to travel from one point to another is determined by many factors, including:

  • The profile used (walking, cycling, or driving).
  • The speed stored in the maxspeed tag in OpenStreetMap.
  • Traffic derived from real-time telemetry data (when the traffic profile is used).

Traffic data

Incorporate real-time traffic into route selection and ETA generation using the mapbox/driving-traffic profile with the Mapbox Directions API, Map Matching API, or Matrix API, or add a traffic layer to road geometries on a visual map. Read more about our traffic tileset in Our map data.

The mapbox/driving-traffic profile is available globally, but the accuracy of traffic-dependent travel times vary by country.

Highly accurate travel times

Traffic data collected in these countries is comprehensive across geographies and times, resulting in highly accurate travel times.

  • Australia
  • Canada
  • Czech Republic
  • Estonia
  • Gibraltar
  • Iceland
  • Ireland
  • Korea, Republic of
  • Latvia
  • Liechtenstein
  • Netherlands
  • New Zealand
  • Puerto Rico
  • Slovakia
  • United Kingdom
  • United States of America

Moderately accurate travel times

Traffic data collected in these countries is less comprehensive. Travel times may be inaccurate, especially in heavy and unusual traffic conditions.

  • Andorra
  • Argentina
  • Armenia
  • Austria
  • Barbados
  • Belarus
  • Belgium
  • Belize
  • Cayman Islands
  • Chile
  • Cyprus
  • Denmark
  • Dominican Republic
  • Finland
  • France
  • Germany
  • Guam
  • Hungary
  • Iran, Islamic Republic of
  • Israel
  • Italy
  • Japan
  • Jordan
  • Lithuania
  • Luxembourg
  • Mexico
  • Montenegro
  • Norway
  • Panama
  • Paraguay
  • Poland
  • Portugal
  • Romania
  • Slovenia
  • Spain
  • Sweden
  • Switzerland
  • United Arab Emirates
  • Uruguay

Limited predictability of travel times

Traffic data collected in these countries is less comprehensive. Travel times are less reliable, with partial coverage of traffic conditions.

  • Åland Islands
  • Albania
  • Algeria
  • American Samoa
  • Anguilla
  • Aruba
  • Azerbaijan
  • Bahamas
  • Bahrain
  • Bangladesh
  • Bermuda
  • Bolivia, Plurinational State of
  • Bosnia and Herzegovina
  • Botswana
  • Brazil
  • Brunei Darussalam
  • Bulgaria
  • Cambodia
  • Cameroon
  • Colombia
  • Cook Islands
  • Costa Rica
  • Côte d'Ivoire
  • Croatia
  • Dominica
  • Ecuador
  • Egypt
  • El Salvador
  • Faroe Islands
  • Fiji
  • French Polynesia
  • Georgia
  • Ghana
  • Greece
  • Grenada
  • Guatemala
  • Haiti
  • Holy See (Vatican City State)
  • Honduras
  • Hong Kong
  • India
  • Indonesia
  • Iraq
  • Jamaica
  • Kazakhstan
  • Kenya
  • Kuwait
  • Kyrgyzstan
  • Laos
  • Lebanon
  • Macedonia, the Former Yugoslav Republic of
  • Malawi
  • Malaysia
  • Malta
  • Mauritius
  • Moldova, Republic of
  • Monaco
  • Mongolia
  • Morocco
  • Myanmar
  • Namibia
  • Nepal
  • New Caledonia
  • Nicaragua
  • Nigeria
  • Oman
  • Pakistan
  • Philippines
  • Qatar
  • Russian Federation
  • Saint Barthélemy
  • Saint Kitts and Nevis
  • Saint Lucia
  • Saint Martin (French part)
  • San Marino
  • Saudi Arabia
  • Senegal
  • Serbia
  • Sierra Leone
  • Singapore
  • Sint Maarten (Dutch part)
  • South Africa
  • Sri Lanka
  • Swaziland
  • Tajikistan
  • Tanzania, United Republic of
  • Thailand
  • Trinidad and Tobago
  • Tunisia
  • Turkey
  • Turks and Caicos Islands
  • Ukraine
  • Uzbekistan
  • Venezuela, Bolivarian Republic of
  • Viet Nam
  • Virgin Islands, British
  • Zambia

Using directions services

There are many tools you can use to enable directions-related services for your Mapbox web or mobile application. You can access these services directly using the web services APIs, through our Navigation SDK, or using one of several plugins and libraries to integrate these services into applications across platforms.

Web services APIs

There are four directions-related services that Mapbox offers:

  • Mapbox Directions API: retrieve point to point directions including a route with durations, estimated distances, and turn-by-turn instructions.
  • Mapbox Matrix API: retrieve all travel times between many points.
  • Mapbox Optimization API: retrieve duration-optimized trips between input coordinates.
  • Mapbox Map Matching API: align existing fuzzy routes to the routeable network.

Read more about the required inputs for each API below.

Mapbox Directions API

Requesting directions from the Mapbox Directions API requires at least two waypoints — an origin and a destination — but can also include up to 23 additional waypoints between (or a total of 25 waypoints). When making a request, you can specify additional parameters such as which profile to use (walking, cycling, driving, or driving with traffic) and whether alternate routes should be included in the response. You can also add optional annotations to your request, including duration, distance, speed, and congestion. We calculate congestion by comparing night-time traffic speeds with real-time traffic speeds and assign a level of congestion given the percentage difference.

You can read more about the directions response object in our API documentation.

Mapbox Matrix API

The Mapbox Matrix API returns travel times between many locations. Each location is either a source or destination. The number of sources and destinations are multiplied to create the matrix, or timetable, and calculate the number of elements needed to make the request. For example, given three locations A, B, C, the Matrix API will return a matrix of all travel times in seconds between all locations:

AA → AA → BA → C
BB → AB → BB → C
CC → AC → BC → C

The Matrix API will always return the duration on the most efficient route for each location in the matrix, where an element is an origin-destination pair in the matrix.

Durations between locations may not be symmetric (for example A to B may have a different duration than B to A), as the routes may differ by direction due to one-way streets or turn restrictions. The Matrix API returns durations in seconds. It does not return route geometries or distances. Like the Directions API, the Matrix API must be used on the same continent (does not cross over water bodies).

This API allows you to build tools that efficiently check the reachability of coordinates from each other, filter locations by travel time, or run your own algorithms for solving optimization problems.

Each request requires that you specify which locations are the sources and which are the destinations. There are four types of requests you can use with the Matrix API:

Many to many (NxN)

A many to many request is the default and generates the most results per-number-of-coordinates. This assumes all locations are sources and destinations. Without passing the source and destinations in the request, the response will still output an array of travel times between all locations.;B;C;D;E?access_token=....
Many to Many (NxN)

One to many (1xN)

In some cases, you may have a single source (for example, one driver) and four potential destinations (four gas stations). To calculate which destination has the shortest drive time, you need to specify the source and destination coordinates.;B;C;D;E?sources=0&destinations=1;2;3;4&access_token=...
One to many (1xN)

Many to one (Nx1)

An opposite request may be necessary where you may want to find travel times of many taxis to one rider, for example. In this case, a many to one (Nx1) request can be made by listing all your sources and your one destination.;B;C;D;E?sources=1;2;3;4&destinations=0&access_token=....
Many to one (Nx1)

Several to several (MxN)

An uncommon but useful case is a several to several (NxM) request where you may want to be selective about how many sources and destinations you wish to find travel times to and from.;B;C;D;E?sources=0;1&destinations=2;3;4&access_token=....
Several to several NxM

Mapbox Optimization API

The Mapbox Optimization API returns a duration-optimized trip between the input coordinates. This is also known as solving the Traveling Salesperson Problem. This API could be used to plan a route for deliveries in a city. Optimized trips can be retrieved for driving, bicycling, and walking or hiking.

optimized trips

Mapbox Map Matching API

The Mapbox Map Matching API snaps fuzzy, inaccurate traces from a GPS unit or a phone to the OpenStreetMap road and path network using the Directions API. This produces clean paths that can be displayed on a map or used for other analysis.

map matching

Mapbox Navigation SDK

You can add directions to a mobile application using the Mapbox Navigation SDK for iOS and Android. With the Navigation SDK, it takes only a few lines of code to display a complete navigation experience inside your app. With the Navigation SDK, you can:

  • Generate turn-by-turn instructions.
  • Use automatic rerouting when a user deviates from the route.
  • Provide walking, biking, and driving directions.
  • Provide real-time traffic.

navigation SDK

Read more about the Navigation SDK for iOS and Android.

Libraries and plugins

We have several tools across platforms that allow you to integrate the Mapbox Directions API into your existing applications seamlessly:

These tools allow you to add routing capabilities to your application, but have limitations when it comes to customization. These tools do not provide access to the Mapbox Matrix API, Optimization API, or Map Matching API. For more flexibility, you can use our APIs directly.

In addition, we offer libraries for:

Here's an example of the Mapbox GL Directions plugin in action:

Mapbox GL JS plugin

Testing the API

If you would like to get a feel for how the Mapbox Directions API works without building a whole application, we also provide a Directions API Playground. Besides providing a convenient user interface to test queries, the API playground allows you to test the API's URL and query parameters, such as mode of transportation, steps, and alternative routes.

Visit the API Playground

Providing directions feedback

If you find issues with routing or any of the related services, you can provide feedback from our Directions API Playground where you can also test your request, response, and any parameters you would like to include in your request.

Was this page helpful?