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.
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 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.
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
maxspeedtag in OpenStreetMap.
- Traffic derived from real-time telemetry data (when the traffic profile is used).
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.
mapbox/driving-traffic profile is available globally, but the accuracy of traffic-dependent travel times vary by country.
Traffic data collected in these countries is comprehensive across geographies and times, resulting in highly accurate travel times.
- Czech Republic
- Korea, Republic of
- New Zealand
- Puerto Rico
- United Kingdom
- United States of America
Traffic data collected in these countries is less comprehensive. Travel times may be inaccurate, especially in heavy and unusual traffic conditions.
- Cayman Islands
- Dominican Republic
- Iran, Islamic Republic of
- United Arab Emirates
Traffic data collected in these countries is less comprehensive. Travel times are less reliable, with partial coverage of traffic conditions.
- Åland Islands
- American Samoa
- Bolivia, Plurinational State of
- Bosnia and Herzegovina
- Brunei Darussalam
- Cook Islands
- Costa Rica
- Côte d'Ivoire
- El Salvador
- Faroe Islands
- French Polynesia
- Holy See (Vatican City State)
- Hong Kong
- Macedonia, the Former Yugoslav Republic of
- Moldova, Republic of
- New Caledonia
- Russian Federation
- Saint Barthélemy
- Saint Kitts and Nevis
- Saint Lucia
- Saint Martin (French part)
- San Marino
- Saudi Arabia
- Sierra Leone
- Sint Maarten (Dutch part)
- South Africa
- Sri Lanka
- Tanzania, United Republic of
- Trinidad and Tobago
- Turks and Caicos Islands
- Venezuela, Bolivarian Republic of
- Viet Nam
- Virgin Islands, British
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.
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.
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.
Use of the Directions API is billed by API requests. For more details, see the Directions API pricing page.
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||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 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.
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.
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.
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.
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.
Use of the Optimization API is billed by API requests. For more details, see the Optimization API pricing page.
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.
Use of the Map Matching API is billed by API requests. For more details, see the Map Matching API pricing page.
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.
We have several tools across platforms that allow you to integrate the Mapbox Directions API into your existing applications seamlessly:
- Web: Mapbox GL Directions plugin for Mapbox GL JS and Mapbox-directions.js for Mapbox.js
- Android: Mapbox Java SDK
- iOS: MapboxDirections.swift
Here's an example of the Mapbox GL Directions plugin in action:
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.
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.