Skip to content
VPNDetection

Migrate from IPQualityScore

Move from IPQualityScore to VPNDetection: change the request, map each field to VPNDetection's, and compare the answers first.

This guide moves an integration from IPQualityScore's Proxy & VPN Detection API to VPNDetection. It shows how the request changes, which VPNDetection field answers each of IPQualityScore'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

IPQualityScore takes your key in the path, or in the key query parameter or the IPQS-KEY header:

bash
curl "https://ipqualityscore.com/api/json/ip/$IPQS_KEY/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

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

IPQualityScore answers flat fields: flags such as vpn, tor and proxy, where proxy also covers VPNs and Tor, the network and location, and a fraud_score. 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.

IPQualityScoreVPNDetectionNotes
vpn, active_vpnis_vpn; Paid plan: vpn.providervpn.provider names the VPN service.
tor, active_toris_toris_tor flags current Tor exits.
proxyPaid plan: is_resproxy, is_dcproxy, is_mobproxy, is_pubproxyIPQualityScore's proxy also covers VPNs and Tor. VPNDetection answers one flag for each kind of proxy.
connection_typeasn.type; Paid plan: company.type, is_hostingIPQualityScore's types (Residential, Corporate, Education, Mobile, Data Center) become asn.type for the network and company.type for the organization: isp, hosting, education, government or business.
ISP, organization, ASN, hostasn.name, asn.asn, hostname; Paid plan: company.nameasn.asn is a number, as ASN is.
country_code, timezonelocation.country, location.timezone
city, region, zip_code, latitude, longitudePaid plan: location.city, location.region, location.postal_code, location.latitude, location.longitude
fraud_score, recent_abuse, bot_status, abuse_velocityNo counterpartVPNDetection doesn't score addresses. See step 3.

The IP lookup reference documents every VPNDetection field.

3. Update your rules

The main change is from a score to classifications. A rule that refused a fraud_score above a threshold becomes a rule over what the address is.

  • IPQualityScore describes a score of 75 or more as likely a proxy, a VPN or Tor, so start with those flags: is_vpn and is_tor on every plan, and the four proxy flags on a paid plan.
  • A rule that read proxy reads is_vpn, is_tor and the proxy flags together, because IPQualityScore's proxy covers all of them.
  • A connection_type of Data Center becomes asn.type equal to hosting on every plan, or is_hosting on a paid plan.
  • 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 IPQualityScore's 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 IPQualityScore'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://ipqualityscore.com/api/json/ip/${process.env.IPQS_KEY}/${ip}`);
    const theirs = await res.json();
    const ours = await client.lookup(ip);
    const theirFlag = theirs.vpn === true;
    const ourFlag = ours.isVpn;
    if (theirFlag !== ourFlag) {
        console.log(ip, 'IPQualityScore:', theirFlag, 'VPNDetection:', ourFlag);
    }
}

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 IPQualityScore, and log VPNDetection's answer beside it for a few days of real traffic.
  2. Switch the decisions. Decide with VPNDetection, and keep logging IPQualityScore's answer while you watch for surprises.
  3. Remove IPQualityScore. 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.