Connect Mapbox: route distance, duration and ETA for TMS lanes
Copy an Access Token from account.mapbox.com → Access Tokens, fill that single access_token into Integration, test it with one real Directions call, pick the route planning template and activate — TMS then gets distance, duration and route for lane cost and ETA.
The Mapbox connector is a route data source for TMS. It uses the Mapbox Directions API to calculate one route at a time — distance, duration and the route itself — so shipments and tenders in TMS can use that result as the basis for lane cost and ETA. That is its only job: it does not pull or push orders, it does not sync customers or inventory, it does not track vehicles, and it does not work out the best visiting order for many stops. One connection holds one Mapbox Access Token.
Prerequisites#
- A Mapbox account you can sign in to at account.mapbox.com, with access to the Access Tokens page.
- You understand that testing this connection is not free of usage: there is no free probe endpoint for the Directions API, so each test is one real route call and uses one quota. Do not click test repeatedly without a reason.
- Your lanes fit what the Directions API accepts through this connector: coordinates are sent in longitude,latitude order, and one route request carries at most 25 coordinates.
- Permission in this system to open Integration and create a new connection.
Get your credentials#
- Sign in at account.mapbox.com and open Access Tokens.
- Copy a token from that page in full. Tokens shown for this connector start with pk.… or sk.… — copy the whole value exactly as shown, with nothing cut off at either end and no extra space added.
- Keep that token as the only value you need to bring back. This connection sends the token to Mapbox as the access_token query parameter on each Directions request, so there is no separate key, username or password to collect on that page.
Fill it into Integration#
- Open Integration → Connector Marketplace → Mapbox → New connection.
- access_token — required, Mapbox Access Token: paste the full token you copied from account.mapbox.com → Access Tokens. It is a password-type field and is stored as a secret. There is no second field for this connector: no username, no password and no account field to fill in here.
- Save the connection before you test it, so the test uses exactly the token you just entered. The token will be sent as the access_token query parameter on the test request.
Test the connection#
Click Test connection. With a token filled in, the test makes one real, minimal Directions call: it sends a GET request to https://api.mapbox.com/directions/v5/mapbox/{profile}/{coordinates} with your token as the access_token query parameter. A pass means the access token is valid and the Directions API is reachable, and the success message says so in words: access token valid, Directions API reachable (probe consumes one quota). Read that last part literally — this probe is a real call and it uses one quota every time you run it, so test once, fix the cause if it fails, and only then test again.
Mapping / pick a template#
Pick the route planning template — the only template this connector uses. There are no order or customer fields to map. What the template sets is the Directions profile for each travel mode asked for in TMS — driving, driving-traffic, walking and cycling each go to Mapbox as the profile of the same name — and the shape of the request itself: coordinates in longitude,latitude order, at most 25 coordinates in one route. After the test passes, ask for one route you already know in TMS and check the returned distance and duration against your own expectation for that lane before you activate.
Activate#
After activation, TMS can ask this connection for a route whenever a shipment or tender needs a lane estimate: the connection returns distance, duration and the route, and TMS uses them as the basis for lane cost and ETA. Watch the first real requests in Runs / Logs and compare a few returned distances and durations with lanes you know, before leaving the connection unattended.
What this connection does not do: it only provides route planning through the Directions API. It does not work out the best order for visiting many stops, it does not pull orders in, it does not sync customers or inventory, and it does not follow a vehicle while it moves. If a TMS screen shows no new orders after activation, that is expected — orders come from your order channels, and this connection only answers when TMS asks: how far, how long, which route.
FAQ#
Test fails and says the access token is not valid
The value in access_token is not a complete, working token from your Mapbox account: a character was lost when copying, an extra space came along, or the token was copied from a different account than the one you meant to use. The test sends the token exactly as saved, as the access_token query parameter, so any difference is enough for Mapbox to refuse it.
Sign in at account.mapbox.com, open Access Tokens, copy a token from that page again in one go, paste it into access_token without typing any part by hand, save and test once.
Usage goes up even though the connection is not activated yet
Each test is a real call. The Directions API has no free probe endpoint, so the test can only prove the token works by asking for a real route — and that request uses one quota, exactly as the success message says: probe consumes one quota. Repeated testing before activation is real usage.
Test once. If it fails, read the failure, fix that one cause in the token, and only then test again. When the test passes, move on to the template and activation steps instead of testing again to double-check.
A route with many stops fails or comes back with no result
The request shape does not fit the Directions API through this connector: one route carries at most 25 coordinates, and the coordinates must be in longitude,latitude order. A list built as latitude,longitude, or a route packed with more coordinates than the limit, will not return the route you expected.
Check the coordinate list for that route: put every point in longitude,latitude order and keep the count at 25 or fewer. For a longer journey, split it into legs of at most 25 coordinates each and calculate the legs one by one.
Distances and durations look wrong for a lane you know well
The route was calculated with a different Directions profile than you expected, or with the two numbers of a point swapped. The template sends driving, driving-traffic, walking and cycling as the profile of the same name, and points go in longitude,latitude order — a walking result read as a driving result, or a point with latitude first, gives a route that looks wrong even though the call worked.
Check two things for that lane: the profile the TMS request used, and the order of every coordinate pair. Fix the profile or the pair order to match the lane, then recalculate and judge the new result only against the same profile.
The stops come back in the order given, not in the best order
That is the limit of this connection. It calculates a route through the points in the order they are given, using the Directions API. Working out the best visiting order for many stops is a different job, and this connection does not do it — the route is correct for the order supplied, it is just not reordered for you.
Decide the visiting order yourself in TMS before you ask for the route, and give the points to this connection in that order. Judge this connection only on the distance, duration and route for the order you supplied.
Activated, but no orders or tracking appear anywhere
Nothing is broken. This connection never carried orders or tracking in the first place: its only capability is route planning, so activation adds no order feed and no vehicle positions — it only lets TMS ask for distance, duration and route when a shipment or tender needs a lane estimate.
Use your order channels for orders and your carrier tools for tracking. Use this connection only where a lane cost or ETA is needed, and check its work in the route result of a shipment or tender in TMS.