VPN Blocker API Reference
The VPN Blocker API tells you whether an IP address is a VPN, proxy, Tor exit, privacy relay or hosting address, how confident we are, and who owns its network, so you can keep fraud, abuse and ban evasion away from your services.
Each lookup finds the network an IP address belongs to and who owns it (its autonomous system, or ASN). If that owner is a hosting provider, data center or VPN network, the response says so in the host-ip field, along with the owner’s name in org.
Every response also says what kind of address it is in categories (vpn, proxy, tor, relay or hosting), checked against our network list, the Tor Project’s list of exit nodes, public open-proxy lists we independently verify, and privacy-relay feeds such as Apple iCloud Private Relay, and how sure we are in confidence (0–99). See Categories and confidence.
API endpoint
https://api.vpnblocker.net/v2
API keys
Every request needs an API key. Create an account to get a free key with 10,000 lookups a month, and manage your keys, plans and usage in the dashboard.
Keys start with vpb_ followed by 32 letters and numbers. Each key has its own plan and monthly limit. Keep your key secret: anyone who has it can use your lookups. If a key leaks, regenerate it in the dashboard.
Send the key in one of two ways:
- as the last part of the URL:
/v2/json/8.8.8.8/vpb_…, or - in an
X-API-KEYrequest header, and leave it out of the URL. This keeps the key out of server logs and browser history.
HTTPS (SSL)
The API is served over HTTPS on every plan, including Free. Always use https://api.vpnblocker.net so your API key and lookups are encrypted in transit.
Look up an IP address
X-API-KEY: {key}Parameters
| Name | In | Description |
|---|---|---|
format * | path | json, xml or html. See Response formats. |
ip * | path | A valid IPv4 or IPv6 address you want to look up. |
key * | path or X-API-KEY header | Your API key. If both are sent, the key in the URL is used. |
Example requests
curl https://api.vpnblocker.net/v2/json/8.8.8.8/vpb_YOUR_API_KEY
curl -H "X-API-KEY: vpb_YOUR_API_KEY" https://api.vpnblocker.net/v2/json/8.8.8.8
Responses
| Status | Description |
|---|---|
| 200 OK | Lookup result. The fields depend on your key’s plan, see Response fields. |
| 401 Unauthorized | Missing, invalid or inactive API key. See Errors. |
| 406 Not Acceptable | Invalid IP address. |
| 429 Too Many Requests | Monthly limit reached. See Monthly limits. |
| 501 Not Implemented | Unsupported format (anything other than json, xml or html). |
| 500 Internal Server Error | Unexpected error. Please try again, and contact us if it continues. |
Response formats
| Format | Content-Type | Notes |
|---|---|---|
json | application/json | Pretty-printed JSON object. host-ip is true or false; categories is an array of strings ([] when there are none); fields with no data are null. |
xml | text/xml | The same fields as child elements of <root>, on one line. host-ip is 1 for true and an empty element (<host-ip/>) for false. categories has one <category> child per category, or is empty (<categories/>). Fields with no data are empty elements. |
html | text/html | A web page showing the result, including categories and confidence, for people viewing a lookup in a browser. Use json or xml in your code. |
XML example (200 OK) · Free key · GET /v2/xml/70.68.0.1
<?xml version="1.0"?>
<root><status>success</status><package>Free</package><remaining_requests>9876</remaining_requests><ipaddress>70.68.0.1</ipaddress><host-ip/><categories/><confidence>80</confidence><org>Shaw Communications</org></root>
With categories, for example a Tor exit in a data center:
<host-ip>1</host-ip><categories><category>tor</category><category>hosting</category></categories><confidence>99</confidence>
Response fields
Free and Basic keys get the Basic fields. Professional, Business and Enterprise keys get the Professional fields: the Basic fields plus hostname and geolocation. Fields always appear in the order below.
| Field | Type | Plans | Description |
|---|---|---|---|
status | string | All | success (errors use failed, see Errors). |
package | string | All | Your key’s plan: Free, Basic, Professional, Business or Enterprise. |
remaining_requests | integer | All | Lookups left this month after this one. On paid plans it shows 0 while you use the 10% buffer. |
ipaddress | string | All | The IP address you looked up. |
host-ip | boolean | All | true if the IP belongs to a hosting organization (a hosting provider, data center or VPN network), otherwise false. |
categories | array of strings | All | What kind of address it is: any of vpn, proxy, tor, relay, hosting, always in that order. Empty when none apply. See Categories and confidence. |
confidence | integer | All | 0–99: how sure we are of this answer. See Confidence. |
hostname | string or null | Professional, Business, Enterprise | The IP’s reverse DNS name. If the IP has no reverse DNS name, this is the IP address itself. |
org | string | All | The organization that owns the IP’s network. |
country | object | Professional, Business, Enterprise | name and ISO 3166-1 code, each a string or null. |
subdivision | object | Professional, Business, Enterprise | State, province or region: name and ISO 3166-2 code, each a string or null. |
city | string or null | Professional, Business, Enterprise | City name. |
postal | string or null | Professional, Business, Enterprise | Postal or ZIP code. |
location | object | Professional, Business, Enterprise | Approximate lat and long. Both are 0 if the location is unknown. |
Geolocation is approximate. Many fields can be null, for example for data center addresses.
Examples by plan
Free (200 OK) · GET /v2/json/159.203.0.1
{
"status": "success",
"package": "Free",
"remaining_requests": 9876,
"ipaddress": "159.203.0.1",
"host-ip": true,
"categories": ["hosting"],
"confidence": 90,
"org": "DigitalOcean, LLC"
}
Basic (200 OK) · GET /v2/json/70.68.0.1
{
"status": "success",
"package": "Basic",
"remaining_requests": 249120,
"ipaddress": "70.68.0.1",
"host-ip": false,
"categories": [],
"confidence": 80,
"org": "Shaw Communications"
}
Professional, Business and Enterprise (200 OK) · GET /v2/json/116.203.10.10
Business and Enterprise responses are the same, with package set to Business or Enterprise.
{
"status": "success",
"package": "Professional",
"remaining_requests": 987654,
"ipaddress": "116.203.10.10",
"host-ip": true,
"categories": ["hosting"],
"confidence": 90,
"hostname": "static.10.10.203.116.clients.your-server.de",
"org": "Hetzner Online GmbH",
"country": {
"name": "Germany",
"code": "DE"
},
"subdivision": {
"name": "Bavaria",
"code": "BY"
},
"city": "Nuremberg",
"postal": "90403",
"location": {
"lat": 49.4527,
"long": 11.0783
}
}
A Tor exit on a network that isn’t classed as hosting (200 OK) · Basic key · GET /v2/json/185.220.101.1
tor never changes host-ip: a Tor exit on a network that isn’t classed as hosting is "host-ip": false with "categories": ["tor"].
{
"status": "success",
"package": "Basic",
"remaining_requests": 249119,
"ipaddress": "185.220.101.1",
"host-ip": false,
"categories": ["tor"],
"confidence": 98,
"org": "Stiftung Erneuerbare Freiheit"
}
Categories and confidence
categories says what kind of address an IP is. It can hold any of these values, always in this order and never repeated:
| Value | Means |
|---|---|
vpn | A network run by a VPN provider. |
proxy | A network that sells or runs proxies, or an IP on a public open-proxy list — with higher confidence once we’ve independently confirmed it relays traffic. |
tor | A Tor exit node: on the Tor Project’s list of exits now, or within the last 7 days. We refresh the list every hour. |
relay | An egress address of a privacy relay such as Apple iCloud Private Relay or Chrome’s prefetch proxy. These carry ordinary people’s traffic, so most sites allow them. Like tor, it never changes host-ip. |
hosting | A hosting provider, data center or cloud network. |
- More about each: VPN detection, proxy detection, Tor detection and hosting detection.
- New values may be added later. Ignore values you don’t recognize rather than treating them as an error.
host-ipandcategoriesanswer different questions.host-ipis about the network an IP belongs to;toris about the IP itself. So a Tor exit on a network that isn’t classed as hosting ishost-ip: falsewithcategories: ["tor"].- An IP can be in more than one category, for example
["tor", "hosting"]for a Tor exit in a data center. host-ipcan betruewith an emptycategorieswhen we know an address isn’t a regular user’s but haven’t put it in a category.
Confidence
confidence (0–99) is how sure we are of the whole answer: of the categories when there are any (or host-ip is true), otherwise that the IP is clean. It’s a score from fixed rules, not a measured probability, so compare it with a threshold rather than reading it as a percentage.
| Score | Typical reason |
|---|---|
| 95–99 | Confirmed for this IP or range: a current Tor exit, an open proxy we’ve verified, or a privacy-relay address in the feed now. 99 when two independent sources agree. |
| 90 | A network categorized by our machine learning models and verified, or a privacy-relay address seen in the last few days. |
| 85 | Left the Tor exit list, dropped off a privacy-relay feed, or last confirmed as an open proxy, within the last day or so. |
| 70–75 | A network categorized by our machine learning models and not verified yet; an IP on a public open-proxy list we haven’t confirmed yet; or a Tor exit or privacy-relay address seen within the last 7 days. |
| 80 | Clean answer: nothing suggests the IP is a VPN, proxy, Tor exit, relay or hosting address. |
| 60 | Clean answer for an address no network announces, so there’s little to go on. |
When a customer has reported that an answer is wrong and we haven’t reviewed the report yet, confidence drops by 15 (never below 50) until we do. See Reporting a wrong result.
Deciding what to block
Pick the rule that fits how strict you want to be. For example:
| Goal | Rule |
|---|---|
| Block VPNs, proxies and hosting (the classic check) | host-ip is true |
| Also block Tor | host-ip is true, or categories contains tor |
| Block only VPNs and Tor, allow other hosting | categories contains vpn or tor |
| Allow privacy relays (Apple, Chrome) | treat relay as clean unless it appears alongside another category; it carries ordinary users |
Using confidence
confidence lets you decide how sure we need to be before you act. These rules combine it with the checks above:
| Goal | Rule |
|---|---|
| Only block when we’re sure | any rule above, and confidence ≥ 90 |
| Block when sure, challenge when unsure | flagged with confidence ≥ 90: block. Flagged with lower confidence: show a captcha or ask for extra verification. |
| Only current Tor exits | categories contains tor and confidence ≥ 90 |
| Recent Tor exits too | categories contains tor and confidence ≥ 70 |
| Block VPNs even when less certain, but hosting only when sure | vpn, proxy or tor with confidence ≥ 70, or hosting with confidence ≥ 90. Hosting needs a higher score because real people sometimes browse from cloud and office networks. |
| Trust clean answers | categories is empty, host-ip is false and confidence ≥ 80: allow with no extra checks |
| Be careful with little-known addresses | a clean answer with confidence below 80: allow, but consider extra verification for sensitive actions such as payments |
When someone reports an answer as wrong, its confidence drops until the report is reviewed, so a threshold of 90 automatically stops blocking an IP that’s under review.
Example: block, challenge or allow
This turns a lookup into one of three actions. Change the settings at the top to fit your site rather than adding more rules.
JavaScript
// Tune these to fit your site.
const BLOCK_CATEGORIES = ['vpn', 'proxy', 'tor']; // add 'hosting' to block data centers too
const ALLOW_CATEGORIES = ['relay']; // privacy relays (e.g. Apple Private Relay) carry ordinary users; don't act on them alone
const BLOCK_AT = 90; // block these categories at or above this confidence
const CHALLENGE_AT = 70; // challenge anything flagged at or above this confidence
const CLEAN_TRUST_AT = 80; // clean answers below this are little-known addresses
// r is the parsed JSON response from /v2/json/{ip}.
// Pass sensitive = true for actions such as payments to also challenge little-known addresses.
function decide(r, sensitive = false) {
const cats = r.categories.filter((c) => !ALLOW_CATEGORIES.includes(c));
const flagged = r['host-ip'] === true || cats.length > 0;
const blockable = cats.some((c) => BLOCK_CATEGORIES.includes(c));
if (blockable && r.confidence >= BLOCK_AT) return 'block';
if (flagged && r.confidence >= CHALLENGE_AT) return 'challenge';
if (sensitive && !flagged && r.confidence < CLEAN_TRUST_AT) return 'challenge';
return 'allow';
}
PHP
// Tune these to fit your site.
const BLOCK_CATEGORIES = ['vpn', 'proxy', 'tor']; // add 'hosting' to block data centers too
const ALLOW_CATEGORIES = ['relay']; // privacy relays (e.g. Apple Private Relay) carry ordinary users; don't act on them alone
const BLOCK_AT = 90; // block these categories at or above this confidence
const CHALLENGE_AT = 70; // challenge anything flagged at or above this confidence
const CLEAN_TRUST_AT = 80; // clean answers below this are little-known addresses
// $r is the decoded JSON response from /v2/json/{ip}.
// Pass $sensitive = true for actions such as payments to also challenge little-known addresses.
function decide(array $r, bool $sensitive = false): string
{
$cats = array_diff($r['categories'], ALLOW_CATEGORIES);
$flagged = $r['host-ip'] === true || count($cats) > 0;
$blockable = (bool) array_intersect($cats, BLOCK_CATEGORIES);
if ($blockable && $r['confidence'] >= BLOCK_AT) return 'block';
if ($flagged && $r['confidence'] >= CHALLENGE_AT) return 'challenge';
if ($sensitive && !$flagged && $r['confidence'] < CLEAN_TRUST_AT) return 'challenge';
return 'allow';
}
Python
# Tune these to fit your site.
BLOCK_CATEGORIES = {"vpn", "proxy", "tor"} # add "hosting" to block data centers too
ALLOW_CATEGORIES = {"relay"} # privacy relays (e.g. Apple Private Relay) carry ordinary users; don't act on them alone
BLOCK_AT = 90 # block these categories at or above this confidence
CHALLENGE_AT = 70 # challenge anything flagged at or above this confidence
CLEAN_TRUST_AT = 80 # clean answers below this are little-known addresses
# r is the parsed JSON response from /v2/json/{ip}.
# Pass sensitive=True for actions such as payments to also challenge little-known addresses.
def decide(r: dict, sensitive: bool = False) -> str:
cats = set(r["categories"]) - ALLOW_CATEGORIES
flagged = r["host-ip"] is True or len(cats) > 0
blockable = bool(BLOCK_CATEGORIES.intersection(cats))
if blockable and r["confidence"] >= BLOCK_AT:
return "block"
if flagged and r["confidence"] >= CHALLENGE_AT:
return "challenge"
if sensitive and not flagged and r["confidence"] < CLEAN_TRUST_AT:
return "challenge"
return "allow"
Hosting addresses end up as challenge rather than block, because real people sometimes browse from cloud and office networks; add hosting to BLOCK_CATEGORIES to block them too. Privacy relays (relay) are allowed outright, since they carry ordinary Apple and Chrome users on their own devices — move relay out of ALLOW_CATEGORIES (and into BLOCK_CATEGORIES) if you’d rather challenge or block them. Little-known addresses are only challenged when you pass sensitive, so ordinary sign-ups and page views aren’t slowed down.
Code examples
Each example looks up an IP, then blocks it if it’s a hosting, VPN or proxy address or a Tor exit. Keep your key in an environment variable, not in your code.
curl
curl -s -H "X-API-KEY: $VPNBLOCKER_KEY" https://api.vpnblocker.net/v2/json/185.220.101.1
PHP
<?php
function shouldBlock(string $ip): bool
{
$ch = curl_init('https://api.vpnblocker.net/v2/json/' . rawurlencode($ip));
curl_setopt_array($ch, [
CURLOPT_HTTPHEADER => ['X-API-KEY: ' . getenv('VPNBLOCKER_KEY')],
CURLOPT_RETURNTRANSFER => true,
CURLOPT_TIMEOUT => 3,
]);
$body = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
curl_close($ch);
if ($body === false || $status !== 200) {
return false; // fail open: don't block users if the lookup fails
}
$r = json_decode($body, true);
return $r['host-ip'] === true || in_array('tor', $r['categories'] ?? [], true);
}
JavaScript (Node.js 18+, or any runtime with fetch)
async function shouldBlock(ip) {
try {
const res = await fetch(`https://api.vpnblocker.net/v2/json/${encodeURIComponent(ip)}`, {
headers: { 'X-API-KEY': process.env.VPNBLOCKER_KEY },
signal: AbortSignal.timeout(3000),
});
if (!res.ok) return false; // fail open: don't block users if the lookup fails
const r = await res.json();
return r['host-ip'] === true || (r.categories ?? []).includes('tor');
} catch {
return false;
}
}
Python (requests)
import os
import requests
def should_block(ip: str) -> bool:
try:
res = requests.get(
f"https://api.vpnblocker.net/v2/json/{ip}",
headers={"X-API-KEY": os.environ["VPNBLOCKER_KEY"]},
timeout=3,
)
except requests.RequestException:
return False # fail open: don't block users if the lookup fails
if res.status_code != 200:
return False
r = res.json()
return r["host-ip"] is True or "tor" in r.get("categories", [])
Cache results on your side (see Monthly limits), and decide what your code should do when a lookup fails. The examples above let the user through.
For complete walkthroughs, see the guides for PHP, Node.js, Python, and game servers and Discord.
Reporting a wrong result
If you think we have an IP wrong, either flagged when it shouldn’t be or missed when it should be flagged, report it under Report an IP in the dashboard. Reports are free on every plan and don’t use up lookups.
- While a report is open, lookups for that IP (or its network) carry a lower
confidence, so you can treat them with care. - We review every report. When we fix a result, the fix applies to every customer straight away, and we email you.
- You can follow your reports and our replies in the dashboard.
Monthly limits
Each API key has its own monthly limit. Usage resets at 00:00 UTC on the 1st of every month.
| Plan | Monthly limit | Requests refused (429) after | Fields |
|---|---|---|---|
| Free | 10,000 | 10,000 | Basic |
| Basic | 250,000 | 275,000 | Basic |
| Professional | 1,000,000 | 1,100,000 | Professional |
| Business | 5,000,000 | 5,500,000 | Professional |
| Enterprise | Custom | Custom limit + buffer | Professional |
- Paid plans keep working up to 110% of their limit (a 10% buffer). The Free plan stops at 100%.
- After that, lookups return 429 Too Many Requests with a
Retry-Afterheader until the monthly reset. - Only successful lookups are counted. Requests refused with an error (401, 406 or 429) don’t use up your limit.
- The dashboard shows your usage and emails you alerts as you approach your limit. You can upgrade at any time.
- Caching results on your side saves lookups. Network results rarely change, but Tor exits change every hour: if you block Tor, cache for about an hour, and never longer than a day.
429 example
HTTP/2 429
content-type: application/json
x-ratelimit-limit: 10000
x-ratelimit-remaining: 0
x-ratelimit-reset: 1793491200
x-vpnblocker-plan: free
retry-after: 1356000
{
"status": "failed",
"msg": "Monthly request limit reached. Upgrade your plan at https:\/\/dashboard.vpnblocker.net"
}
Rate limit headers
Every successful lookup and every 429 response has these headers:
| Header | Description |
|---|---|
X-RateLimit-Limit | Your key’s monthly limit, for example 10000. |
X-RateLimit-Remaining | Lookups left this month, the same as remaining_requests. |
X-RateLimit-Reset | When usage resets, as a Unix timestamp: 00:00 UTC on the 1st of next month. |
X-VPNBlocker-Plan | Your key’s plan: free, basic, professional, business or enterprise. |
Retry-After | 429 responses only: seconds until the monthly reset. |
Example (Free key)
HTTP/2 200
content-type: application/json
x-ratelimit-limit: 10000
x-ratelimit-remaining: 9876
x-ratelimit-reset: 1793491200
x-vpnblocker-plan: free
Errors
Errors use the same format you asked for, with status set to failed and the reason in msg.
| Status | msg | When |
|---|---|---|
| 401 | An API key is required. Create a free account and API key at https://dashboard.vpnblocker.net/signup | No key in the URL or the X-API-KEY header. |
| 401 | Invalid API Key | The key is malformed, doesn’t exist, or was revoked or regenerated. |
| 401 | This API key is not active yet. Finish setting it up at https://dashboard.vpnblocker.net | The key’s first payment hasn’t gone through yet. |
| 401 | Payment for this API key is overdue. Pay the open invoice at https://dashboard.vpnblocker.net | A renewal payment failed and wasn’t paid in time. |
| 401 | This API key is suspended. See https://dashboard.vpnblocker.net for details. | The key has been suspended. |
| 406 | Invalid IP Address | The ip isn’t a valid IPv4 or IPv6 address. |
| 429 | Monthly request limit reached. Upgrade your plan at https://dashboard.vpnblocker.net | The key is over its monthly limit. See Monthly limits. |
Examples
401 · GET /v2/json/8.8.8.8/vpb_…
{
"status": "failed",
"msg": "Invalid API Key"
}
406 · GET /v2/json/not-an-ip/vpb_…
{
"status": "failed",
"msg": "Invalid IP Address"
}
An unsupported format or an unknown path returns a short JSON body instead, for example 501 · GET /v2/yaml/8.8.8.8:
{
"message": "501 Not Implemented"
}