# IP Geolocation and Fraud Score API - MaxMind GeoIP and minFraud (`nabeelbaghoor/ip-geolocation-fraud-score-api`) Actor

IP geolocation and fraud scoring from the MaxMind GeoIP and minFraud web services: country, city, postal code, coordinates, ASN, ISP, VPN, proxy and Tor flags, IP risk, plus minFraud transaction risk scores with email, card and address checks. Bring your own key.

- **URL**: https://apify.com/nabeelbaghoor/ip-geolocation-fraud-score-api.md
- **Developed by:** [Nabeel Hassan](https://apify.com/nabeelbaghoor) (community)
- **Categories:** Developer tools, Business, Integrations
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $5.00 / 1,000 geoip country record returneds

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

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

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

Example: score an order with minFraud Factors.

```json
{
    "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):

```json
{
    "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.

# Actor input Schema

## `mode` (type: `string`):

GeoIP Country returns the country, continent and registered country of each IP. GeoIP City Plus adds region, city, postal code, coordinates with accuracy radius, time zone, ASN, ISP, organization, domain and connection type. GeoIP Insights adds user type, confidence scores, the IP risk snapshot, static IP score, user count and VPN, proxy, hosting, residential proxy and Tor flags. minFraud Score returns a 0.01 to 99 fraud risk score for each transaction plus the IP risk. minFraud Insights adds GeoIP Insights for the IP and email, card, phone, address and device checks. minFraud Factors adds the reasons behind the risk score. Your MaxMind account must have credit for the service you pick.

## `ips` (type: `array`):

One IPv4 or IPv6 address per line, up to 10,000 a run. A port, a CIDR mask or brackets around an IPv6 address are stripped. GeoIP modes look up each address; the word me looks up the address the run connects from. minFraud modes score each address as an IP-only transaction.

## `transactions` (type: `array`):

minFraud modes only. A JSON array of transactions, each an object with the documented minFraud request objects: account, billing, credit_card, custom_inputs, device, email, event, order, payment, shipping and shopping_cart. Example: \[{"device": {"ip_address": "81.2.69.160"}, "email": {"domain": "example.com"}, "event": {"transaction_id": "order-1001", "type": "purchase"}, "order": {"amount": 49.9, "currency": "USD"}}]. Each transaction must stay under 20,000 bytes. Hash email addresses (MD5) if you prefer not to send them in the clear.

## `eventType` (type: `string`):

minFraud modes only. Sets event.type on every transaction that does not already have one, so minFraud scores it as that kind of event.

## `shopId` (type: `string`):

minFraud modes only. Sets event.shop_id on every transaction that does not already have one. Required by MaxMind for resellers, payment providers, gateways and affiliate networks. Use test, or a test prefix, while testing.

## `environment` (type: `string`):

Production calls geoip.maxmind.com and minfraud.maxmind.com. Sandbox calls sandbox.maxmind.com, which needs a license key from a MaxMind Sandbox account and answers with fixed test data for a small set of addresses.

## `skipNotFound` (type: `boolean`):

Leave out addresses MaxMind has no record for, reserved or private addresses and transactions MaxMind would not read. Off by default so you can see every miss. Misses are never charged either way.

## `concurrency` (type: `integer`):

How many MaxMind requests to keep in flight at once.

## `maxResults` (type: `integer`):

Stop after this many rows. Only this many addresses or transactions are sent, so it also caps the MaxMind credit a run uses.

## `accountId` (type: `string`):

Your numeric MaxMind account ID, shown on maxmind.com under Account, Manage License Keys. Sent only as the HTTP Basic user name. Or leave it empty and put accountId:licenseKey in the license key field or the DATA_API_KEY secret.

## `apiKey` (type: `string`):

A MaxMind license key for the account above, sent only as the HTTP Basic password and never logged. Required for every lookup. Stored as a secret.

## Actor input object example

```json
{
  "mode": "geoipCity",
  "ips": [
    "81.2.69.160",
    "2001:4860:4860::8888"
  ],
  "environment": "production",
  "skipNotFound": false,
  "concurrency": 5,
  "maxResults": 100
}
```

# Actor output Schema

## `records` (type: `string`):

One row per IP address or transaction for the chosen MaxMind service.

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "ips": [
        "81.2.69.160",
        "2001:4860:4860::8888"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("nabeelbaghoor/ip-geolocation-fraud-score-api").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = { "ips": [
        "81.2.69.160",
        "2001:4860:4860::8888",
    ] }

# Run the Actor and wait for it to finish
run = client.actor("nabeelbaghoor/ip-geolocation-fraud-score-api").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "ips": [
    "81.2.69.160",
    "2001:4860:4860::8888"
  ]
}' |
apify call nabeelbaghoor/ip-geolocation-fraud-score-api --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,nabeelbaghoor/ip-geolocation-fraud-score-api"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/7Y0jfq4g0UfiOF5uW/builds/QI44h5yqbFqlMZPP0/openapi.json