API Reference

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
Terms of Service
https://vpnblocker.net/terms-of-service/
Contact
[email protected]
Scheme
https
Formats
JSON, XML, HTML

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-KEY request 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.

query

Look up an IP address

GEThttps://api.vpnblocker.net/v2/{format}/{ip}/{key}
GEThttps://api.vpnblocker.net/v2/{format}/{ip}with header X-API-KEY: {key}

Parameters

NameInDescription
format *pathjson, xml or html. See Response formats.
ip *pathA valid IPv4 or IPv6 address you want to look up.
key *path or X-API-KEY headerYour 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

StatusDescription
200 OKLookup result. The fields depend on your key’s plan, see Response fields.
401 UnauthorizedMissing, invalid or inactive API key. See Errors.
406 Not AcceptableInvalid IP address.
429 Too Many RequestsMonthly limit reached. See Monthly limits.
501 Not ImplementedUnsupported format (anything other than json, xml or html).
500 Internal Server ErrorUnexpected error. Please try again, and contact us if it continues.

Response formats

FormatContent-TypeNotes
jsonapplication/jsonPretty-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.
xmltext/xmlThe 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.
htmltext/htmlA 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.

FieldTypePlansDescription
statusstringAllsuccess (errors use failed, see Errors).
packagestringAllYour key’s plan: Free, Basic, Professional, Business or Enterprise.
remaining_requestsintegerAllLookups left this month after this one. On paid plans it shows 0 while you use the 10% buffer.
ipaddressstringAllThe IP address you looked up.
host-ipbooleanAlltrue if the IP belongs to a hosting organization (a hosting provider, data center or VPN network), otherwise false.
categoriesarray of stringsAllWhat kind of address it is: any of vpn, proxy, tor, relay, hosting, always in that order. Empty when none apply. See Categories and confidence.
confidenceintegerAll0–99: how sure we are of this answer. See Confidence.
hostnamestring or nullProfessional, Business, EnterpriseThe IP’s reverse DNS name. If the IP has no reverse DNS name, this is the IP address itself.
orgstringAllThe organization that owns the IP’s network.
countryobjectProfessional, Business, Enterprisename and ISO 3166-1 code, each a string or null.
subdivisionobjectProfessional, Business, EnterpriseState, province or region: name and ISO 3166-2 code, each a string or null.
citystring or nullProfessional, Business, EnterpriseCity name.
postalstring or nullProfessional, Business, EnterprisePostal or ZIP code.
locationobjectProfessional, Business, EnterpriseApproximate 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:

ValueMeans
vpnA network run by a VPN provider.
proxyA 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.
torA Tor exit node: on the Tor Project’s list of exits now, or within the last 7 days. We refresh the list every hour.
relayAn 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.
hostingA 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-ip and categories answer different questions. host-ip is about the network an IP belongs to; tor is about the IP itself. So a Tor exit on a network that isn’t classed as hosting is host-ip: false with categories: ["tor"].
  • An IP can be in more than one category, for example ["tor", "hosting"] for a Tor exit in a data center.
  • host-ip can be true with an empty categories when 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.

ScoreTypical reason
95–99Confirmed 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.
90A network categorized by our machine learning models and verified, or a privacy-relay address seen in the last few days.
85Left the Tor exit list, dropped off a privacy-relay feed, or last confirmed as an open proxy, within the last day or so.
70–75A 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.
80Clean answer: nothing suggests the IP is a VPN, proxy, Tor exit, relay or hosting address.
60Clean 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:

GoalRule
Block VPNs, proxies and hosting (the classic check)host-ip is true
Also block Torhost-ip is true, or categories contains tor
Block only VPNs and Tor, allow other hostingcategories 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:

GoalRule
Only block when we’re sureany rule above, and confidence ≥ 90
Block when sure, challenge when unsureflagged with confidence ≥ 90: block. Flagged with lower confidence: show a captcha or ask for extra verification.
Only current Tor exitscategories contains tor and confidence ≥ 90
Recent Tor exits toocategories contains tor and confidence ≥ 70
Block VPNs even when less certain, but hosting only when surevpn, 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 answerscategories is empty, host-ip is false and confidence ≥ 80: allow with no extra checks
Be careful with little-known addressesa 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.

PlanMonthly limitRequests refused (429) afterFields
Free10,00010,000Basic
Basic250,000275,000Basic
Professional1,000,0001,100,000Professional
Business5,000,0005,500,000Professional
EnterpriseCustomCustom limit + bufferProfessional
  • 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-After header 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:

HeaderDescription
X-RateLimit-LimitYour key’s monthly limit, for example 10000.
X-RateLimit-RemainingLookups left this month, the same as remaining_requests.
X-RateLimit-ResetWhen usage resets, as a Unix timestamp: 00:00 UTC on the 1st of next month.
X-VPNBlocker-PlanYour key’s plan: free, basic, professional, business or enterprise.
Retry-After429 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.

StatusmsgWhen
401An API key is required. Create a free account and API key at https://dashboard.vpnblocker.net/signupNo key in the URL or the X-API-KEY header.
401Invalid API KeyThe key is malformed, doesn’t exist, or was revoked or regenerated.
401This API key is not active yet. Finish setting it up at https://dashboard.vpnblocker.netThe key’s first payment hasn’t gone through yet.
401Payment for this API key is overdue. Pay the open invoice at https://dashboard.vpnblocker.netA renewal payment failed and wasn’t paid in time.
401This API key is suspended. See https://dashboard.vpnblocker.net for details.The key has been suspended.
406Invalid IP AddressThe ip isn’t a valid IPv4 or IPv6 address.
429Monthly request limit reached. Upgrade your plan at https://dashboard.vpnblocker.netThe 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"
}