Integration guide

Set up Mapbox in RouteIQ

Create a dedicated Mapbox access token and choose whether Mapbox should handle address search, geocoding, routing, or matrix calculations.

Updated September 3, 2026
Mapbox bills you separately. Review Mapbox pricing, account limits, and geocoding terms before production use.

Before you start

You will need a Mapbox account with permission to manage access tokens, appropriate billing for production use, and administrator access to your RouteIQ site.

Use a dedicated token

Create a RouteIQ-specific public token with no write or administrative scopes. Use a separate token for each environment so usage and rotation remain isolated.

1. Create a Mapbox access token

  1. Sign in to the Mapbox account dashboard.
  2. Open Access Tokens and select Create a token.
  3. Name it clearly, such as RouteIQ production.
  4. Keep only the public permissions required to call Mapbox APIs. Secret write and account-management permissions are not needed.
  5. Leave URL restrictions empty, create the token, and copy its pk... value.
Do not add a browser URL restriction

RouteIQ calls Mapbox from its servers. A restriction for your website or the RouteIQ dashboard can cause 403 Forbidden. Keep this dedicated token narrowly scoped, monitor it, and rotate it if exposed.

See Mapbox's access-token guide.

2. Understand the Mapbox services used

You do not need to turn on Mapbox services separately. The access token allows requests to these services:

RouteIQ operationMapbox APISupport
autocompleteGeocoding API v6Supported
geocodeGeocoding API v6Supported
reverse_geocodeGeocoding API v6Supported
routingDirections API v5Supported
matrixMatrix API v1Supported
sequenceNot applicableNot supported by the Mapbox integration

Review the official Geocoding, Directions, and Matrix API references.

Check Mapbox's rules for saving address results

Mapbox's default terms do not allow temporary address-search results to be stored permanently. Contact us before using Mapbox address features in a workflow that needs to save those results.

3. Connect Mapbox to RouteIQ

  1. Sign in to RouteIQ and open Settings > Integrations.
  2. Find Mapbox and turn it on.
  3. After it shows Connected, select Configure.
  4. Paste the token into Mapbox Access Token.
  5. Select one or more supported operations.
  6. Leave Is Active selected and save.

4. Choose the right operations

Mapbox supports routing, matrix, autocomplete, geocode, and reverse_geocode. It does not support sequence in RouteIQ.

You can mix Mapbox with Google, HERE, or an included provider to get the best price, address coverage, and route quality for each feature. Each feature can use only one active provider.

Truck, bus, taxi, and scooter requests currently use Mapbox's standard driving profile. Vehicle height, weight, axle, and commercial-road limits are not applied.

5. Verify the setup

  1. Confirm the card displays the operations you selected.
  2. Enter and select a new address to test address operations.
  3. Create a route with at least two locations to test routing.
  4. Confirm RouteIQ calculates travel time and distance when using matrix.
  5. Check Mapbox account statistics for requests from the new token.

Troubleshooting

Mapbox returns 401

The token is invalid, deleted, or copied incorrectly.

Mapbox returns 403

Check account standing, token scopes, and incompatible URL restrictions. See Mapbox's token error guide.

RouteIQ rejects an operation

Do not select sequence, and confirm another active mapping provider does not already own the selected operation.

A matrix request fails

Reduce the number of locations. Mapbox imposes coordinate limits on each Matrix API request.

Rotate or remove the token

  1. Create a replacement token with the same minimal permissions.
  2. Update the token in RouteIQ and save.
  3. Test every assigned operation.
  4. Delete the old token only after the replacement works.

Disconnecting Mapbox in RouteIQ does not revoke the token at Mapbox.