Migrate from LocationIQ to Mapricot

This guide moves an app's LocationIQ API calls to Mapricot. It lists the Mapricot endpoint for each LocationIQ API, how each parameter and response field carries over, and what has no equivalent. To weigh up the switch first, see Mapricot vs LocationIQ.

Mapricot's API isn't compatible with LocationIQ's, so each call changes. LocationIQ's geocoding follows Nominatim's API and its routing follows OSRM's, so this guide links to the Nominatim and OSRM guides for those, and covers what's LocationIQ's own here.

Migrate with a coding agent

Paste this prompt into Claude Code, Cursor, Codex, or another coding agent, in your project. It finds your LocationIQ calls, plans the switch with you, and makes it.

Prompt
Migrate this project from LocationIQ to Mapricot, a location API. https://mapricot.com/guides/migrate-from-locationiq/ maps each LocationIQ endpoint, parameter, and response field to Mapricot's, linking to the Nominatim and OSRM guides for the parts LocationIQ shares with them, and https://mapricot.com/llms.txt lists Mapricot's docs.

1. Find every use of LocationIQ in this project: requests to locationiq.com hosts, LocationIQ SDKs and packages, and maps using LocationIQ's tiles. 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. LocationIQ returns lat and lon as strings, and its directions take lon,lat pairs, while Mapricot takes and returns lat and lon by name, as numbers. Mapricot rejects unknown parameters with a 400, so drop LocationIQ parameters that have no equivalent.
4. Point maps at 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 LocationIQ'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

LocationIQ Mapricot
GET /v1/search GET /geocoding/v1/search
GET /v1/search/structured GET /geocoding/v1/search, with the address in parts
GET /v1/reverse GET /geocoding/v1/reverse
GET /v1/autocomplete GET /geocoding/v1/autocomplete
GET /v1/nearby GET /places/v1/nearby
GET /v1/directions/{profile}/{coordinates} POST /routing/v1/route
GET /v1/optimize/{profile}/{coordinates} POST /routing/v1/optimize
Map tiles, tiles.locationiq.com/v3/{style}/vector.json /tiles/v1/styles/{style}.json

LocationIQ takes its key as key in the URL. Mapricot takes its key in a header, Authorization: Bearer mapricot_sk_…, except for map styles, which take it as ?key=. LocationIQ's place_id and OpenStreetMap IDs don't work with Mapricot's place lookup, so search again for any place you saved by them.

Search and reverse

LocationIQ's search, structured search, and reverse take Nominatim's parameters and return Nominatim's fields, so map them as Migrate from Nominatim shows: q stays q, countrycodes becomes country, accept-language becomes lang, and display_name becomes label. LocationIQ's own additions have no equivalent: normalizeaddress, normalizecity, statecode, matchquality, and postaladdress. Mapricot always returns address.regionCode, which is what statecode=1 adds.

Autocomplete

LocationIQ Mapricot
q q
countrycodes country, up to 10 codes
limit, up to 20 limit, up to 20
accept-language lang
viewbox focus=lat,lon, the box's center
tag, bounded, normalizecity, importancesort, dedupe None
display_place name
display_name label
address.name, .house_number, .road, .city, .state, .postcode, .country, .country_code name, address.houseNumber, .street, .locality, .region, .postalCode, .country, .countryCode
lat, lon, as strings lat, lon, as numbers

The address autocomplete guide builds a form on Mapricot's autocomplete.

Nearby places

LocationIQ Mapricot
lat, lon lat, lon
tag=restaurant category=food:restaurant, from Mapricot's categories
tag=all Leave out category
radius, in meters radius, in meters, up to 50,000
limit limit, up to 20
accept-language lang

LocationIQ's tags are OpenStreetMap's, and Mapricot's categories are broader: restaurant is food:restaurant, cafe is food:cafe, and hotel is accommodation. Results come nearest first. LocationIQ's distance becomes distanceMeters, and the address maps as for autocomplete.

Directions and optimize

LocationIQ's Directions and Optimize services are OSRM's route and trip services, so map them as Migrate from OSRM shows. The stops move from {lon},{lat};… in the URL to waypoints in a JSON body as {"lat", "lon"} objects, profile driving becomes "mode": "drive", walking becomes "walk", and each step gains a written instruction. Mapricot also routes for "mode": "bicycle".

LocationIQ's Matrix, Matching, and Nearest services have no equivalent.

Maps

Both serve MapLibre styles, so a map changes only its style URL. Replace https://tiles.locationiq.com/v3/streets/vector.json?key=… with https://api.mapricot.com/tiles/v1/styles/default.json?key=mapricot_pk_…, or another of Mapricot's styles. Mapricot's tiles are free, but take a browser key with the Map tiles product. Static maps and raster tiles have no equivalent.

What has no equivalent

Keep these on LocationIQ, or replace them with something else:

  • The Matrix, Matching, and Nearest routing services.
  • The Timezone API and static maps.
  • Looking places up by OpenStreetMap ID, and address normalization options.