Migrate from Nominatim to Mapricot

This guide moves an app's Nominatim calls to Mapricot, whether they go to your own Nominatim server or the public one at nominatim.openstreetmap.org. It lists the Mapricot endpoint for each Nominatim endpoint, how each parameter and response field carries over, and what has no equivalent. To weigh up the switch first, see Mapricot vs Nominatim.

Mapricot's API isn't compatible with Nominatim's, so each call changes. Mapricot searches OpenStreetMap too, along with OpenAddresses and other open sources, so the results are familiar. Coordinates come back as numbers rather than strings, and the address has fixed field names rather than OpenStreetMap's tags.

Migrate with a coding agent

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

Prompt
Migrate this project from Nominatim to Mapricot, a location API. https://mapricot.com/guides/migrate-from-nominatim/ maps each Nominatim endpoint, parameter, and response field to Mapricot's, and https://mapricot.com/llms.txt lists Mapricot's docs.

1. Find every use of Nominatim in this project: requests to /search, /reverse, and /lookup on nominatim.openstreetmap.org or our own server, Nominatim client libraries such as geopy's Nominatim, and Leaflet or MapLibre geocoder plugins that use it. 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. Nominatim returns lat and lon as strings, and Mapricot as numbers. Mapricot rejects unknown parameters with a 400, so drop Nominatim parameters that have no equivalent, such as format and addressdetails.
4. Remove any throttling to one request a second that the project added for the public Nominatim server, and keep a sensible limit of our own.
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 Nominatim's packages 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

Nominatim Mapricot
GET /search?q= GET /geocoding/v1/search
GET /search with street, city, and other parts GET /geocoding/v1/search, with the address in parts
GET /search as people type GET /geocoding/v1/autocomplete
GET /reverse GET /geocoding/v1/reverse
GET /lookup?osm_ids= GET /places/v1/{id}, for a Mapricot ID
A loop of searches over a file POST /geocoding/v1/search/batch, up to 100 searches a request

Nominatim takes no key, and the public server asks for an identifying User-Agent or email and at most one request a second. Mapricot takes a key in a header, Authorization: Bearer mapricot_sk_…, and has no per-second rate limit, only a limit on requests in progress at once. The public Nominatim server's policy also forbids autocomplete, which Mapricot has an endpoint for.

Nominatim Mapricot
q q
street address
city locality
county county
state region
postalcode postalCode
country, a name or code country, two-letter codes
countrycodes=us,ca country=us,ca, up to 10 codes
limit, up to 40 limit, up to 20
accept-language=fr lang=fr, one language
viewbox focus=lat,lon, the box's center, which ranks results near it higher
format, addressdetails, extratags, namedetails, polygon_*, bounded, layer, featureType, exclude_place_ids, dedupe, email None. Mapricot always returns JSON with the address
amenity None. Put the name in q, or find a kind of place with nearby search

Mapricot takes the parts in place of q, as Nominatim does, and ignores parts sent blank.

Reverse

Nominatim Mapricot
lat, lon lat, lon
accept-language lang
zoom, layer, format, addressdetails None

Mapricot returns the nearest address or street, or the town, county, region, or country when there's none nearby, and can return up to 20 results with limit. Each has distanceMeters from the point. Reverse never returns businesses; use nearby search for those.

Results

Nominatim (jsonv2) Mapricot results[]
A list {"results": […], "attribution": […]}
lat, lon, as strings such as "45.5217" lat, lon, as numbers
display_name label
name name
osm_type, osm_id, place_id id, a Mapricot ID, and source
category and type, such as place and house type, such as address, street, locality, or venue
address.house_number address.houseNumber
address.road address.street
address.city, .town, or .village address.locality
address.state address.region
address.ISO3166-2-lvl4, such as US-OR address.regionCode, such as OR
address.postcode address.postalCode
address.country, .country_code, such as us address.country, address.countryCode, such as US
importance, place_rank, boundingbox, licence None. attribution lists the sources to credit
No results: [] {"results": []}

Nominatim's address keys depend on the OpenStreetMap tags, so code often checks city, then town, then village. Mapricot always uses locality, so those checks become one field read.

Lookup

Nominatim looks places up by OpenStreetMap ID, such as osm_ids=W123456. Mapricot looks them up by the id in its own results, one at a time: GET /places/v1/{id}. To move places you saved by OpenStreetMap ID, search for them once, store the Mapricot id, and look them up by it after that.

What has no equivalent

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

  • Boundary polygons, with polygon_geojson and the other polygon_* options.
  • Looking places up by OpenStreetMap ID, extratags, and namedetails.
  • Hard bounding box filters, with viewbox and bounded.
  • The details and status endpoints.