Migrate from MaxMind to Mapricot

This guide moves an app's IP lookups from MaxMind to Mapricot's IP geolocation API, whether the app reads a GeoLite2 or GeoIP2 database file or calls MaxMind's web services. It shows the Mapricot request for each, how each response field carries over, and what has no equivalent. To weigh up the switch first, see Mapricot vs MaxMind.

Mapricot's API isn't compatible with MaxMind's, so each lookup changes. From a web service, it's a new URL and flatter fields. From a database file, it's a bigger change: each lookup becomes an HTTP request, and there's no file to download and update each week.

Migrate with a coding agent

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

Prompt
Migrate this project's IP geolocation from MaxMind to Mapricot, a location API. https://mapricot.com/guides/migrate-from-maxmind/ maps each MaxMind lookup and response field to Mapricot's, and https://mapricot.com/llms.txt lists Mapricot's docs.

1. Find every use of MaxMind in this project: GeoLite2 or GeoIP2 .mmdb files and the code that reads them, geoipupdate and other download jobs, MaxMind client libraries, and requests to geolite.info or geoip.maxmind.com. List each with what it does and which fields it uses, 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. Ask me to create a server key with the IP geolocation product at https://app.mapricot.com/ and put it in MAPRICOT_KEY, wherever this project keeps secrets. Don't ask me to paste it here.
3. Replace each lookup as the guide shows. A database lookup was local, so where the code looks up the same IP address many times, cache results for a day or more, and handle a request that fails or times out the way the code handled a missing database. Mapricot returns "found": false rather than an error for an address with no known location.
4. Credit DB-IP wherever the project shows these locations, as https://mapricot.com/docs/attribution/ explains.
5. Run the tests, and look up one real address. Then remove MaxMind's packages, database files, download jobs, and license keys, 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.

Lookups

MaxMind Mapricot
GeoLite2 or GeoIP2 City database, reader.city(ip) GET /ip-geolocation/v1/{ip}
GeoLite2 or GeoIP2 Country database, reader.country(ip) GET /ip-geolocation/v1/{ip}, reading the country fields
Web service GET geolite.info/geoip/v2.1/city/{ip} GET /ip-geolocation/v1/{ip}
Web service GET geoip.maxmind.com/geoip/v2.1/city/{ip} GET /ip-geolocation/v1/{ip}
Web service …/city/me, for the caller GET /ip-geolocation/v1/{ip} with the visitor's address, read from the request on your server

MaxMind's web services use HTTP basic authentication, with your account ID and license key. Mapricot takes its key in a header, Authorization: Bearer mapricot_sk_…. Keep that key on your server: the lookup runs there, with the visitor's IP address.

Response fields

MaxMind Mapricot
continent.code continentCode
country.iso_code countryCode
country.names.en countryName, in English
subdivisions[0].names.en regionName
city.names.en city
location.latitude, .longitude location.lat, .lon
location.accuracy_radius None: treat the point as somewhere in the city or region
traits.ip_address ip
subdivisions[].iso_code, postal.code, location.time_zone, registered_country, traits.network None
names in other languages None
Address not in the data: AddressNotFoundError, or 404 from the web service 200 with "found": false, which still counts as a request
A private or reserved address 400, which isn't billed

Mapricot leaves out fields the data doesn't have, rather than sending them empty, so check for city before using it. source, attributionUrl, licenseUrl, and datasetRelease say where the data came from and which month's release answered.

From a database file to an API

A database lookup takes microseconds and never fails once the file is loaded. An API lookup takes a network round trip and can fail, so:

  • Look up once per visitor, not on every page view, and keep the answer in the session or a cache keyed by IP address. Locations change slowly, so a day is a safe time to keep one.
  • Decide what happens on failure. Use a default country, as you would for an address the database didn't have, and set a short timeout so a slow lookup doesn't hold up the page.
  • Delete the update job. There's no database to download, no license key for downloads, and no weekly geoipupdate run.

Each lookup is one request from the shared free allowance, and Mapricot doesn't write the addresses you look up to usage records or logs.

What has no equivalent

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

  • Offline lookups from a local database file.
  • Accuracy radius, postal codes, time zones, and names in languages other than English.
  • The ASN, Connection Type, Anonymous IP, and ISP databases, and GeoIP Insights.
  • minFraud and other fraud scoring.