Migrate from Geocodio to Mapricot
This guide moves an app's Geocodio API calls to Mapricot. It lists the Mapricot endpoint for each Geocodio endpoint, how each parameter and response field carries over, and what has no equivalent. To weigh up the switch first, see Mapricot vs Geocodio.
Mapricot's API isn't compatible with Geocodio's, so each call changes. The main differences are lng, which becomes lon, smaller batches, and the address, which Mapricot keeps as one street field rather than Geocodio's number, directional, street, and suffix.
Migrate with a coding agent
Paste this prompt into Claude Code, Cursor, Codex, or another coding agent, in your project. It finds your Geocodio calls, plans the switch with you, and makes it.
Migrate this project from Geocodio to Mapricot, a location API. https://mapricot.com/guides/migrate-from-geocodio/ maps each Geocodio endpoint, parameter, and response field to Mapricot's, and https://mapricot.com/llms.txt lists Mapricot's docs.
1. Find every use of Geocodio in this project: requests to api.geocod.io, Geocodio client libraries, and any data appends requested with fields. List each with what it does and the Mapricot endpoint that replaces it, and tell me about any that Mapricot can't replace, such as census or congressional district data. 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. Geocodio's lng is Mapricot's lon, and Mapricot's batches hold up to 100 searches, so split larger ones. Mapricot rejects unknown parameters with a 400, so drop Geocodio 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 Geocodio'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
| Geocodio | Mapricot |
|---|---|
GET /v2.1/geocode |
GET /geocoding/v1/search |
POST /v2.1/geocode, up to 10,000 addresses |
POST /geocoding/v1/search/batch, up to 100 searches a request |
GET /v2.1/reverse |
GET /geocoding/v1/reverse |
POST /v2.1/reverse, a batch |
One GET /geocoding/v1/reverse per point |
GET /v2.1/distance with mode=driving |
One POST /routing/v1/route per destination |
| Lists, for spreadsheet uploads | The batch geocoding guide, which geocodes a CSV file with a short script |
Geocodio takes its key as api_key in the URL. Mapricot takes its key in a header, Authorization: Bearer mapricot_sk_….
Geocoding
| Geocodio | Mapricot |
|---|---|
q |
q |
street, with street2 |
address, with the unit in the same string |
city |
locality |
county |
county |
state_province |
region |
postal_code |
postalCode |
country, a name or code, defaulting to the US |
country, two-letter codes, up to 10. Without it, Mapricot searches the whole world |
limit |
limit, up to 20 |
addressee |
None. Leave the business name out of the address |
fields, format, and the distance_* parameters |
None |
Reverse: q=38.9,-77.0 |
Reverse: lat=38.9&lon=-77.0 |
Geocodio assumes the US when an address doesn't say otherwise. Mapricot covers the world, so send country=us to keep the same behavior for US addresses that leave out the country.
Geocodio's batch takes a JSON list of addresses, or an object keyed by your own IDs. Mapricot's takes {"queries": […]}, each with the same parameters as search, and answers in responses in the same order, so keep your IDs in a list alongside. A batch of 10,000 becomes 100 batches of 100.
Results
Geocodio results[] |
Mapricot results[] |
|---|---|
formatted_address |
label |
location.lat, .lng |
lat, lon |
accuracy_type: "rooftop" or "range_interpolation" |
type: "address" |
accuracy_type: "street_center" |
type: "street" |
accuracy_type: "place" or "county" |
type: "locality" or "county" |
address_components.number |
address.houseNumber |
address_components.formatted_street |
address.street |
address_components.city |
address.locality |
address_components.state_province |
address.regionCode, with the name in address.region |
address_components.postal_code |
address.postalCode |
address_components.country |
address.countryCode |
source |
source, and attribution for the whole response |
accuracy, a score |
None. Use type to tell an exact match from a broader one |
address_components.county, address_lines, stable_address_key, fields |
None |
Reverse: distance |
Reverse: distanceMeters |
Mapricot gives the street as one string, such as N Highland St, so code that joins Geocodio's predirectional, street, and suffix reads address.street instead.
Distance
Geocodio's Distance API gives the driving distance and time from one origin to many destinations. Mapricot's routing gives them for one route at a time: send a route from the origin to each destination, as waypoints with two points, and read routes[0].distanceMeters and durationSeconds. Each route is one request. Geocodio's distance_miles is Mapricot's meters divided by 1,609.34. Straight-line distances need no API at all.
What has no equivalent
Keep these on Geocodio, or replace them with something else:
- Data appends: census data, congressional and legislative districts, school districts, time zones, and the other
fields. - USPS ZIP+4 codes and the
addresseeparameter. - Lists, Geocodio's spreadsheet upload, and batches larger than 100.
- The distance matrix, for many origins at once.