key query parameter on every request, and it must have the Search, Routing or Traffic product enabled for the endpoints you call.
Things to know:
- Paging is offset based.
limitcaps at 100 andoffsetskips within the result set;summary.totalResultsis the total available;summary.numResultsis the size of this page. - A search with no matches is a success. TomTom answers 200 with an empty
resultsarray, so check the array rather than the status. radiusneeds a point. A radius withoutlatandlonis rejected before the request, because the API ignores it otherwise.- Routes take coordinates, not addresses. Geocode first, then pass the resulting positions.
originsanddestinationseach accept several waypoints, joined with colons in the path. - Traffic needs a bounding box.
traffic.incidentstakesminLon,minLat,maxLon,maxLatcovering at most 10,000 km², such as4.88,52.36,4.92,52.39for central Amsterdam. An inverted box is rejected here rather than at the provider. - Tiles are images, not JSON.
traffic.tilereturns{ content_type, base64 }: the PNG bytes base64-encoded. Both layers take a style in the path (stylefor flow,incident_stylefor incidents). - A 403 is a plan limit. The key is valid but does not cover the product or the region, so the plugin does not retry it.
- 7 typed API operations
Setup
1
Install
2
Add the plugin
corsair.ts
multiTenancy: true, scope calls with corsair.withTenant(id). See Quick start for KEK + Hub keys, and Multi-tenancy for account isolation.3
Choose authentication
- API Key (Recommended)
Store the TomTom API key before the first call: More: API Key
pnpm corsair setup --plugin=tomtom --tenant=acme api_key=<your-key> (leave out --tenant without multiTenancy), or pass it as key in the plugin options. With Hub, each tenant enters their own key on the connect page. See API key auth.4
Connect a tenant
Mint a connect link and send the tenant to it. Hub hosts the page and delivers the result to your app — see Connect / OAuth.
Example API calls
Search for a place with a geo biasWhat’s next
API reference
Every
tomtom.api.* operation with input and output types.Connect / OAuth
createLink, Hub delivery, and tenant connect flows.
Use with agents
Expose this plugin’s operations as MCP tools.