Use an SDK
Install an official VPNDetection client library, look up an IP address from your code, and authenticate with an API key read from the environment.
The official client libraries wrap the API with typed results, a built-in cache and automatic retries, so most integrations need only a few lines of code. This page installs a library, makes a lookup, adds your key, and explains how the libraries behave so you can rely on them in production.
Each library is open source, and its page under Programming SDKs documents everything it does. The libraries for Node.js, Python, Go, PHP, Ruby, .NET and Rust are shown here; libraries also exist for Java, Swift, Erlang, Perl and Zig.
1. Install the library
npm install vpndetectionpip install vpndetectiongo get github.com/vpndetection-io/sdk-go/v5composer require vpndetection/vpndetectiongem install vpndetectiondotnet add package VPNDetectioncargo add vpndetectionFor Java, add the Maven or Gradle coordinates from the Java page.
2. Look up an address
You can call the API without a key while you build. The client returns the same fields the API does, with names in your language's usual style, such as isVpn in Node.js and is_vpn in Python:
import { VPNDetection } from 'vpndetection';
const client = new VPNDetection();
const result = await client.lookup('45.83.91.1');
console.log(result.isVpn); // true
console.log(result.location?.country); // SEfrom vpndetection import VPNDetection
with VPNDetection() as client:
result = client.lookup("45.83.91.1")
print(result.is_vpn) # True
print(result.location.country) # SEclient, err := vpndetection.New()
if err != nil {
log.Fatal(err)
}
result, err := client.Lookup(ctx, "45.83.91.1")
if err != nil {
log.Fatal(err)
}
fmt.Println(result.IsVpn) // trueuse VPNDetection\Client;
$client = new Client();
$result = $client->lookup('45.83.91.1');
echo $result->isVpn ? 'yes' : 'no'; // yes
echo $result->location->country; // SErequire 'vpndetection'
client = VPNDetection::Client.new
result = client.lookup('45.83.91.1')
result.is_vpn # => true
result.location['country'] # => "SE"using VPNDetection;
using var client = new VpnDetectionClient();
var result = await client.LookupAsync("45.83.91.1");
Console.WriteLine(result.IsVpn); // True
Console.WriteLine(result.Location?.Country); // SEuse vpndetection::Client;
let client = Client::new()?;
let result = client.lookup("45.83.91.1").await?;
println!("{}", result.is_vpn); // trueCreate one client when your application starts and reuse it. It keeps a connection pool and a cache, so a new client for every request is slower and repeats lookups the cache would have answered.
3. Authenticate with an API key
To authenticate, pass your API key when you create the client. Read it from the environment rather than writing it in your code:
export VPNDETECTION_API_KEY="YOUR_API_KEY"const client = new VPNDetection({ apiKey: process.env.VPNDETECTION_API_KEY });import os
client = VPNDetection(os.environ["VPNDETECTION_API_KEY"])Each library's page shows how to pass a key in that language.
How the libraries behave
Every official library follows the same rules, so you can move between languages without relearning them:
- Caching. Each client caches answers by address, 10,000 entries for an hour by default. Errors are never cached. You can change both limits or turn the cache off.
- Private addresses. A private, reserved or documentation address is answered locally, without a request, with
is_bogonset totrue. - Retries. A failed connection, a server error or a
429that carriesRetry-Afteris retried. A429withoutRetry-Afteris not. - Timeouts. Each attempt is abandoned after 30 seconds by default. You can set a shorter limit for the client or for a single call.
Handle errors
When a lookup fails, the library raises an error that says what kind of failure it was and whether retrying can help:
import { VPNDetection, VPNDetectionError } from 'vpndetection';
try {
const result = await client.lookup(ip);
} catch (err) {
if (err instanceof VPNDetectionError) {
console.error(err.kind, err.retryable);
}
}from vpndetection import VPNDetectionError
try:
result = client.lookup(ip)
except VPNDetectionError as err:
print(err.kind, err.retryable)kind is one of bad_request, unauthorized, forbidden, rate_limited, quota_exceeded, server_error or network. Decide what a failure means for each place you look up addresses: a page view can usually continue, while a sign-up might wait or ask for more verification.
Look up many addresses at once
To check a list, use the batch method. Private addresses and cached answers are handled locally, and the rest go to the API in chunks of up to 1,000. The batch endpoint needs a paid plan:
const results = await client.lookupBatch(['45.83.91.1', '8.8.8.8']);
for (const [ip, result] of results) {
console.log(ip, result instanceof Error ? result.message : result.isVpn);
}results = client.lookup_batch(["45.83.91.1", "8.8.8.8"])
for ip, result in results.items():
print(ip, result if isinstance(result, Exception) else result.is_vpn)Results are keyed by address, so duplicates collapse into one entry, and an address that fails carries its own error without affecting the others.
Next steps
Your application can now look up addresses. Each library's page also documents its other features, such as your plan and usage, database downloads and sign-in with OAuth: