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 |
Enter your API key above to send requests.
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
Enter your API key above to send requests.
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) |
Enter your API key above to send requests.
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
Enter your API key above to send requests.
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
Enter your API key above to send requests.
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
/mcpin 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>®</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
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
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"
}