Skip to content
VPNDetection

Migrate from IP2Location

Move from IP2Location to VPNDetection: change the request, map each IP2Location field to its VPNDetection field, and compare the answers before you switch.

This guide moves an integration from IP2Location.io's proxy detection to VPNDetection. It shows how the request changes, which VPNDetection field answers each of IP2Location's, how rules that read them change, and how to compare the two services on your own traffic before you switch.

Before you begin

  • A VPNDetection API key, if you need more than the free plan's fields. Without a key, a lookup answers the free plan's fields: is_vpn, is_tor, is_relay, and the address's country and network. See Plans and fields.
  • A sample of a few hundred addresses from your own traffic, one per line in sample.txt, for the comparison in step 4.

1. Change the request

IP2Location.io takes your key in a bearer header or the key query parameter, and the address in ip:

bash
curl -H "Authorization: Bearer $IP2LOCATION_KEY" "https://api.ip2location.io/?ip=8.8.8.8"

VPNDetection takes the address as the path and your key in the Authorization header:

bash
curl -H "Authorization: Bearer $VPNDETECTION_API_KEY" https://api.vpndetection.io/8.8.8.8

The original IP2Proxy web service, at api.ip2proxy.com, still answers keys issued before it closed to new registrations, with fields of its own; this guide maps IP2Location.io's. If your code can't set a header, send the key in the apikey query parameter instead; see Authentication. To make the request from your code with an official library, see Use an SDK.

2. Map the fields

IP2Location.io answers one is_proxy flag at the top level, and the proxy object, with a flag for each kind, on its plans that include it. VPNDetection answers one top-level flag for each kind of address, with a detail object beside it. Fields after Paid plan: come with a paid plan; the rest come with every plan, the free plan included.

IP2LocationVPNDetectionNotes
is_proxyis_vpn, is_tor; Paid plan: is_resproxy, is_dcproxy, is_pubproxyOne flag for each kind.
proxy.is_vpn, proxy.provideris_vpn; Paid plan: vpn.providervpn.provider is a stable ID; vpn.provider_name carries the display name.
proxy.is_residential_proxyPaid plan: is_resproxy
proxy.is_data_centerPaid plan: is_hosting, is_dcproxy, is_cdnHosting, datacenter proxies and CDNs are separate flags.
proxy.is_public_proxy, proxy.is_web_proxyPaid plan: is_pubproxy
proxy.is_toris_tor
proxy.last_seenPaid plan: vpn.last_seen, resproxy.last_seenA date, where proxy.last_seen counts days.
fraud_score, proxy.threatNo counterpart

The IP lookup reference documents every VPNDetection field.

3. Update your rules

Most rules move field for field:

  • A rule that read is_proxy reads the flags it was built from.
  • proxy.is_data_center splits into is_hosting, is_dcproxy and is_cdn, so a rule can block datacenter proxies and allow a CDN.
  • There's no fraud_score: rules decide from the classifications.
  • A field your plan doesn't include is absent rather than false, so a rule checks that a paid field is present before it acts on the value. See Plans and fields.

The equivalent of is_proxy on VPNDetection is:

js
const r = await client.lookup(ip);
const anonymous = r.isVpn || r.isTor || r.isResproxy === true || r.isDcproxy === true
    || r.isMobproxy === true || r.isPubproxy === true;

4. Compare the answers

Before you switch, run both services on your sample and review the addresses where they disagree. This script prints each address where IP2Location's VPN flag and VPNDetection's differ. Save it as compare.mjs beside sample.txt, install the library with npm install vpndetection, and run node compare.mjs:

js
import { readFileSync } from 'node:fs';
import { VPNDetection } from 'vpndetection';

const client = new VPNDetection({ apiKey: process.env.VPNDETECTION_API_KEY });
const ips = readFileSync('sample.txt', 'utf8').split('\n').filter(Boolean);

for (const ip of ips) {
    const res = await fetch(`https://api.ip2location.io/?ip=${ip}`, {
        headers: { 'Authorization': `Bearer ${process.env.IP2LOCATION_KEY}` },
    });
    const theirs = await res.json();
    const ours = await client.lookup(ip);
    const theirFlag = theirs.proxy?.is_vpn === true;
    const ourFlag = ours.isVpn;
    if (theirFlag !== ourFlag) {
        console.log(ip, 'IP2Location:', theirFlag, 'VPNDetection:', ourFlag);
    }
}

If your plan answers no proxy object, compare theirs.is_proxy with the combined flag from step 3 instead.

Every provider builds its own data, so some disagreement is expected. Look up a few of the addresses on both sides. If you believe VPNDetection's answer is wrong, send us the address.

5. Switch over

Once the comparison looks right, switch in stages, so you can stop at any point without affecting your users:

  1. Run both side by side. Keep deciding with IP2Location, and log VPNDetection's answer beside it for a few days of real traffic.
  2. Switch the decisions. Decide with VPNDetection, and keep logging IP2Location's answer while you watch for surprises.
  3. Remove IP2Location. Once your logs are clean, delete the old client from your code and revoke its key.

Next steps

When the answers suit your rules, switch your code to VPNDetection. Protect a web app applies rules in middleware, and the guides cover sign-ups, logins, payments and country rules. Before you launch, review the go-live checklist.