Migrate from OpenCage to Mapricot
This guide moves an app's OpenCage API calls to Mapricot. It lists the Mapricot endpoint for each OpenCage feature, how each parameter and response field carries over, and what has no equivalent. To weigh up the switch first, see Mapricot vs OpenCage.
Mapricot's API isn't compatible with OpenCage's, so each call changes. Both are built on open data, so results are similar. The main differences are that Mapricot has separate endpoints for forward and reverse geocoding, lng becomes lon, 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 OpenCage calls, plans the switch with you, and makes it.
Migrate this project from OpenCage to Mapricot, a location API. https://mapricot.com/guides/migrate-from-opencage/ maps each OpenCage parameter and response field to Mapricot's, and https://mapricot.com/llms.txt lists Mapricot's docs.
1. Find every use of OpenCage in this project: requests to api.opencagedata.com, OpenCage client libraries, and the Geosearch widget. Note which calls are reverse geocoding, with coordinates as the query, and which use annotations. 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. OpenCage's lng is Mapricot's lon, and reverse geocoding moves to its own endpoint. Mapricot rejects unknown parameters with a 400, so drop OpenCage parameters that have no equivalent.
4. Credit the data wherever the project shows Mapricot's results, as https://mapricot.com/docs/attribution/ explains.
5. Run the tests, and make one real request to each endpoint you changed. Then remove OpenCage'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
| OpenCage | Mapricot |
|---|---|
GET /geocode/v1/json?q={address} |
GET /geocoding/v1/search |
GET /geocode/v1/json?q={lat},{lng} |
GET /geocoding/v1/reverse |
| Geosearch | GET /geocoding/v1/autocomplete, which suggests addresses as well as place names |
| A loop of requests over a file | POST /geocoding/v1/search/batch, up to 100 searches a request |
OpenCage takes its key as key in the URL. Mapricot takes its key in a header, Authorization: Bearer mapricot_sk_…. OpenCage tells forward from reverse by whether the query looks like coordinates. Mapricot has an endpoint for each, so code that builds q from coordinates calls reverse with lat and lon instead.
Parameters
| OpenCage | Mapricot |
|---|---|
q, an address |
q |
q, coordinates such as 45.52,-122.68 |
lat=45.52&lon=-122.68 on reverse |
countrycode=us,ca |
country=us,ca, up to 10 codes |
proximity=45.52,-122.68 |
focus=45.52,-122.68 |
language |
lang |
limit, up to 100 |
limit, up to 20 |
no_annotations=1 |
Not needed: Mapricot has no annotations |
bounds |
None. focus at its center ranks results near it higher |
abbrv, address_only, add_request, no_dedupe, no_record, pretty, roadinfo |
None |
OpenCage takes one string. If you build that string from parts you already have, such as spreadsheet columns, send them to Mapricot as address, locality, region, and postalCode instead, which is more accurate for messy addresses.
Results
OpenCage results[] |
Mapricot results[] |
|---|---|
status.code: 200 |
HTTP 200 |
total_results: 0 |
An empty results list |
formatted |
label |
geometry.lat, .lng |
lat, lon |
components._type, such as building, road, or city |
type, such as address, street, locality, or venue |
components.house_number |
address.houseNumber |
components.road |
address.street |
components._normalized_city, or city, town, or village |
address.locality |
components.state, .state_code |
address.region, address.regionCode |
components.postcode |
address.postalCode |
components.country, .country_code, such as us |
address.country, address.countryCode, such as US |
confidence, from the size of the match's area |
type: address for an exact address, and a wider type for an area |
annotations, bounds, rate |
None |
| Reverse: no distance | Reverse: distanceMeters |
OpenCage's component 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. Mapricot's id is a stable ID you can store and look up later with /places/v1/{id}.
Geosearch
OpenCage's Geosearch is a widget that suggests place names, not street addresses. Mapricot has no widget, but its autocomplete suggests both, with coordinates in each result: q for the text, focus to rank results near the user, and country to limit them. The address autocomplete guide builds a search form on it.
What has no equivalent
Keep these on OpenCage, or replace them with something else:
- Annotations: time zones, currencies, calling codes, what3words, Maidenhead, MGRS, sun times, and road information.
- Hard bounding box filters, with
bounds. - Results in Google's v3 format.