Bulk Exports

For high-volume use cases (>1 M lookups/day) or warehouse loads, pull the full dataset on a schedule instead of hammering the API.

Format choice

Format	Best for	Tier required
CSV	Spreadsheets, ad-hoc analysis, simple ETL	Pro
MMDB	Sub-ms local lookups in production code (Python, Go, Node, Java)	Business
Parquet	Snowflake / BigQuery / Athena / Spark loads	Business

MMDB is what most production fraud pipelines use — load once into memory, look up at the speed of a hash table, refresh hourly.

Scheduling

Refresh once an hour at most. The dataset rolls over with new observations roughly every 60 minutes. Pulling more often wastes bandwidth. The MMDB ships as two files. artifact=ranges (the default) is wxa_vpn.mmdb — the VPN / proxy / hosting / CDN / Tor / relay CIDR-ranges layer. artifact=points is wxa_vpn-points.mmdb — the residential-proxy per-IP (/32) layer. Download both for full coverage:

# crontab — hourly refresh of BOTH MMDB layers
0 * * * * curl -fsS \
  "https://vpn-proxy-detection.whoisxmlapi.com/api/v1/export/mmdb?artifact=ranges&apiKey=$WXA_API_KEY" \
  -o /var/lib/wxa-vpn/wxa_vpn.mmdb.tmp \
  && mv /var/lib/wxa-vpn/wxa_vpn.mmdb.tmp /var/lib/wxa-vpn/wxa_vpn.mmdb
5 * * * * curl -fsS \
  "https://vpn-proxy-detection.whoisxmlapi.com/api/v1/export/mmdb?artifact=points&apiKey=$WXA_API_KEY" \
  -o /var/lib/wxa-vpn/wxa_vpn-points.mmdb.tmp \
  && mv /var/lib/wxa-vpn/wxa_vpn-points.mmdb.tmp /var/lib/wxa-vpn/wxa_vpn-points.mmdb

Atomic rename pattern (tmp → final) so readers never see a partial file.

MMDB lookup (Python)

For a complete verdict, check the points DB first (an exact /32 residential-proxy detection wins), then fall back to the ranges DB:

import maxminddb

points = maxminddb.open_database("/var/lib/wxa-vpn/wxa_vpn-points.mmdb")
ranges = maxminddb.open_database("/var/lib/wxa-vpn/wxa_vpn.mmdb")

def lookup(ip):
    return points.get(ip) or ranges.get(ip)

data = lookup("1.1.1.1")
# {"classification": "cdn", "provider": "Cloudflare", ...}

Both IPv4 and IPv6 keys are accepted, but Phase 1 coverage is IPv4-first — an IPv6 lookup returns an empty result, not an error (broader IPv6 coverage is on the roadmap). Empty/None also means an unknown IP. wxa_vpn.mmdb alone does NOT include the ~34M residential-proxy points — pull wxa_vpn-points.mmdb for that layer.

Parquet to Snowflake

COPY INTO wxa_vpn_intel
FROM @my_s3_stage/wxa-vpn.parquet
FILE_FORMAT = (TYPE = PARQUET);

We don’t host the file in S3 — you download it via the API, drop it in your stage, then COPY. Schema is documented at docs/data-dictionary.md.

Concurrency

Bulk downloads count against a separate bulk concurrent limit (1 for Starter, 2 for Pro, 5 for Business, negotiated for Enterprise). Don’t parallelize a single export — start one, wait for completion, start the next.

File size

Format	Approx size (full dataset)
CSV	~3 GB compressed (gzip), ~15 GB uncompressed
MMDB — `wxa_vpn.mmdb` (ranges)	~800 MB
MMDB — `wxa_vpn-points.mmdb` (points)	~1.1 GB
Parquet	~1.2 GB

Plan storage and bandwidth accordingly. Compressed transfers are negotiated via Accept-Encoding: gzip.

Getting Started

Guides

Reference

Lookup

Aggregates

Bulk Exports

Format choice

Scheduling

MMDB lookup (Python)

Parquet to Snowflake

Concurrency

File size

​Format choice

​Scheduling

​MMDB lookup (Python)

​Parquet to Snowflake

​Concurrency

​File size

Format choice

Scheduling

MMDB lookup (Python)

Parquet to Snowflake

Concurrency

File size