Migrate from the HERE APIs to Mapricot
This guide moves an app's HERE API calls to Mapricot. It lists the Mapricot endpoint for each HERE API, how each parameter and response field carries over, and what has no equivalent. To weigh up the switch first, see Mapricot vs HERE.
Mapricot's API isn't compatible with HERE's, so each call changes. Coordinates keep HERE's latitude-first order, but lng becomes lon, country codes have two letters rather than three, and route lines use Google's polyline encoding rather than HERE's flexible polyline.
Migrate with a coding agent
Paste this prompt into Claude Code, Cursor, Codex, or another coding agent, in your project. It finds your HERE calls, plans the switch with you, and makes it.
Migrate this project from HERE's location APIs to Mapricot, a location API. https://mapricot.com/guides/migrate-from-here/ maps each HERE endpoint, parameter, and response field to Mapricot's, and https://mapricot.com/llms.txt lists Mapricot's docs.
1. Find every use of HERE in this project: requests to hereapi.com hosts, HERE SDKs and packages, the HERE Maps API for JavaScript, and flexible polyline decoding. 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. HERE's lng is Mapricot's lon, HERE's three-letter country codes become two-letter ones, and HERE's flexible polylines become standard encoded polylines. Mapricot rejects unknown parameters with a 400, so drop HERE 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 HERE'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
| HERE | Mapricot |
|---|---|
GET geocode.search.hereapi.com/v1/geocode |
GET /geocoding/v1/search |
GET revgeocode.search.hereapi.com/v1/revgeocode |
GET /geocoding/v1/reverse |
GET autosuggest.search.hereapi.com/v1/autosuggest or autocomplete.search.hereapi.com/v1/autocomplete |
GET /geocoding/v1/autocomplete |
GET discover.search.hereapi.com/v1/discover |
GET /geocoding/v1/search |
GET browse.search.hereapi.com/v1/browse |
GET /places/v1/nearby |
GET lookup.search.hereapi.com/v1/lookup |
GET /places/v1/{id}, for a Mapricot ID |
Routing v8 GET router.hereapi.com/v8/routes |
POST /routing/v1/route |
| Waypoints Sequence v8 | POST /routing/v1/optimize |
Isoline Routing v8 GET isoline.router.hereapi.com/v8/isolines |
POST /routing/v1/isochrone |
| HERE Maps API for JavaScript | MapLibre GL JS with Mapricot's map tiles |
Every Mapricot endpoint is on one host, https://api.mapricot.com. HERE takes its key as apiKey in the URL, or an OAuth token. Mapricot takes its key in a header, Authorization: Bearer mapricot_sk_…, except for map styles, which take it as ?key=. HERE IDs, such as here:pds:place:…, don't work with Mapricot, so search again for any place you saved by its HERE ID.
Geocoding
| HERE | Mapricot |
|---|---|
q |
q |
qq=houseNumber=…;street=… |
address, the house number and street together |
qq=city=… |
locality |
qq=county=… |
county |
qq=state=… |
region |
qq=postalCode=… |
postalCode |
in=countryCode:USA,CAN |
country=us,ca, with two-letter codes |
at=45.52,-122.68 |
focus=45.52,-122.68 |
limit, up to 100 |
limit, up to 20 |
lang |
lang, one language |
Reverse: at=45.52,-122.68 |
Reverse: lat=45.52&lon=-122.68 |
types, show, politicalView |
None. Filter on each result's type instead of types |
Mapricot takes an address in parts as separate parameters in place of q, where HERE packs them into qq.
Results
HERE items[] |
Mapricot results[] |
|---|---|
title |
name |
address.label |
label |
position.lat, .lng |
lat, lon |
id |
id |
resultType, such as houseNumber, street, or place |
type, such as address, street, or venue |
address.houseNumber |
address.houseNumber |
address.street |
address.street |
address.city |
address.locality |
address.state, .stateCode |
address.region, address.regionCode |
address.postalCode |
address.postalCode |
address.countryName, .countryCode, such as USA |
address.country, address.countryCode, such as US |
distance |
distanceMeters, on reverse and nearby results |
access, mapView, scoring |
None |
Autocomplete
HERE's autocomplete endpoint returns addresses without coordinates, so apps call lookup when someone picks one. Mapricot's autocomplete results have lat, lon, and the address already, so delete the lookup step. autosuggest already returns positions, and maps the same way as geocoding:
HERE autosuggest or autocomplete |
Mapricot autocomplete |
|---|---|
q |
q |
at |
focus |
in=countryCode:USA |
country=us |
limit |
limit |
lang |
lang |
termsLimit, types, politicalView |
None |
Mapricot returns places and addresses, not query suggestions such as "restaurants near me", so autosuggest results with resultType: "categoryQuery" or "chainQuery" have no equivalent.
Nearby places
HERE browse |
Mapricot nearby |
|---|---|
at=45.52,-122.68 |
lat=45.52&lon=-122.68 |
in=circle:45.52,-122.68;r=1000 |
radius=1000, in meters, up to 50,000 |
categories=100-1000-0000 |
category=food:restaurant, from Mapricot's categories |
limit |
limit, up to 20 |
lang |
lang |
name, foodTypes, chains |
None |
Mapricot's categories are broader than HERE's: HERE's 100-1000-0000, restaurants, is food:restaurant, and 100-1100-0010, coffee shops, is food:coffee_shop. Results come nearest first.
HERE items[] |
Mapricot results[] |
|---|---|
categories |
categories, when you send category |
contacts[].phone[].value |
phones |
contacts[].www[].value |
websites |
openingHours[].text |
openingHours, in OpenStreetMap's format, where known |
chains[].name |
brand |
Routes
| HERE Routing v8 | Mapricot |
|---|---|
origin, via (repeated), destination, each lat,lng |
waypoints, 2 to 20 {"lat", "lon"} objects, in order |
transportMode=car |
"mode": "drive" |
transportMode=bicycle |
"mode": "bicycle" |
transportMode=pedestrian |
"mode": "walk" |
return=polyline |
Always returned |
return=actions,instructions |
"steps": true |
lang |
lang |
avoid[features]=tollRoad |
"costing": {"useTolls": 0} |
avoid[features]=controlledAccessHighway |
"costing": {"useHighways": 0} |
avoid[features]=ferry |
"costing": {"useFerry": 0} |
avoid[features]=dirtRoad |
"costing": {"excludeUnpaved": true} |
vehicle[height], [width], [length], [grossWeight], in centimeters and kilograms |
costing.height, .width, .length in meters, and .weight in tonnes |
routingMode=short |
"costing": {"shortest": true} |
transportMode=truck, scooter, taxi, or bus, departureTime, arrivalTime, alternatives, spans, exclude |
None |
Both treat these as preferences: HERE's avoid and Mapricot's costing each still use a toll road or ferry when there's no other way. HERE adds a notice when its route breaks an avoid; Mapricot doesn't. HERE's exclude, which rules out countries strictly, has no equivalent.
| HERE response | Mapricot response |
|---|---|
routes[].sections[], one per stretch between stops |
routes[].legs[], one per pair of waypoints |
sections[].summary.length |
legs[].distanceMeters, and the total in routes[].distanceMeters |
sections[].summary.duration |
legs[].durationSeconds, and the total in routes[].durationSeconds |
sections[].polyline, a flexible polyline per section |
routes[].polyline, one encoded polyline for the whole route |
sections[].actions[].instruction |
legs[].steps[].instruction |
actions[].length, .duration |
steps[].distanceMeters, .durationSeconds |
No route: routes: [] with notices |
{"routes": []}, not billed |
HERE's flexible polyline needs HERE's decoder. Mapricot's polyline is the encoding Google uses, with five decimal places, which most map libraries and polyline packages decode. To skip decoding, send "geometries": "geojson" and draw the GeoJSON line as it is.
Stop order
HERE's Waypoints Sequence API returns the best order for a list of stops, which apps then send to Routing. Mapricot's optimize does both in one call: it takes the same body as a route, keeps the first and last waypoints in place, and returns the route in the best order with waypointOrder, the indexes of your waypoints in visiting order. It takes up to 20 stops, and has no time windows or vehicle constraints.
Isolines
| HERE Isoline Routing v8 | Mapricot |
|---|---|
origin=lat,lng |
"location": {"lat": …, "lon": …} |
transportMode |
mode, as for routes |
range[type]=time&range[values]=300,600 |
"minutes": [5, 10], up to 4, each up to 60: divide HERE's seconds by 60 |
range[type]=distance or consumption |
None |
shape[maxPoints] |
generalize, in meters: a larger value gives an outline with fewer points |
optimizeFor |
None |
HERE returns each isoline's outline as flexible polylines. Mapricot returns a GeoJSON FeatureCollection with one polygon per time, largest first, each with its minutes, which maps draw without decoding.
Maps
The HERE Maps API for JavaScript has no drop-in replacement, so map code is rewritten for MapLibre GL JS, which draws Mapricot's free map tiles. The concepts carry over: H.Map is maplibregl.Map, H.map.Marker is maplibregl.Marker, and H.ui.InfoBubble is maplibregl.Popup. MapLibre takes coordinates as [lng, lat] arrays, rather than HERE's {lat, lng} objects. MapLibre markers and popups and MapLibre routes show the pieces most apps need.
What has no equivalent
Keep these on HERE, or replace them with something else:
- Live traffic, departure and arrival times, and truck routing with hazardous goods.
- The Matrix Routing, Tour Planning, Route Matching, and EV charging APIs.
- Transit routing and public transit data.
- Satellite imagery and HERE's own map styles.