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.

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