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:
curl https://api.vpndetection.io/45.83.91.1The API answers with a JSON object:
{
"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:
curl https://api.vpndetection.io/myip2. 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.
| Field | Meaning |
|---|---|
is_vpn | The address is used by a commercial VPN service. |
is_tor | The address is a Tor exit node. |
is_relay | The address belongs to a privacy relay, such as iCloud Private Relay, or an enterprise web gateway. |
is_bot | The address is used by a bot, such as a search engine's crawler, an uptime monitor or an internet scanner. |
is_anycast | The address is announced from many locations at once, as public DNS resolvers are. |
is_bogon | The address is private, reserved or unallocated, and should never appear on the public internet. |
location | Where the address is, to the country on the free plan, with its time zone and currency. |
asn | The network that announces the address: its number, name, type and prefix. |
hostname | The 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.
-
Create an account. The console creates your first API key for you.
-
In the console, go to API > Keys and select Show key.
-
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" -
Send the key in the
Authorizationheader: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 Unauthorizedmeans the key is unknown, revoked or expired. Copy an active key from API > Keys, or remove theAuthorizationheader to use the free plan.403 Forbiddenmeans 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 Requestsmeans the request exceeded a rate limit. Wait for the number of seconds in theRetry-Afterheader, 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.