Skip to content

IP Risk API documentation

The risk score, VPN, proxy, Tor and datacenter flags, location and network of any IP address, in JSON. Authenticate with an API key and start querying.

Your key is stored in your browser's localStorage and never sent to our servers except in API requests.

Authentication

All API requests require an API key, sent in an X-API-Key header or as Authorization: Bearer <key> (the same header the MCP server takes). Send one of them; if both are sent with different keys, the request is refused with 400 API_KEY_CONFLICT.

curl -H "X-API-Key: mih_live_a1b2c3d4e5f6..." \
  https://www.myiphelp.com/api/v1/ipdata/lookup/8.8.8.8

curl -H "Authorization: Bearer mih_live_a1b2c3d4e5f6..." \
  https://www.myiphelp.com/api/v1/ipdata/lookup/8.8.8.8

Keys start with mih_live_. Every request returns real data and counts against your plan's monthly quota and rate limits. To try the API, use a key on the Free plan: real lookups, no card.

Generate keys at Account → API → Keys.

Base URL

https://www.myiphelp.com/api/v1/ipdata

All endpoint paths below are relative to this base URL.

IP Lookup

Full geolocation and enrichment data for a single IP address.

GET /lookup/{ip}

Parameters

ip path Required IPv4 or IPv6 address

Example Response

{
  "success": true,
  "data": {
    "ip": "8.8.8.8",
    "country": "United States",
    "country_code": "US",
    "state": "California",
    "state_code": "CA",
    "city": "Mountain View",
    "geoname_id": 5375480,
    "latitude": 37.419,
    "longitude": -122.057,
    "timezone": "America/Los_Angeles",
    "continent": "North America",
    "continent_code": "NA",
    "isp": "Google LLC",
    "asn": 15169,
    "asn_name": "GOOGLE",
    "organization": "Google LLC",
    "hostname": "dns.google",
    "risk_score": 15,
    "risk_band": "low",
    "risk_label": "Low risk",
    "risk_reason": "Datacenter address",
    "is_vpn": false,
    "is_tor_exit": false,
    "is_proxy": false,
    "is_relay": false,
    "is_verified_bot": false,
    "bot_name": null,
    "bot_operator": null,
    "is_drop_listed": false,
    "drop_sbl_id": null,
    "is_anonymous": false,
    "is_datacenter": true,
    "is_eu": false,
    "country_flag": "\ud83c\uddfa\ud83c\uddf8",
    "country_tld": ".us",
    "currency_name": "United States dollar",
    ...
  },
  "meta": {
    "attribution": "Free IP geolocation data provided by MaxMind (https://www.maxmind.com/), creator of GeoIP®. IP Geolocation by DB-IP (https://db-ip.com/)."
  }
}

Lookup Own IP

Look up the geolocation of the requesting server's IP address. Returns the same data as IP Lookup.

GET /lookup/me

Bulk Lookup

Look up multiple IP addresses in a single request, on every plan: up to Starter 20, Pro 100, Business 500, Enterprise 1,000 IPs per request.

POST /lookup/bulk

Parameters

ips body Required Array of IP addresses (at most: Starter 20, Pro 100, Business 500, Enterprise 1,000)

Each IP that returns data counts as one lookup toward your monthly quota (private, reserved and unknown IPs don't). A request with more IPs than your quota has left is refused whole with 429 QUOTA_EXCEEDED and nothing is counted — send a smaller batch. meta.lookups_counted shows how many were counted.

ASN Lookup

One network (autonomous system) by its AS number, with or without the AS prefix: its name, how many IPv4 and IPv6 ranges it announces, its IPv4 address count, its largest IPv4 prefixes (up to 10) and its page on this site. From Pro, is_datacenter. A network that is found counts as one lookup; 400 INVALID_ASN and 404 ASN_NOT_FOUND do not count. The ranges come from IPtoASN, credited in meta.attribution.

GET /asn/{asn}

Example Response (Business)

GET /asn/AS13335

{
  "success": true,
  "data": {
    "asn": 13335,
    "asn_name": "CLOUDFLARENET",
    "ipv4_ranges": 1873,
    "ipv6_ranges": 312,
    "ipv4_addresses": 1652736,
    "largest_prefixes": ["104.16.0.0/13", "172.64.0.0/13", "..."],
    "is_datacenter": true,
    "asn_page": "https://www.myiphelp.com/asn/AS13335/"
  },
  "meta": {
    "attribution": "Network data from IPtoASN (https://iptoasn.com/)."
  }
}

My IP

Return the caller's IP address (no geolocation data).

GET /me

Example Response

{ "success": true, "data": { "ip": "203.0.113.42" } }

Usage Stats

Returns your current billing period usage: lookups.used counts single lookups plus bulk IPs (what the quota counts, split into single and bulk_ips), with tools and rate limit info.

GET /usage

MCP Server (AI assistants)

Claude, Cursor, VS Code and other MCP clients can look up IP addresses with your API key through the hosted MCP server. Free keys work. Every tool call is an API request: the same plan, monthly quota, rate limit, fields and attribution as the REST API. What each tool does, with example prompts: the MCP server page.

https://www.myiphelp.com/mcp/v1

Streamable HTTP. Send your key as Authorization: Bearer mih_live_... (or X-API-Key).

Tool What it answers
lookup_ip Location, network and risk score of one address (the fields of your plan).
bulk_lookup Several addresses in one call, sent in batches of your plan's bulk size (Free: 20).
check_ip_risk The risk verdict: score, band, label and the main reason behind it (risk_reason) on every plan; the full breakdown and the flags from Pro.
lookup_asn The network (ASN, ISP, organization) behind an address, or a network by its AS number (AS13335 or 13335), with its page on this site.
get_my_usage Your plan, lookups used and left, and when the month resets. Costs no lookup.

Claude Code

claude mcp add --transport http --scope user myiphelp https://www.myiphelp.com/mcp/v1 --header "Authorization: Bearer YOUR_KEY"

--scope user makes the server work in every folder; without it, Claude Code adds it to the current folder only.

Claude (claude.ai, Claude Desktop) and ChatGPT: sign in, no key

Add https://www.myiphelp.com/mcp/v1 as a custom connector (Claude: Settings → Connectors → Add custom connector; ChatGPT: a connector in developer mode, with OAuth). The app opens our sign-in: sign in to your My IP Help account (email or Google) and allow it. Its lookups count against your plan, and you can disconnect it on Account → API → Keys. The tool list needs no sign-in; the first lookup asks for it.

Claude Desktop with an API key

To use a key instead of signing in, connect through mcp-remote (needs Node.js). In claude_desktop_config.json (Settings → Developer → Edit Config). The key sits in env because a space inside args breaks on Windows:

{
  "mcpServers": {
    "myiphelp": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://www.myiphelp.com/mcp/v1",
               "--header", "Authorization:${AUTH_HEADER}"],
      "env": { "AUTH_HEADER": "Bearer YOUR_KEY" }
    }
  }
}

Cursor

In ~/.cursor/mcp.json (or the project's .cursor/mcp.json):

{
  "mcpServers": {
    "myiphelp": {
      "url": "https://www.myiphelp.com/mcp/v1",
      "headers": { "Authorization": "Bearer YOUR_KEY" }
    }
  }
}

VS Code (GitHub Copilot)

In .vscode/mcp.json; VS Code asks for the key once and stores it:

{
  "inputs": [
    { "type": "promptString", "id": "myiphelp-key", "description": "My IP Help API key", "password": true }
  ],
  "servers": {
    "myiphelp": {
      "type": "http",
      "url": "https://www.myiphelp.com/mcp/v1",
      "headers": { "Authorization": "Bearer ${input:myiphelp-key}" }
    }
  }
}

Example prompts

  • “Where is 8.8.8.8 and who runs it?”
  • “Is 185.220.101.1 risky? Why?”
  • “Here are the IPs from my login log: which ones are VPNs or datacenters?” (one bulk_lookup call)
  • “Which network is 1.1.1.1 on?”
  • “How many lookups do I have left this month?”

Troubleshooting

  • 401 error, or “Server rejected the configured Authorization header”: the key was revoked or mistyped. Check the key, or create a new one. Then, in Claude Code, run claude mcp remove myiphelp --scope user, then add the server again with the new key.
  • The tools do not show up: tools load when a session starts. Start a new session, or run /mcp in Claude Code to reconnect.
  • Never paste your key into a chat or share it. After you replace a key, update it in every assistant and script that uses it.

More help: MCP troubleshooting.

Attribution. Every tool result with IP data carries the credits of the sources behind it, the API answer's meta.attribution (Data Attribution), in the result and its _meta.attribution; a bulk_lookup result every credit its addresses need. If an assistant shows the data to other people, keep the credit with it.

Response Fields

Fields included in the IP lookup response depend on your plan's field tier.

Group Fields Free Pro Biz Ent
Risk Score risk_score (0–100), risk_band (low / medium / high), risk_label, risk_reason (the main reason behind the score, e.g. "On the Tor exit list"; null when nothing was found)
Risk Breakdown risk_signals: [{ key, label, points, source, detail }] — every signal behind the score, with its points —
Core Geo country, country_code, state, state_code, city, geoname_id, latitude, longitude, timezone, continent, continent_code
Network isp, asn, asn_name, organization, hostname, domain
Postal postal_code —
Security is_vpn, is_tor_exit, is_proxy, is_relay, is_datacenter, is_bogon, is_anonymous, threat_score, ip_type, is_verified_bot, bot_name, bot_operator (a crawler, monitor or webhook sender in its operator's published ranges), is_drop_listed, drop_sbl_id (a hijacked or criminal network — Spamhaus DROP, © The Spamhaus Project, free under its terms) —
Cloud cloud_provider, cloud_region —
Country Meta currency_code, currency_name, currency_symbol, languages, calling_code, capital, country_tld, country_flag, is_eu —
Allocation rir, allocation_date, registration_country —
Summary summary (verdict + overview) —
Sanctions is_sanctioned_country, sanctions_programs, corruption_index — —

The API's risk_score, risk_reason and risk_signals come from the Tor Project exit list, Spamhaus DROP, IP2Proxy LITE, public proxy lists, VPN provider ranges, cloud and datacenter ranges, iCloud Private Relay ranges and operators' published bot ranges; threat_score from the Tor exit list, Spamhaus DROP, VPN and datacenter ranges and reserved (bogon) ranges. Two blocklist sources the website's risk check also reads, the FireHOL attack levels and IPsum's blocklist count (both include DShield), are not used in the API, so an API score can be lower than the website's for the same address.

Data Attribution

The geolocation fields come from MaxMind GeoLite and DB-IP Lite, the hijacked-network fields from Spamhaus DROP and the proxy signal from IP2Proxy LITE, and each requires a credit. These are all four credits:

Free IP geolocation data provided by MaxMind (https://www.maxmind.com/), creator of GeoIP®. IP Geolocation by DB-IP (https://db-ip.com/). Hijacked-network data: Spamhaus DROP, © The Spamhaus Project (https://www.spamhaus.org/). My IP Help uses the IP2Proxy LITE database for proxy and VPN detection (https://www.ip2location.com).

Each lookup response carries the credits of the sources behind that answer: in the JSON as meta.attribution, and in the X-Attribution header (the same text in ASCII). MaxMind and DB-IP are always in it; Spamhaus only when the answer has a DROP match, and IP2Proxy LITE only when its proxy signal is in the answer, even where your plan leaves out the field that shows it (the score and risk_reason can rest on it). A bulk answer carries every credit its rows need, and so do MCP tool results. The ASN lookup carries IPtoASN's.

If your application shows these fields to its own users (pages, dashboards, alerts, reports), show this credit with them, for example:

Free IP geolocation data provided by <a href="https://www.maxmind.com/">MaxMind</a>, creator of GeoIP<sup>&reg;</sup>. IP Geolocation by <a href="https://db-ip.com">DB-IP</a>.

IP2Proxy LITE (IP2Location), the source of the proxy signal: My IP Help uses the IP2Proxy LITE database for proxy and VPN detection.

The full list of sources and their terms is on Data sources.

Plans & Pricing

Free

$0 forever

Core geolocation data. No credit card required.

  • 1,000 lookups/mo
  • 10 req/min, bursts of 30
  • Geo + network fields
  • Bulk (20 IPs/req)
  • 1 API key, real data
  • HTTPS included
Most Popular

Pro

$29 /month

Security intelligence and bulk lookups.

  • 100,000 lookups/mo
  • 60 req/min, bursts of 180
  • VPN, proxy, Tor, threat — $99+ elsewhere
  • Bulk (100 IPs/req)
  • 3 keys · 5-day trial

Business

$79 /month

Sanctions and full intelligence.

  • 500,000 lookups/mo
  • 200 req/min, bursts of 600
  • Everything in Pro
  • Sanctions + corruption index
  • Bulk (500 IPs) · 10 keys

Enterprise

$199 /month

High-volume with dedicated support.

  • 2,000,000 lookups/mo
  • 500 req/min, bursts of 1,500
  • Everything in Business
  • Bulk (1,000 IPs/req)
  • 25 API keys
  • Dedicated support

Why My IP Help

Threat detection at $29 — others charge $99+
Sanctions data no one else offers
Free plan with real data to build and test against
HTTPS on all plans including Free

Annual billing saves 2 months: Pro $290/yr, Business $790/yr, Enterprise $1,990/yr. Manage subscription

Rate Limits

Each API key has two limits: a request rate with room for short bursts, and a monthly lookup quota.

Request rate. Each key can send a burst of requests at once, then its plan's rate per minute on average: a bucket that holds the burst and refills at the rate. A bulk request is one request. After a quiet spell the full burst is available again.

Plan Burst Then, per minute IPs per bulk request
Starter 30 10 20
Pro 180 60 100
Business 600 200 500
Enterprise 1,500 500 1,000

Over the rate you get 429 RATE_LIMITED with a Retry-After header: the seconds until the next request is allowed. Every response carries the burst headers:

Header Description
X-Burst-Limit Requests the key can send at once (the burst)
X-Burst-Remaining Requests that can be sent right now
X-Burst-Refill Requests added back per minute (the plan's rate)
Retry-After Seconds until the next request is allowed (only on 429 RATE_LIMITED)

Monthly quota. Single lookups and each bulk IP that returns data count toward the plan's monthly lookups. The lookup responses carry the quota headers:

Header Description
X-RateLimit-Limit Lookups per month on your plan
X-RateLimit-Remaining Lookups left this month, after this request
X-RateLimit-Reset When the lookup month ends (Unix time)

When your monthly lookups are used up (or a bulk request needs more than you have left), you get 429 QUOTA_EXCEEDED with an upgrade link; X-RateLimit-Reset says when the quota starts again.

Error Codes

All errors return a consistent JSON format:

{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable description."
  }
}
HTTP Code Description
401 API_KEY_MISSING No key sent (X-API-Key or Authorization: Bearer)
400 API_KEY_CONFLICT X-API-Key and Authorization: Bearer carry different keys
401 API_KEY_INVALID Key not found or revoked/expired
403 ACCOUNT_BLOCKED The key's account is blocked
403 IP_NOT_ALLOWED Request IP not in key's allowlist
403 PLAN_REQUIRED Endpoint requires a higher plan
403 BULK_NOT_ALLOWED Bulk not available on your plan
400 INVALID_IP Invalid IP address format
400 INVALID_ASN Not an AS number (send AS13335 or 13335)
404 ASN_NOT_FOUND No announced IP ranges for that AS number
404 IP_NOT_FOUND No geolocation data for this IP
422 PRIVATE_IP Private/reserved IP not supported
422 BULK_LIMIT_EXCEEDED Too many IPs in bulk request
429 QUOTA_EXCEEDED Monthly lookup limit reached
429 RATE_LIMITED Burst used up: retry after the Retry-After seconds
503 DATABASE_NOT_FOUND GeoIP database unavailable

Code Examples

# Single IP lookup
curl -H "X-API-Key: mih_live_YOUR_KEY" \
  "https://www.myiphelp.com/api/v1/ipdata/lookup/8.8.8.8"

# Lookup your own IP
curl -H "X-API-Key: mih_live_YOUR_KEY" \
  "https://www.myiphelp.com/api/v1/ipdata/lookup/me"

# Bulk lookup
curl -X POST -H "X-API-Key: mih_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"ips": ["8.8.8.8", "1.1.1.1"]}' \
  "https://www.myiphelp.com/api/v1/ipdata/lookup/bulk"

# Check usage
curl -H "X-API-Key: mih_live_YOUR_KEY" \
  "https://www.myiphelp.com/api/v1/ipdata/usage"
import requests

API_KEY = "mih_live_YOUR_KEY"
BASE = "https://www.myiphelp.com/api/v1/ipdata"
headers = {"X-API-Key": API_KEY}

# Single IP lookup
resp = requests.get(f"{BASE}/lookup/8.8.8.8", headers=headers)
data = resp.json()
print(data["data"]["country"])  # "United States"

# Bulk lookup
resp = requests.post(
    f"{BASE}/lookup/bulk",
    headers=headers,
    json={"ips": ["8.8.8.8", "1.1.1.1"]}
)

# Handle rate limits
if resp.status_code == 429:
    retry_after = int(resp.headers.get("Retry-After", 60))
    print(f"Rate limited. Retry in {retry_after}s")
const API_KEY = "mih_live_YOUR_KEY";
const BASE = "https://www.myiphelp.com/api/v1/ipdata";

// Single IP lookup
const resp = await fetch(`${BASE}/lookup/8.8.8.8`, {
  headers: { "X-API-Key": API_KEY }
});
const { data } = await resp.json();
console.log(data.country); // "United States"

// Bulk lookup
const bulk = await fetch(`${BASE}/lookup/bulk`, {
  method: "POST",
  headers: {
    "X-API-Key": API_KEY,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({ ips: ["8.8.8.8", "1.1.1.1"] })
});

// Check remaining quota
console.log(resp.headers.get("X-RateLimit-Remaining"));
<?php
$apiKey = "mih_live_YOUR_KEY";
$base = "https://www.myiphelp.com/api/v1/ipdata";

// Single IP lookup
$ch = curl_init("$base/lookup/8.8.8.8");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ["X-API-Key: $apiKey"],
]);
$response = json_decode(curl_exec($ch), true);
curl_close($ch);

echo $response["data"]["country"]; // "United States"

// Using Laravel HTTP client
$response = Http::withHeaders([
    'X-API-Key' => $apiKey,
])->get("$base/lookup/8.8.8.8");

$data = $response->json('data');
package main

import (
    "encoding/json"
    "fmt"
    "net/http"
)

func main() {
    apiKey := "mih_live_YOUR_KEY"
    base := "https://www.myiphelp.com/api/v1/ipdata"

    req, _ := http.NewRequest("GET", base+"/lookup/8.8.8.8", nil)
    req.Header.Set("X-API-Key", apiKey)

    resp, err := http.DefaultClient.Do(req)
    if err != nil {
        panic(err)
    }
    defer resp.Body.Close()

    var result struct {
        Success bool `json:"success"`
        Data    struct {
            Country string `json:"country"`
            City    string `json:"city"`
        } `json:"data"`
    }
    json.NewDecoder(resp.Body).Decode(&result)
    fmt.Println(result.Data.Country) // "United States"
}