IP Geolocation and Fraud Score API - MaxMind GeoIP and minFraud

Geolocate IP addresses, flag VPNs, proxies and hosting ranges, and score transactions for fraud risk with the MaxMind GeoIP and minFraud web services, using your own MaxMind account, as one clean dataset row per IP address or transaction.

Works with the official MaxMind web services: GeoIP Country, GeoIP City Plus and GeoIP Insights on geoip.maxmind.com, and minFraud Score, minFraud Insights and minFraud Factors on minfraud.maxmind.com, plus the MaxMind Sandbox for testing. Paste IPs from server logs, signups, checkouts or a CRM export and get back country, region, city, postal code, coordinates, time zone, ASN, ISP, organization, connection type, user type and anonymizer flags, or send transactions and get back the minFraud risk score with IP, email, card, phone and address checks, ready to download as JSON, CSV or Excel, schedule, or feed into fraud review, analytics and routing. Bring your own API key.

BYOK, route-checked but not live-tested: every path, field and error code comes from dev.maxmind.com and MaxMind's published OpenAPI documents, and each route was confirmed with a probe (documented paths answer 401 AUTHORIZATION_INVALID to an invalid account ID and license key, invented paths 404 with an HTML page), but the actor has not been run against a live MaxMind account.

What it does

• GeoIP Country: country and continent with ISO codes, EU membership, registered and represented country and the network the record covers, for each IPv4 or IPv6 address.
• GeoIP City Plus: adds region (subdivision), city, postal code, latitude and longitude with accuracy radius, time zone, ASN and AS organization, ISP, organization, domain, connection type and mobile network codes.
• GeoIP Insights: adds user type (residential, business, hosting, cellular and more), country, city and postal confidence, IP risk snapshot, static IP score, user count, average income and population density (US), and the anonymizer block: VPN with provider name, public proxy, residential proxy with provider, hosting provider and Tor exit node.
• minFraud Score: a fraud risk score from 0.01 to 99 for each transaction, the IP risk, any custom rule disposition and input warnings.
• minFraud Insights: adds GeoIP Insights for the transaction IP, email and email domain risk (disposable, free, high risk, first seen), card issuer, brand, type, prepaid and virtual flags, billing and shipping distance to the IP, phone checks and device ID.
• minFraud Factors: adds the risk score reasons, such as ANONYMOUS_IP or EMAIL_VELOCITY, that raised or lowered the score.
• Bulk and flat: up to 10,000 IPs or transactions a run, several requests in parallel, one flat row each with the full MaxMind answer kept under record.
• Misses are visible and free: an address not in the database, a private or reserved address, or a transaction MaxMind will not read becomes a row with found false and a note, and is never charged.

How to get an API key

Sign up at maxmind.com for a GeoIP web services trial or buy credit for GeoIP or minFraud, then open Account, Manage License Keys. Copy your numeric account ID and generate a license key. Paste the account ID into accountId and the license key into apiKey, or set the DATA_API_KEY secret to accountId:licenseKey. For testing, a Sandbox account (sandbox.maxmind.com) has its own license keys.

Input

Field	Modes	Description
mode	all	geoipCountry, geoipCity (default), geoipInsights, minfraudScore, minfraudInsights or minfraudFactors
ips	all	One IPv4 or IPv6 address per line, up to 10,000. GeoIP accepts me for the run's own address. minFraud scores each as an IP-only transaction
transactions	minFraud	JSON array of minFraud request objects (device, email, billing, shipping, order, credit_card, payment, account, event, shopping_cart, custom_inputs)
eventType	minFraud	Sets event.type, such as purchase or account_creation, where missing
shopId	minFraud	Sets event.shop_id where missing
environment	all	production (default) or sandbox
skipNotFound	all	Leave misses out of the dataset (default false)
concurrency	all	Parallel requests, 1 to 20 (default 5)
maxResults	all	Row ceiling for the run (default 100)
accountId	all	Your MaxMind account ID
apiKey	all	Your MaxMind license key (or the DATA_API_KEY secret as accountId:licenseKey)

Example: geolocate two addresses with GeoIP City Plus.

{
    "mode": "geoipCity",
    "ips": ["81.2.69.160", "2001:4860:4860::8888"]
}

Example: score an order with minFraud Factors.

{
    "mode": "minfraudFactors",
    "transactions": [{
        "device": { "ip_address": "81.2.69.160", "user_agent": "Mozilla/5.0" },
        "email": { "address": "977577b140bfb7c516e4746204fbdb01", "domain": "example.com" },
        "billing": { "country": "GB", "postal": "SW1A 1AA" },
        "event": { "transaction_id": "order-1001", "type": "purchase" },
        "order": { "amount": 49.9, "currency": "GBP" }
    }]
}

Example output

A GeoIP Insights row (illustrative values in the shape MaxMind documents):

{
    "mode": "geoipInsights",
    "service": "GeoIP Insights",
    "input": "81.2.69.160",
    "found": true,
    "ip": "81.2.69.160",
    "network": "81.2.69.160/27",
    "countryCode": "GB",
    "country": "United Kingdom",
    "countryConfidence": 99,
    "region": "England",
    "regionCode": "ENG",
    "city": "London",
    "postalCode": "SW1A",
    "latitude": 51.5142,
    "longitude": -0.0931,
    "accuracyRadiusKm": 10,
    "timeZone": "Europe/London",
    "asn": 20712,
    "asOrganization": "Andrews & Arnold Ltd",
    "isp": "Andrews & Arnold Ltd",
    "connectionType": "Cable/DSL",
    "userType": "residential",
    "ipRiskSnapshot": 0.5,
    "isAnonymousVpn": false,
    "isHostingProvider": false,
    "isTorExitNode": false,
    "queriesRemaining": 54321,
    "record": { "...": "the full MaxMind answer" }
}

A minFraud Factors row adds riskScore, ipRisk, minfraudId, dispositionAction, emailIsDisposable, emailDomainClassification, cardBrand, billingDistanceToIpKm, riskScoreReasons (for example ["ANONYMOUS_IP"]), warnings and fundsRemaining.

FAQ

What is MaxMind?

MaxMind is the company behind GeoIP, one of the most widely used IP geolocation and IP intelligence datasets, and minFraud, a transaction fraud detection service used by ecommerce, fintech and marketplaces. Its web services answer per IP address or per transaction over HTTPS with HTTP Basic auth.

Do I need my own MaxMind account?

Yes. This is a bring-your-own-key actor: it calls MaxMind with your account ID and license key, under your account's credit and the MaxMind End User License Agreement. A missing or rejected credential, or an empty balance, ends the run cleanly with a status message that explains what to change, and nothing is charged.

Does the free GeoLite account work?

No. The GeoLite web services on geolite.info are not offered here; this actor calls the paid GeoIP and minFraud web services and the MaxMind Sandbox. A GeoLite-only license key answers 401 or 403 and the run ends with that message.

What is the difference between GeoIP City Plus and GeoIP Insights?

City Plus returns location and network data: city, region, postal code, coordinates, time zone, ASN, ISP and connection type. Insights adds IP intelligence: user type, confidence scores, the IP risk snapshot, static IP score, user count and the anonymizer flags for VPN, public proxy, residential proxy, hosting provider and Tor exit node.

How accurate is IP geolocation?

IP geolocation is approximate. MaxMind returns an accuracy radius in kilometers around the coordinates, and states the coordinates must not be used to identify a street address or household. Show the radius whenever you show the coordinates.

What does the minFraud risk score mean?

It is MaxMind's estimate, from 0.01 to 99, of the percentage chance that the transaction is fraudulent. Send as many fields as you have (IP, email, billing and shipping address, card BIN, order amount) for a sharper score; an IP-only transaction still gets a score.

What do I pay?

Pay per result: 0.005 USD per GeoIP Country record, 0.008 USD per City Plus record, 0.012 USD per Insights record, 0.01 USD per minFraud Score result and 0.02 USD per minFraud Insights or Factors result. Misses, reserved addresses and refused requests are never charged. MaxMind bills your own account separately for each query.

What happens if my credentials are wrong or my credit runs out?

401 (AUTHORIZATION_INVALID), 402 (INSUFFICIENT_FUNDS) and 403 (PERMISSION_REQUIRED) end the run cleanly with MaxMind's own code. 429 and 5xx answers are retried with backoff a few times before the run stops.

Pricing

Event	Price	Charged for
ip-country-record	0.005 USD	Each IP GeoIP Country answers
ip-city-record	0.008 USD	Each IP GeoIP City Plus answers
ip-insights-record	0.012 USD	Each IP GeoIP Insights answers
fraud-score	0.01 USD	Each transaction minFraud Score scores
fraud-insights	0.02 USD	Each transaction minFraud Insights or Factors scores

Keyword map

MaxMind API, GeoIP2 web service, GeoIP API, IP geolocation API, IP to country, IP to city, IP to ISP, IP to ASN, bulk IP lookup, VPN detection, proxy detection, residential proxy detection, Tor exit node check, hosting IP detection, IP risk score, IP intelligence, minFraud API, fraud score API, transaction fraud detection, ecommerce fraud screening, chargeback prevention, email risk, card BIN check.

Terms and data use

Use of the MaxMind web services is governed by the MaxMind End User License Agreement (maxmind.com/en/end-user-license-agreement, dated February 12, 2026). Section 3(1) and section 4.1(4) limit use to your own Internal Restricted Business Purposes, which section 2.8 defines as content customization, fraud prevention and geographic reporting, and which excludes sharing GeoIP Data with third parties (2.8(3)) and offering geolocation to platforms other users can access (2.8(1), 4.1(10)) unless you hold a redistribution license. Section 4.1(6) forbids publishing, distributing, selling or sublicensing the Services, section 4.2 forbids disclosing GeoIP Data to any third party except as the agreement allows, and section 4.1 forbids using the Services to identify or locate a specific individual or household. Section 6 forbids giving minFraud outputs to the person whose transaction was scored. The 30-day destruction rule in section 4.3 applies to old versions of the GeoIP Databases, not to web service answers, and the agreement sets no storage or cache time limit for web service results. Run this actor with your own account, keep the results inside your own organization, and do not resell, publish or redistribute them. minFraud requests can carry personal data (email, address, IP); send only what your privacy notice covers, and hash email addresses if you prefer. MaxMind data incorporates GeoNames data under CC BY 4.0. This actor is not affiliated with or endorsed by MaxMind.