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.

Prompt
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.