Skip to content
VPNDetection

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

Node.js
npm install vpndetection

For 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:

Node.js
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);  // SE

Create 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:

bash
export VPNDETECTION_API_KEY="YOUR_API_KEY"
Node.js
const client = new VPNDetection({ apiKey: process.env.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_bogon set to true.
  • Retries. A failed connection, a server error or a 429 that carries Retry-After is retried. A 429 without Retry-After is 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:

Node.js
import { VPNDetection, VPNDetectionError } from 'vpndetection';

try {
    const result = await client.lookup(ip);
} catch (err) {
    if (err instanceof VPNDetectionError) {
        console.error(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:

Node.js
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 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: