Use the databases
Download a VPNDetection database with your API key, look IP addresses up on your own servers, and keep the file current as new builds publish.
A database lets you look addresses up on your own servers, with no request to the API for each one. This page downloads a database, looks an address up in it, and sets up a refresh so the file stays current.
The examples use Tor IP, which every account may download for free, so you can follow along before you license anything. Every other database downloads and reads the same way.
Before you begin
- An account and its API key. The key the console creates for you can download; a key you create yourself needs the
db.downloadscope. - An MMDB reader for your language, such as the
maxminddbpackage for Python ormaxmindfor Node.js. CSV files need no special reader.
1. Choose a format
Every database is published in two formats:
- MMDB is a binary format built for lookups. A reader opens the file and answers an address in memory, in microseconds. Choose it to look addresses up from an application.
- Gzipped CSV (
csvgz) holds one IP range per row. Choose it to load the data into a database or a data warehouse, or to inspect it with your own tools.
Formats describes both in detail.
2. Download the file
Request the database by its ID and format. The API answers with a redirect to the file, so tell curl to follow it with -L:
export VPNDETECTION_API_KEY="YOUR_API_KEY"
curl -L -o tor_ip_v1.mmdb \
"https://api.vpndetection.io/api/v1/database/download?id=tor_ip_v1&format=mmdb&apikey=$VPNDETECTION_API_KEY"The CLI downloads the same file with one command, after vpndetection login:
vpndetection db download tor_ip_v1 --format mmdb tor_ip_v1.mmdbEach dataset's page in the Database Reference gives its ID, its columns and a sample.
3. Look up an address
The record for an address holds the columns its dataset page lists. An address that isn't in the dataset returns nothing:
# pip install maxminddb
import maxminddb
with maxminddb.open_database("tor_ip_v1.mmdb") as reader:
print(reader.get("185.220.101.1")) # {'confidence': 'high', 'last_seen': '2026-11-20'}
print(reader.get("8.8.8.8")) # None: not a Tor exit// npm install maxmind
import maxmind from 'maxmind';
const tor = await maxmind.open('tor_ip_v1.mmdb');
console.log(tor.get('185.220.101.1')); // { confidence: 'high', last_seen: '2026-11-20' }
console.log(tor.get('8.8.8.8')); // null: not a Tor exit// go get github.com/oschwald/maxminddb-golang/v2
db, err := maxminddb.Open("tor_ip_v1.mmdb")
if err != nil {
log.Fatal(err)
}
defer db.Close()
var record struct {
Confidence string `maxminddb:"confidence"`
LastSeen string `maxminddb:"last_seen"`
}
result := db.Lookup(netip.MustParseAddr("185.220.101.1"))
if err := result.Decode(&record); err != nil {
log.Fatal(err)
}
fmt.Println(result.Found(), record.Confidence) // true highOpen the file once when your application starts and keep it open. Reopening it for every lookup reads it from disk each time.
4. Keep the file current
Tor IP, like most datasets, is rebuilt every day, so a copy you downloaded last week no longer includes the exits that appeared since. Each dataset's page gives its update frequency. You can fetch new builds on a schedule, or have them delivered:
- On a schedule: call Metadata, whose
updatedfield gives the date of the current build, and download only when it's newer than your copy. Verify each download against Checksums. - Delivered: a webhook calls your endpoint when a new build publishes, or delivery writes each build to Amazon S3, Google Cloud Storage, Azure Blob Storage or SFTP.
This script downloads the current build, checks it against its published SHA-256 digest, and only then replaces your copy, so a failed or partial download never reaches your application:
#!/usr/bin/env bash
set -euo pipefail
id=tor_ip_v1
base=https://api.vpndetection.io/api/v1/database
key=$VPNDETECTION_API_KEY
curl -fsSL -o "$id.mmdb.new" "$base/download?id=$id&format=mmdb&apikey=$key"
want=$(curl -fsS "$base/checksum?id=$id&format=mmdb&apikey=$key" | jq -r .checksums.sha256)
echo "$want $id.mmdb.new" | sha256sum -c -
mv "$id.mmdb.new" "$id.mmdb"Run it once a day, for example from cron, and reopen the file in your application after it changes.
Next steps
You can now answer lookups on your own servers. Tor IP, Relay IP and Relay Provider are free for every account; the other databases are licensed, so contact us about the ones you need. To decide which lookups belong in a database and which in the API, see API or database.