Migrate from the TomTom APIs to Mapricot
This guide moves an app's TomTom API calls to Mapricot. It lists the Mapricot endpoint for each TomTom API, how each parameter and response field carries over, and what has no equivalent. To weigh up the switch first, see Mapricot vs TomTom.
Mapricot's API isn't compatible with TomTom's, so each call changes. Coordinates keep TomTom's latitude-first order and lat and lon names, the query moves from the path to a parameter, and the response is flatter.
Migrate with a coding agent
Paste this prompt into Claude Code, Cursor, Codex, or another coding agent, in your project. It finds your TomTom calls, plans the switch with you, and makes it.
Migrate this project from TomTom's location APIs to Mapricot, a location API. https://mapricot.com/guides/migrate-from-tomtom/ maps each TomTom endpoint, parameter, and response field to Mapricot's, and https://mapricot.com/llms.txt lists Mapricot's docs.
1. Find every use of TomTom in this project: requests to api.tomtom.com, TomTom SDKs and packages, and TomTom maps. List each with what it does and the Mapricot endpoint that replaces it, and tell me about any that Mapricot can't replace. Wait for my OK before changing code.
2. Use Mapricot's client for this project's language if the docs list one; otherwise use plain HTTP. For server code, ask me to create a server key at https://app.mapricot.com/ and put it in MAPRICOT_KEY, wherever this project keeps secrets. Don't ask me to paste it here. Web pages need a browser key: create one with the create_key tool if you have Mapricot's MCP server, or ask me to.
3. Replace each call as the guide shows. Mapricot takes the search text as q rather than in the path, and rejects unknown parameters with a 400, so drop TomTom parameters that have no equivalent.
4. Move maps to MapLibre GL JS with Mapricot's map tiles, as https://mapricot.com/docs/map-tiles/ shows.
5. Credit the data wherever the project shows Mapricot's results, as https://mapricot.com/docs/attribution/ explains.
6. Run the tests, and make one real request to each endpoint you changed. Then remove TomTom's packages, keys, and settings, and tell me what changed and what's left.
The rest of this guide is what the agent works from, and what to check its changes against.
Endpoints
| TomTom | Mapricot |
|---|---|
Geocoding GET /search/2/geocode/{query}.json |
GET /geocoding/v1/search |
Structured geocoding GET /search/2/structuredGeocode.json |
GET /geocoding/v1/search, with the address in parts |
Reverse geocoding GET /search/2/reverseGeocode/{lat},{lon}.json |
GET /geocoding/v1/reverse |
Fuzzy search GET /search/2/search/{query}.json?typeahead=true, or Places Search POST /maps/orbis/places/suggest |
GET /geocoding/v1/autocomplete |
Nearby search GET /search/2/nearbySearch/.json, or Places Search POST /maps/orbis/places/discover with poiTypes |
GET /places/v1/nearby |
Place by ID GET /search/2/place.json, or Places Search GET /maps/orbis/places/details/{type}/{id} |
GET /places/v1/{id}, for a Mapricot ID |
Batch search POST /search/2/batch.json |
POST /geocoding/v1/search/batch, up to 100 searches |
Calculate Route GET /routing/1/calculateRoute/{locations}/json |
POST /routing/v1/route |
Calculate Route with computeBestOrder=true |
POST /routing/v1/optimize |
| Calculate Reachable Range | POST /routing/v1/isochrone |
| Maps SDK for Web and Map Display API | MapLibre GL JS with Mapricot's map tiles |
TomTom takes its key as key in the URL, or a TomTom-Api-Key header. Mapricot takes its key in a header, Authorization: Bearer mapricot_sk_…, except for map styles, which take it as ?key=. TomTom IDs don't work with Mapricot, so search again for any place you saved by its TomTom ID.
Geocoding
| TomTom | Mapricot |
|---|---|
{query} in the path |
q |
lat, lon |
focus=lat,lon |
countrySet=US,CA |
country=us,ca, up to 10 two-letter codes |
limit, up to 100 |
limit, up to 20 |
language |
lang |
Structured: streetNumber and streetName |
address, the house number and street together |
Structured: municipality |
locality |
Structured: countrySecondarySubdivision |
county |
Structured: countrySubdivision |
region |
Structured: postalCode |
postalCode |
Structured: countryCode |
country |
Reverse: {lat},{lon} in the path |
Reverse: lat and lon parameters |
radius, topLeft, btmRight, ofs, entityTypeSet, view |
None. focus ranks results near a point higher without a hard limit |
Results
TomTom results[] |
Mapricot results[] |
|---|---|
position.lat, .lon |
lat, lon |
Reverse: addresses[].position, a "lat,lon" string |
Reverse: results[].lat, .lon, numbers |
address.freeformAddress |
label |
poi.name |
name |
id |
id |
type, such as Point Address, Street, Geography, or POI |
type, such as address, street, locality, or venue |
address.streetNumber |
address.houseNumber |
address.streetName |
address.street |
address.municipality |
address.locality |
address.countrySubdivisionName, .countrySubdivisionCode |
address.region, address.regionCode |
address.postalCode |
address.postalCode |
address.country, .countryCode |
address.country, address.countryCode |
dist |
distanceMeters, on reverse and nearby results |
score, matchConfidence, viewport, entryPoints |
None |
Reverse results are in results, like every other Mapricot endpoint, rather than TomTom's addresses.
Autocomplete
TomTom fuzzy search with typeahead |
Mapricot autocomplete |
|---|---|
{query} in the path |
q |
lat, lon |
focus=lat,lon |
countrySet |
country |
limit |
limit |
language |
lang |
typeahead=true, minFuzzyLevel, maxFuzzyLevel, idxSet, categorySet |
None |
Places Search
TomTom's Places Search API takes a JSON POST for suggest and discover, with the key and API version in headers. Mapricot takes GET parameters instead:
| TomTom Places Search | Mapricot |
|---|---|
query |
q |
preferences.geometry, a point as [lon, lat] |
focus=lat,lon |
filters.countryCodesIso2 |
country, up to 10 two-letter codes |
maxResults, up to 10 for suggest or 100 for discover |
limit, up to 20 |
Accept-Language header |
lang, one language |
discover with filters.poiTypes and a circle in filters.geometry |
nearby with category, lat, lon, and radius |
origin, which only adds distanceInMeters |
None. Nearby results have distanceMeters from lat and lon |
filters.types |
None. Filter on each result's type instead |
Session-Id, Attributes, geopoliticalView, areaTypes, poiBrands, chargingLocation, fuelStation |
None. Each Mapricot response has every field |
TomTom Places Search results[] |
Mapricot results[] |
|---|---|
position.coordinates, as [lon, lat], on discover and details |
lat, lon, on every result |
title |
name |
subtitles, lines of the address |
label, the name and address in one line |
type: poi, address, street, intersection, or area |
type, such as venue, address, street, or locality |
address.houseNumber, .street, .postalCode |
address.houseNumber, .street, .postalCode |
address.municipality |
address.locality |
address.countrySubdivision, .countrySubdivisionCodeIso |
address.region, address.regionCode |
address.country, .countryCodeIso2 |
address.country, address.countryCode |
distanceInMeters |
distanceMeters, on reverse and nearby results |
poiTypes, poiBrands |
categories, when you send category to nearby, and brand |
discoverAction results, which suggest a category search, and more, the follow-up request |
None |
suggest results have no position, so apps follow the one picked with a details or discover request. Mapricot's autocomplete results have lat and lon, so that second request goes away.
Nearby places
| TomTom nearby search | Mapricot nearby |
|---|---|
lat, lon |
lat, lon |
radius, in meters |
radius, in meters, up to 50,000 |
categorySet=7315 |
category=food:restaurant, from Mapricot's categories |
limit, up to 100 |
limit, up to 20 |
language |
lang |
brandSet, openingHours, countrySet, ofs |
None |
Mapricot's categories are broader than TomTom's: TomTom's 7315, restaurants, is food:restaurant, and 7314, hotels and motels, is accommodation. Results come nearest first.
TomTom results[].poi |
Mapricot results[] |
|---|---|
name |
name |
phone |
phones |
url |
websites |
brands[].name |
brand |
categories |
categories, when you send category |
openingHours, with openingHours=nextSevenDays |
openingHours, in OpenStreetMap's format, where known |
Routes
TomTom puts the stops in the URL. Mapricot takes a JSON body:
curl "https://api.tomtom.com/routing/1/calculateRoute/43.7396,7.4275:43.734,7.4222/json?travelMode=pedestrian&instructionsType=text&key=…"
curl https://api.mapricot.com/routing/v1/route \
-H "Authorization: Bearer $MAPRICOT_KEY" \
-H "Content-Type: application/json" \
-d '{"waypoints": [{"lat": 43.7396, "lon": 7.4275}, {"lat": 43.734, "lon": 7.4222}], "mode": "walk", "steps": true}'
| TomTom | Mapricot |
|---|---|
{lat,lon:lat,lon:…} in the path |
waypoints, 2 to 20 {"lat", "lon"} objects |
travelMode=car |
"mode": "drive" |
travelMode=bicycle |
"mode": "bicycle" |
travelMode=pedestrian |
"mode": "walk" |
instructionsType=text |
"steps": true |
language |
lang |
avoid=tollRoads |
"costing": {"useTolls": 0} |
avoid=motorways |
"costing": {"useHighways": 0} |
avoid=ferries |
"costing": {"useFerry": 0} |
avoid=unpavedRoads |
"costing": {"excludeUnpaved": true} |
avoid=borderCrossings |
"costing": {"countryCrossingPenalty": 3600}, in seconds: a larger value avoids borders more |
avoid=carpools |
The default: carpool lanes are only used with includeHov2 or includeHov3 |
routeType=shortest |
"costing": {"shortest": true} |
vehicleHeight, vehicleWidth, vehicleLength |
costing.height, .width, .length, in meters |
vehicleWeight, in kilograms |
costing.weight, in tonnes: divide by 1,000 |
vehicleMaxSpeed |
costing.topSpeed |
traffic, departAt, arriveAt, maxAlternatives, routeType=eco or thrilling, truck and EV parameters |
None |
Both treat these as preferences: TomTom's avoid and Mapricot's costing each still use a toll road or ferry when there's no other way. TomTom's avoidAreas, avoid=tunnels, and avoid=lowEmissionZones have no equivalent.
| TomTom response | Mapricot response |
|---|---|
routes[].summary.lengthInMeters |
routes[].distanceMeters |
routes[].summary.travelTimeInSeconds |
routes[].durationSeconds, without traffic |
routes[].legs[].summary |
routes[].legs[].distanceMeters, .durationSeconds |
routes[].legs[].points, a list of {latitude, longitude} |
routes[].polyline, encoded, or a GeoJSON line with "geometries": "geojson" |
routes[].guidance.instructions[].message |
legs[].steps[].instruction |
guidance.instructions[].point |
steps[].lat, steps[].lon |
optimizedWaypoints[] with providedIndex and optimizedIndex |
waypointOrder, from optimize |
No route: 400 with detailedError.code NO_ROUTE_FOUND |
200 with {"routes": []}, not billed |
Mapricot's line is an encoded polyline by default, the encoding Google uses, rather than a list of points. Most map libraries and polyline packages decode it, or send "geometries": "geojson" and draw the line as it is.
Stop order
TomTom reorders the stops in the middle with computeBestOrder=true, and returns optimizedWaypoints, which list only those middle stops. Mapricot's optimize takes the same body as a route, also keeps the first and last waypoints in place, and returns waypointOrder, which lists every waypoint from 0, origin and destination included.
Reachable range
TomTom's Calculate Reachable Range takes one time budget in seconds, timeBudgetInSec, and returns one boundary as a list of points. Mapricot's isochrone takes up to four times in minutes, "minutes": [5, 10, 15], from "location": {"lat", "lon"}, and returns a GeoJSON polygon for each, largest first. TomTom's distance, fuel, and energy budgets have no equivalent.
Maps
Mapricot's map tiles work with MapLibre GL JS. Replace TomTom's Maps SDK for Web with MapLibre, and TomTom's style with a Mapricot style URL: new maplibregl.Map({ container: "map", style: "https://api.mapricot.com/tiles/v1/styles/default.json?key=mapricot_pk_…" }). Markers, popups, and GeoJSON layers are MapLibre's own, which MapLibre markers and popups and MapLibre routes show.
What has no equivalent
Keep these on TomTom, or replace them with something else:
- Live traffic, traffic incidents, and departure and arrival times.
- Matrix Routing, Long Distance EV Routing, and EV charging search.
- Truck routing with hazardous goods, and fuel and energy budgets.
- Place photos and reviews, and TomTom's satellite imagery.