Skip to content
VPNDetection

Quickstart

Make your first VPNDetection API request with curl, read what it says about an IP address, then add an API key and see what it changes.

This quickstart takes about two minutes. You look up an IP address without an account, learn what each part of the answer means, and then authenticate with an API key.

Before you begin

You need a terminal with curl. An account is only required for the last step, and it's free.

1. Look up an address

Send a GET request with the IP address as the whole path. This example uses an address that belongs to a VPN service:

bash
curl https://api.vpndetection.io/45.83.91.1

The API answers with a JSON object:

json
{
  "ip": "45.83.91.1",
  "is_bogon": false,
  "is_vpn": true,
  "is_relay": false,
  "is_tor": false,
  "is_bot": false,
  "is_anycast": false,
  "relay": {},
  "tor": {},
  "location": {
    "continent": "EU",
    "continent_name": "Europe",
    "country": "SE",
    "country_name": "Sweden",
    "timezone": "Europe/Stockholm",
    "currency_code": "SEK",
    "currency_name": "Krona",
    "currency_symbol": "SEK",
    "flag_emoji": "πŸ‡ΈπŸ‡ͺ",
    "flag_unicode": "U+1F1F8 U+1F1EA"
  },
  "asn": {
    "asn": 9009,
    "name": "M247 Europe SRL",
    "domain": "m247global.com",
    "type": "hosting",
    "prefix": "45.83.91.0/24",
    "country": "RO",
    "rpki_status": "not_found"
  },
  "hostname": "vlan3000.as06.stk1.se.m247.ro"
}

The path takes an IPv4 or an IPv6 address. To look up the address your own request comes from, call /myip instead:

bash
curl https://api.vpndetection.io/myip

2. Read the answer

Each is_ field is a yes-or-no classification, and the object beside it, such as relay for is_relay, holds the detail when the flag is true. An empty object means the flag is false.

FieldMeaning
is_vpnThe address is used by a commercial VPN service.
is_torThe address is a Tor exit node.
is_relayThe address belongs to a privacy relay, such as iCloud Private Relay, or an enterprise web gateway.
is_botThe address is used by a bot, such as a search engine's crawler, an uptime monitor or an internet scanner.
is_anycastThe address is announced from many locations at once, as public DNS resolvers are.
is_bogonThe address is private, reserved or unallocated, and should never appear on the public internet.
locationWhere the address is, to the country on the free plan, with its time zone and currency.
asnThe network that announces the address: its number, name, type and prefix.
hostnameThe address's reverse DNS name, when it has one.

The IP lookup reference documents every field the API can return, and what each one means.

3. Authenticate with an API key

Without a key, every request uses the free plan, which has no daily or monthly cap. An API key identifies your account, so you can see your usage in the console and receive the fields a paid plan adds.

  1. Create an account. The console creates your first API key for you.

  2. In the console, go to API > Keys and select Show key.

  3. Store the key in an environment variable, so it stays out of your code and your shell history:

    bash
    export VPNDETECTION_API_KEY="YOUR_API_KEY"
  4. Send the key in the Authorization header:

    bash
    curl -H "Authorization: Bearer $VPNDETECTION_API_KEY" https://api.vpndetection.io/45.83.91.1

A new account can try every field. With a paid plan, the answer also says whether the address is a hosting server, a CDN, or a residential, datacenter, mobile or public proxy, which VPN operates it and how confident the classification is, and the address's city, company and abuse contact. All paid plans return the same fields and differ only in how many lookups they include.

If the request fails

Most first requests that fail have one of three causes:

  • 401 Unauthorized means the key is unknown, revoked or expired. Copy an active key from API > Keys, or remove the Authorization header to use the free plan.
  • 403 Forbidden means the key lacks the IP lookup scope, is limited to other source addresses, or was sent over plain HTTP. Fix the key's settings under API > Keys, and send keys over HTTPS only.
  • 429 Too Many Requests means the request exceeded a rate limit. Wait for the number of seconds in the Retry-After header, then retry.

Troubleshooting covers these and other errors in detail.

Next steps

You have made your first request and authenticated it. Next, make the same call from your application with an official SDK, or protect a web app with middleware. Authentication describes the other two ways to send a key.