Skip to content
VPNDetection

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.download scope.
  • An MMDB reader for your language, such as the maxminddb package for Python or maxmind for 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:

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

bash
vpndetection db download tor_ip_v1 --format mmdb tor_ip_v1.mmdb

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

Python
# 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

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

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:

bash
#!/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.