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.

Prompt
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

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:

TomTom
curl "https://api.tomtom.com/routing/1/calculateRoute/43.7396,7.4275:43.734,7.4222/json?travelMode=pedestrian&instructionsType=text&key=…"
Mapricot
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.