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.
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.
Search
| 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_geojsonand the otherpolygon_*options. - Looking places up by OpenStreetMap ID,
extratags, andnamedetails. - Hard bounding box filters, with
viewboxandbounded. - The
detailsandstatusendpoints.