Directions

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 of 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 a number of 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

A directions service that can create routes and optimized trips requires a robust network of paths with distinct attributes like speed, turn restrictions, and travel mode (for example, motorway, foot path, bike lane). Mapbox’s directions services use a network of roads and paths, or ways, derived from OpenStreetMap, a collaborative project to create a free and editable map of the world.

Contributors to OpenStreetMap have built a vast, routeable network that includes properties like speed limits, turn lane restrictions, and accessibility for bikes and pedestrians. These details provide the framework that the Open Source Routing Machine (OSRM) needs to calculate the fastest path for your mode of transportation (driving, cycling, walking).

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 a number of 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

In addition to the contributions of OpenStreetMap, Mapbox SDKs collect anonymous data, or telemetry, about the device location to continuously update and the routing network. Attributes such as speed, turn restrictions, and travel mode can be collected to improve OpenStreetMap. With the added telemetry, your customers can also route over the same networks factoring in real-time traffic. Read more about our traffic tileset in Our map data.

Using directions services

There are a number of 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 in 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:

  A B C
A A → A A → B A → C
B B → A B → B B → C
C C → A C → B C → C

The Matrix API will always return the duration on the fastest 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. Similar to 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.

https://api.mapbox.com/directions-matrix/v1/mapbox/driving/A;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.

https://api.mapbox.com/directions-matrix/v1/mapbox/driving/A;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.

https://api.mapbox.com/directions-matrix/v1/mapbox/driving/A;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.

https://api.mapbox.com/directions-matrix/v1/mapbox/driving/A;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:

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 an API Playground. In addition to 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 on our Directions Feedback page. If you are using the API directly, you can use the API Playground to test your request, response, and any parameters you would like to include in your request.