Real-Time VPN and Proxy Detection

Q: Do I need an API key in the frontend?

No. Authorization is by Request Origin : register your domain once and requests from it and its subdomains authenticate automatically. No secret ships to the browser.

Overview

Detect VPNs, proxies and residential proxies live in the browser, at the moment a user acts. See what the service does and try it on the Real-Time VPN and Proxy Detection product page.

Setup

The script carries no API key. Requests are authorized by origin, so register your domain before your first call.

Sign up for your IPGeolocation account.
Add your origin as a Request Origin, for example https://app.example.com .
Save.

Quick start

<script src="https://static.ipgeolocation.io/web-assets/static/security/session-analysis.js"></script>

<script>
    Analysis
        .startMonitoring()
        .get()
        .then(result => console.log(result))
        .catch(error => console.error(error instanceof Error ? error.message : String(error)));
</script>

Response for a clean connection:

Response Preview

1{
2  "public_ip": "119.156.x.x",
3  "public_ip_country_code": "PK",
4  "live_vpn_proxy_detection": {
5    "is_anonymous": false,
6    "confidence_score": 100,
7    "proxy_score": 0,
8    "vpn_score": 0
9  },
10  "visitor_actual_location": {
11    "actual_ip": "119.156.x.x",
12    "actual_country_code": "PK",
13    "confidence_score": 100
14  }
15}

In plain words: this connection is not anonymized, the service is certain about it, and the visitor is where the request says they are.

1. Optional objects

Pass an include string to startMonitoring() to attach extra data about the public IP. Separate several names with commas, or pass all for everything.

Value	Adds
`security`	`ip_security`
`location`	`ip_location`
`asn`	`ip_asn`
`company`	`ip_company`
`all`	All four objects

const include = "security,location";

Analysis
    .startMonitoring(include)
    .get()
    .then(result => console.log(result));

Each extra object costs credits; see Credits.

Response fields

1. The IP address the request comes from

Two top-level fields, describing the IP address the user appears to be on:

Field	Type	Meaning
`public_ip`	string	The IP address your server sees on the request. Behind a VPN or proxy this is the exit node's IP address, not the user's.
`public_ip_country_code`	string	Two-letter ISO country code for that IP address. Behind a VPN or proxy, this is the exit node's country, not the user's.

2. The live verdict: live_vpn_proxy_detection

Four fields, meant to be read together:

Field	Type	Meaning
`is_anonymous`	boolean	The headline answer. `true` means the connection is anonymized through a VPN or a proxy. It does not say which; the two scores below do.
`confidence_score`	up to 100	How much to trust that yes or no. `100` with `is_anonymous: false` means confidently clean; a low value is weak evidence either way.
`proxy_score`	0 to 100	Looks like a proxy, including residential and rotating proxies.
`vpn_score`	0 to 100	Looks like a VPN.

3. Where the visitor really is: visitor_actual_location

Where the user actually is, recovered by the live tests:

Field	Type	Meaning
`actual_ip`	string	The visitor's real IP address behind the VPN or proxy. Falls back to `public_ip` when nothing is hidden, or when the real IP cannot be detected.
`actual_country_code`	string	Two-letter ISO country code of the visitor's actual location.
`confidence_score`	up to 100	Certainty about that actual country. Gate on it before acting on a country mismatch.

4. Optional objects about the public IP

Each appears only when its name, or all , is in include . They describe the public IP, so behind a VPN or proxy they refer to the exit node, not the visitor.

Object	include value	What it tells you	Field reference
`ip_security`	`security`	What is already known about the IP: VPN, proxy, Tor, bot, and threat signals	IP Security API response reference
`ip_location`	`location`	Where the IP is: country, state, city, coordinates	Location object reference
`ip_asn`	`asn`	Who routes the IP: AS number, organization, type	ASN object reference
`ip_company`	`company`	Who owns the IP: company name, type, domain	Company object reference

Response with include: "all" :

Response Preview

1{
2  "public_ip": "94.237.x.x",
3  "public_ip_country_code": "DE",
4  "live_vpn_proxy_detection": {
5    "is_anonymous": true,
6    "confidence_score": 90,
7    "proxy_score": 90,
8    "vpn_score": 10
9  },
10  "visitor_actual_location": {
11    "actual_ip": "119.156.x.x",
12    "actual_country_code": "PK",
13    "confidence_score": 80
14  },
15  "ip_security": {
16    "threat_score": 50,
17    "is_tor": false,
18    "is_proxy": true,
19    "proxy_provider_names": [],
20    "proxy_confidence_score": 99,
21    "proxy_last_seen": "",
22    "is_residential_proxy": false,
23    "is_vpn": true,
24    "vpn_provider_names": ["Browsec VPN"],
25    "vpn_confidence_score": 99,
26    "vpn_last_seen": "2026-08-27",
27    "is_relay": false,
28    "relay_provider_name": "",
29    "is_anonymous": true,
30    "is_known_attacker": false,
31    "is_bot": false,
32    "bot_confidence_score": 0,
33    "bot_operator_name": "",
34    "bot_type": "",
35    "is_known_good_bot": false,
36    "bot_last_seen": "",
37    "is_spam": false,
38    "is_cloud_provider": true,
39    "cloud_provider_name": "UpCloud Ltd",
40    "is_corporate_gateway": false,
41    "corporate_gateway_type": "",
42    "corporate_gateway_provider_name": ""
43  },
44  "ip_location": {
45    "continent_code": "EU",
46    "continent_name": "Europe",
47    "country_code2": "DE",
48    "country_code3": "DEU",
49    "country_name": "Germany",
50    "country_name_official": "Federal Republic of Germany",
51    "country_capital": "Berlin",
52    "state_prov": "Hesse",
53    "state_code": "DE-HE",
54    "district": "Frankfurt",
55    "city": "Frankfurt",
56    "locality": "Frankfurt",
57    "accuracy_radius": "8.588",
58    "confidence": "medium",
59    "dma_code": "",
60    "zipcode": "60311",
61    "latitude": "50.11208",
62    "longitude": "8.68341",
63    "is_eu": true,
64    "country_flag": "https://ipgeolocation.io/static/flags/de_64.png",
65    "geoname_id": "6463469",
66    "country_emoji": "🇩🇪"
67  },
68  "ip_asn": {
69    "as_number": "AS202053",
70    "organization": "UpCloud Ltd",
71    "country": "FI",
72    "type": "BUSINESS",
73    "domain": "upcloud.com",
74    "date_allocated": "2014-04-24",
75    "rir": "RIPE"
76  },
77  "ip_company": {
78    "name": "UpCloud Cloud Servers",
79    "type": "HOSTING",
80    "domain": "upcloud.com"
81  }
82}

Reading it in code:

const liveDetection  = result.live_vpn_proxy_detection;
const actualLocation = result.visitor_actual_location;
const ipSecurity     = result.ip_security;

liveDetection.confidence_score;                                        // 90
actualLocation.actual_country_code;                                    // "PK"
actualLocation.actual_country_code !== result.public_ip_country_code;  // true: presenting DE, actually in PK
ipSecurity.vpn_provider_names;                                         // ["Browsec VPN"]
ipSecurity.threat_score;                                               // 50
result.ip_location.city;                                               // "Frankfurt": the exit node, not the visitor
result.ip_asn.organization;                                            // "UpCloud Ltd"
result.ip_company.type;                                                // "HOSTING"

Acting on the verdict

When is_anonymous is true , confidence_score decides how much friction the session deserves. Blocking everything the service flags costs real customers; ignoring the flag defeats the check. Work in bands, and tune the cutoffs against your own confirmed fraud outcomes:

confidence_score	What it means	Recommended action
Below 30	Very weak signal. Expect false positives.	Allow. Log the result, add nothing to the user's path.
30 to 50	Uncertain. Could be an unusual network, a mobile carrier, or a corporate gateway.	Allow and monitor. Feed it into your wider risk score; add friction only if another signal agrees.
51 to 80	Likely anonymized. Enough for friction, not for a hard denial alone.	Challenge. MFA, email or SMS verification, or a CAPTCHA. Hold payouts and first orders for review.
81 and above	Confidently anonymized.	Block or restrict. High `proxy_score` : block or hold for review. High `vpn_score` : prefer a hard challenge, since many ordinary people browse through VPNs.

These bands apply only when is_anonymous is true . High confidence with is_anonymous: false is a clean visitor, not a risky one.

Credits

include	Credits per call
Default	3
`security`	+2
Any or all of `location` , `asn` , `company`	+1
`all`	6

The three objects location , asn , and company share a single credit, whether you include one or all of them. For example, security alone costs 5, location,asn,company costs 4, and security,location costs 6.

FAQs

No. Authorization is by Request Origin: register your domain once and requests from it and its subdomains authenticate automatically. No secret ships to the browser.

No, the script is browser-only. For backend, mobile, or bulk checks, use the IP Security API, which returns only the reputation data through a key-authenticated API call.

Usually 1 to 5 seconds, because live network tests run against the connection rather than a single database lookup. Start monitoring on page load so the wait is over before the user reaches your decision point.

Yes. visitor_actual_location returns the actual_ip and actual_country_code recovered by the live tests, with its own confidence_score. Use that country for fraud and compliance rules, and gate on the confidence before acting on a mismatch.

Yes, and that is the main reason it exists. Static lists miss them because the IPs come from constantly refreshed pools of ordinary consumer ISP addresses with no listing history yet; live analysis catches the anonymization behavior itself.

ip_security.is_vpn and is_proxy come from our IP intelligence database, updated daily: they tell you an IP address is known to be associated with VPN or proxy infrastructure. The live vpn_score and proxy_score come from inspecting the current connection, so they describe this session rather than the address's history.

No. It classifies a session with live connection-level techniques only, and does not consult the IP Security database or traditional IP intelligence to reach its verdict. Including security simply attaches the database view next to the live one.

A residential IP is a real household address that may also be part of a proxy network. The homeowner's own request and an anonymous request routed through the network can arrive from it seconds apart. A database can say the address is associated with residential proxy infrastructure, but not how it is being used on this connection, so acting on the association alone can affect legitimate users too.

Yes. No offline database has complete coverage: new VPN endpoints, private proxies, and rotating residential pools may not be listed yet. Real-time detection does not depend on prior knowledge of the IP address.

In our testing, classification accuracy is around 98%. In the remaining cases, confidence_score was below 35, so gating on confidence gives you an extra signal on the sessions most likely to be misread.

Both, where you can. The IP Security API gives broader IP-level context and known associations; real-time detection tells you what the connection is doing right now. Together they support better decisions without unnecessarily blocking legitimate users.

No. It measures certainty about the verdict it sits next to, in either direction: 100 with is_anonymous: false means confidently clean. Risk lives in proxy_score, vpn_score, and ip_security.threat_score.

Usually not. Many are ordinary privacy-conscious or corporate users. Work the confidence bands: log the weak signals, challenge the likely ones, and reserve blocks for high confidence backed by a second signal.

3 credits per call, 5 with security included, and 1 more for any of location, asn, or company, so all costs 6. Credits come from your plan's normal credit pool. It is a paid plan feature; contact our support team for a free trial.

Real-Time Proxy andVPN Detection

Looking for features, modules, and use cases? Visit the Live Proxy & VPN Detection page.

Explore Live Proxy & VPN Detection