What is the difference between a proxy, a VPN, and Tor?

Proxy: Forwards traffic through another server and mainly masks the IP. VPN: Routes traffic through a remote server and encrypts and tunnels the connection. Tor: Routes traffic through multiple nodes to provide stronger anonymity.

IP Security API

Q: What does is_known_good_bot mean?

is_bot says automated activity is associated with the IP. is_known_good_bot says the operator is declared and verifiable, such as a search engine crawler, an uptime or SEO service, or an internet-wide security scanner, usually because the operator publishes the IP range itself. When it is true , bot_operator_name and bot_type identify the bot. When is_bot is true and is_known_good_bot is false , the traffic is automated but has no recognized legitimate operator, and your own bot policy applies.

Run in Postman

Overview

The IP Security API returns threat flags for any IPv4 or IPv6 address. It detects whether an IP is associated with a VPN, proxy, residential proxy, Tor exit node, relay, bot activity, spam activity or known attacker behavior. For VPN, proxy and bot signals it also returns confidence scores, provider or operator names and last seen dates when available, and for bots the bot type and whether it is a known good bot such as a search engine crawler.

The API also reports whether the IP belongs to a cloud provider or is a corporate gateway, the shared egress address of an enterprise secure web gateway such as Zscaler or Netskope, with the provider name and gateway type. Use it to identify anonymous, automated and shared traffic before it reaches your systems.

IP Security API Lookup Endpoints

The IP Security API offers two endpoints for IP risk assessment: single lookup and bulk lookup. Below you’ll find details and examples for both endpoints, along with the full list of optional query parameters and how to use them with each endpoint.

Single IP Lookup Endpoint

1. Lookup the Caller IP (No `ip` Parameter)

If you don’t pass the ip parameter, the API automatically detects the public IP address of the requesting client and returns its threat score and security signals (for example, VPN/proxy/Tor/bot/spam/hosting/corporate gateway indicators and the provider names when available). Use this option when you want to assess the IP risk of the requesting client without specifying an IP address.

curl -X GET 'https://api.ipgeolocation.io/v3/security?apiKey=API_KEY'

Response Preview

1{
2  "ip": "119.156.120.72",
3  "security": {
4    "threat_score": 0,
5    "is_tor": false,
6    "is_proxy": false,
7    "proxy_provider_names": [],
8    "proxy_confidence_score": 0,
9    "proxy_last_seen": "",
10    "is_residential_proxy": false,
11    "is_vpn": false,
12    "vpn_provider_names": [],
13    "vpn_confidence_score": 0,
14    "vpn_last_seen": "",
15    "is_relay": false,
16    "relay_provider_name": "",
17    "is_anonymous": false,
18    "is_known_attacker": false,
19    "is_bot": false,
20    "bot_confidence_score": 0,
21    "bot_operator_name": "",
22    "bot_type": "",
23    "is_known_good_bot": false,
24    "bot_last_seen": "",
25    "is_spam": false,
26    "is_cloud_provider": false,
27    "cloud_provider_name": "",
28    "is_corporate_gateway": false,
29    "corporate_gateway_type": "",
30    "corporate_gateway_provider_name": ""
31  }
32}

2. Lookup a Specific IP Address

Pass the ip parameter to check a specific IPv4 or IPv6 address. The API returns the threat score and security signals (such as VPN, proxy, residential proxy, Tor, bot, spam, relay, hosting and corporate gateway flags), along with provider names, confidence scores, bot type and last seen dates when available.

curl -X GET 'https://api.ipgeolocation.io/v3/security?apiKey=API_KEY&ip=145.223.7.7'

Response Preview

1{
2  "ip": "145.223.7.7",
3  "security": {
4    "threat_score": 90,
5    "is_tor": false,
6    "is_proxy": true,
7    "proxy_provider_names": [
8      "NetNut",
9      "ProxyScrape",
10      "Oxy Labs",
11      "DataImpulse"
12    ],
13    "proxy_confidence_score": 99,
14    "proxy_last_seen": "2026-09-01",
15    "is_residential_proxy": true,
16    "is_vpn": true,
17    "vpn_provider_names": [
18      "SurfShark VPN",
19      "Ishaan VPN"
20    ],
21    "vpn_confidence_score": 99,
22    "vpn_last_seen": "2026-07-31",
23    "is_relay": false,
24    "relay_provider_name": "",
25    "is_anonymous": true,
26    "is_known_attacker": true,
27    "is_bot": false,
28    "bot_confidence_score": 0,
29    "bot_operator_name": "",
30    "bot_type": "",
31    "is_known_good_bot": false,
32    "bot_last_seen": "",
33    "is_spam": true,
34    "is_cloud_provider": true,
35    "cloud_provider_name": "Brander Group Inc.",
36    "is_corporate_gateway": false,
37    "corporate_gateway_type": "",
38    "corporate_gateway_provider_name": ""
39  }
40}

3. Bot Activity Lookup

When is_bot is true , the bot detail fields are populated. The two lookups below show an undeclared bot and a known good bot.

I. Bad bot activity

When bot activity is detected, the API also returns the confidence score, the bot_type, the operator name for declared bots, and the last seen date. Bad bot types such as brute_force also set is_known_attacker to true .

curl -X GET 'https://api.ipgeolocation.io/v3/security?apiKey=API_KEY&ip=223.197.196.92'

Response Preview

1{
2  "ip": "223.197.196.92",
3  "security": {
4    "threat_score": 40,
5    "is_tor": false,
6    "is_proxy": false,
7    "proxy_provider_names": [],
8    "proxy_confidence_score": 0,
9    "proxy_last_seen": "",
10    "is_residential_proxy": false,
11    "is_vpn": false,
12    "vpn_provider_names": [],
13    "vpn_confidence_score": 0,
14    "vpn_last_seen": "",
15    "is_relay": false,
16    "relay_provider_name": "",
17    "is_anonymous": false,
18    "is_known_attacker": true,
19    "is_bot": true,
20    "bot_confidence_score": 95,
21    "bot_operator_name": "",
22    "bot_type": "brute_force",
23    "is_known_good_bot": false,
24    "bot_last_seen": "2026-06-21",
25    "is_spam": false,
26    "is_cloud_provider": false,
27    "cloud_provider_name": "",
28    "is_corporate_gateway": false,
29    "corporate_gateway_type": "",
30    "corporate_gateway_provider_name": ""
31  }
32}

II. Known good bot activity

For a declared bots such as a search engine, is_known_good_bot is true and the operator is named. The anonymity and abuse flags stay false and threat_score stays low; is_cloud_provider may still be true because many crawlers run from cloud address space.

curl -X GET 'https://api.ipgeolocation.io/v3/security?apiKey=API_KEY&ip=4.227.36.0'

Response Preview

1{
2  "ip": "4.227.36.0",
3  "security": {
4    "threat_score": 15,
5    "is_tor": false,
6    "is_proxy": false,
7    "proxy_provider_names": [],
8    "proxy_confidence_score": 0,
9    "proxy_last_seen": "",
10    "is_residential_proxy": false,
11    "is_vpn": false,
12    "vpn_provider_names": [],
13    "vpn_confidence_score": 0,
14    "vpn_last_seen": "",
15    "is_relay": false,
16    "relay_provider_name": "",
17    "is_anonymous": false,
18    "is_known_attacker": false,
19    "is_bot": true,
20    "bot_confidence_score": 95,
21    "bot_operator_name": "ChatGPT",
22    "bot_type": "ai_crawler",
23    "is_known_good_bot": true,
24    "bot_last_seen": "2026-09-03",
25    "is_spam": false,
26    "is_cloud_provider": true,
27    "cloud_provider_name": "Microsoft Corporation",
28    "is_corporate_gateway": false,
29    "corporate_gateway_type": "",
30    "corporate_gateway_provider_name": ""
31  }
32}

4. Lookup a Corporate Gateway IP

When the IP is an egress address of an enterprise secure web gateway, is_corporate_gateway is true and the API returns the gateway type and provider name. Gateway address space is usually registered to the vendor, so is_cloud_provider is often true for the same IP.

curl -X GET 'https://api.ipgeolocation.io/v3/security?apiKey=API_KEY&ip=87.58.66.106'

Response Preview

1{
2  "ip": "87.58.66.106",
3  "security": {
4    "threat_score": 5,
5    "is_tor": false,
6    "is_proxy": false,
7    "proxy_provider_names": [],
8    "proxy_confidence_score": 0,
9    "proxy_last_seen": "",
10    "is_residential_proxy": false,
11    "is_vpn": false,
12    "vpn_provider_names": [],
13    "vpn_confidence_score": 0,
14    "vpn_last_seen": "",
15    "is_relay": false,
16    "relay_provider_name": "",
17    "is_anonymous": false,
18    "is_known_attacker": false,
19    "is_bot": false,
20    "bot_confidence_score": 0,
21    "bot_operator_name": "",
22    "bot_type": "",
23    "is_known_good_bot": false,
24    "bot_last_seen": "",
25    "is_spam": false,
26    "is_cloud_provider": true,
27    "cloud_provider_name": "Zscaler Switzerland GmbH",
28    "is_corporate_gateway": true,
29    "corporate_gateway_type": "secure_web_gateway",
30    "corporate_gateway_provider_name": "Zscaler"
31  }
32}

Additional Query Parameters

Use these query parameters to exclude fields, or return only the fields you need.

1. Exclude Fields ( `excludes` )

Use excludes to remove fields you don’t need from the response. Pass a comma-separated list of field paths.

How to write field paths: Use dot notation for nested fields: object.field . For example:

Exclude specific flags: security.is_tor , security.is_cloud_provider
Exclude a whole block: security.is_corporate_gateway , security.corporate_gateway_type , security.corporate_gateway_provider_name

An example request and response are shown below.

curl -X GET 'https://api.ipgeolocation.io/v3/security?apiKey=API_KEY&ip=145.223.7.7&excludes=security.is_tor,security.is_cloud_provider'

Response Preview

1{
2  "ip": "145.223.7.7",
3  "security": {
4    "threat_score": 90,
5    "is_proxy": true,
6    "proxy_provider_names": [
7      "NetNut",
8      "ProxyScrape",
9      "Oxy Labs",
10      "DataImpulse"
11    ],
12    "proxy_confidence_score": 99,
13    "proxy_last_seen": "2026-09-01",
14    "is_residential_proxy": true,
15    "is_vpn": true,
16    "vpn_provider_names": [
17      "SurfShark VPN",
18      "Ishaan VPN"
19    ],
20    "vpn_confidence_score": 99,
21    "vpn_last_seen": "2026-07-31",
22    "is_relay": false,
23    "relay_provider_name": "",
24    "is_anonymous": true,
25    "is_known_attacker": true,
26    "is_bot": false,
27    "bot_confidence_score": 0,
28    "bot_operator_name": "",
29    "bot_type": "",
30    "is_known_good_bot": false,
31    "bot_last_seen": "",
32    "is_spam": true,
33    "cloud_provider_name": "Brander Group Inc.",
34    "is_corporate_gateway": false,
35    "corporate_gateway_type": "",
36    "corporate_gateway_provider_name": ""
37  }
38}

In this example, the response does not contain is_tor and is_cloud_provider in the security object.

2. Return Specific Fields ( `fields` )

Use fields to return only the response fields you need. This helps reduce response size and keeps the payload focused.

How to specify fields: Provide a comma-separated list using dot notation: object.field . For example:

Security score: security.threat_score
Bot signals: security.is_bot , security.bot_type , security.is_known_good_bot

An example request and response are shown below.

curl -X GET 'https://api.ipgeolocation.io/v3/security?apiKey=API_KEY&ip=2.56.188.34&fields=security.threat_score'

Response Preview

1{
2  "ip": "2.56.188.34",
3  "security": {
4    "threat_score": 80
5  }
6}

Bulk IP Security Lookup Endpoint

The bulk endpoint allows you to perform IP security lookup for multiple IPv4 or IPv6 (maximum 50,000) in a single request.

Bulk lookup supports the same query parameters as the single lookup ( excludes , fields , and output ).

1. Bulk lookup request

Send a POST request and pass the ips array as JSON.

curl -X POST 'https://api.ipgeolocation.io/v3/security-bulk?apiKey=API_KEY' \
-H 'Content-Type: application/json' \
-d '{"ips":["145.223.7.7","2.56.188.35"]}'

Response Preview

1[
2  {
3    "ip": "145.223.7.7",
4    "security": {
5      "threat_score": 90,
6      "is_tor": false,
7      "is_proxy": true,
8      "proxy_provider_names": [
9        "NetNut",
10        "ProxyScrape",
11        "Oxy Labs",
12        "DataImpulse"
13      ],
14      "proxy_confidence_score": 99,
15      "proxy_last_seen": "2026-09-01",
16      "is_residential_proxy": true,
17      "is_vpn": true,
18      "vpn_provider_names": [
19        "SurfShark VPN",
20        "Ishaan VPN"
21      ],
22      "vpn_confidence_score": 99,
23      "vpn_last_seen": "2026-07-31",
24      "is_relay": false,
25      "relay_provider_name": "",
26      "is_anonymous": true,
27      "is_known_attacker": true,
28      "is_bot": false,
29      "bot_confidence_score": 0,
30      "bot_operator_name": "",
31      "bot_type": "",
32      "is_known_good_bot": false,
33      "bot_last_seen": "",
34      "is_spam": true,
35      "is_cloud_provider": true,
36      "cloud_provider_name": "Brander Group Inc.",
37      "is_corporate_gateway": false,
38      "corporate_gateway_type": "",
39      "corporate_gateway_provider_name": ""
40    }
41  },
42  {
43    "ip": "2.56.188.35",
44    "security": {
45      "threat_score": 35,
46      "is_tor": false,
47      "is_proxy": false,
48      "proxy_provider_names": [],
49      "proxy_confidence_score": 0,
50      "proxy_last_seen": "",
51      "is_residential_proxy": false,
52      "is_vpn": false,
53      "vpn_provider_names": [],
54      "vpn_confidence_score": 0,
55      "vpn_last_seen": "",
56      "is_relay": false,
57      "relay_provider_name": "",
58      "is_anonymous": false,
59      "is_known_attacker": true,
60      "is_bot": false,
61      "bot_confidence_score": 0,
62      "bot_operator_name": "",
63      "bot_type": "",
64      "is_known_good_bot": false,
65      "bot_last_seen": "",
66      "is_spam": false,
67      "is_cloud_provider": true,
68      "cloud_provider_name": "Packethub S.A.",
69      "is_corporate_gateway": false,
70      "corporate_gateway_type": "",
71      "corporate_gateway_provider_name": ""
72    }
73  }
74]

2. Bulk Lookup with Additional Request Parameters

Use fields when you want to return only specific properties from the security object. Use excludes when you want to return the full security object but omit certain properties.

I. Using fields Parameter

This example uses the fields parameter to return only specific fields from the security object.

The goal is to return only:

security.is_vpn
security.vpn_confidence_score
security.is_proxy

Here is how the parameter is used:

Select only required fields: fields=security.is_vpn, security.vpn_confidence_score, security.is_proxy

curl -X POST 'https://api.ipgeolocation.io/v3/security-bulk?apiKey=API_KEY&fields=security.is_vpn,security.vpn_confidence_score,security.is_proxy' \
-H 'Content-Type: application/json' \
-d '{"ips":["2.56.188.34","2.56.188.35"]}'

Response Preview

1[
2  {
3    "ip": "2.56.188.34",
4    "security": {
5      "is_proxy": false,
6      "is_vpn": true,
7      "vpn_confidence_score": 75
8    }
9  },
10  {
11    "ip": "2.56.188.35",
12    "security": {
13      "is_proxy": false,
14      "is_vpn": false,
15      "vpn_confidence_score": 0
16    }
17  }
18]

II. Using excludes Parameter

This example uses the excludes parameter to remove specific fields from the security object.

The goal is to return the full security object except:

security.threat_score
security.proxy_last_seen
security.vpn_last_seen

Here is how the parameter is used:

Exclude specific fields: excludes=security.threat_score, security.proxy_last_seen, security.vpn_last_seen

curl -X POST 'https://api.ipgeolocation.io/v3/security-bulk?apiKey=API_KEY&excludes=security.threat_score,security.proxy_last_seen,security.vpn_last_seen' \
-H 'Content-Type: application/json' \
-d '{"ips":["145.223.7.7","2.56.188.35"]}'

Response Preview

1[
2  {
3    "ip": "145.223.7.7",
4    "security": {
5      "is_tor": false,
6      "is_proxy": true,
7      "proxy_provider_names": [
8        "NetNut",
9        "ProxyScrape",
10        "Oxy Labs",
11        "DataImpulse"
12      ],
13      "proxy_confidence_score": 99,
14      "is_residential_proxy": true,
15      "is_vpn": true,
16      "vpn_provider_names": [
17        "SurfShark VPN",
18        "Ishaan VPN"
19      ],
20      "vpn_confidence_score": 99,
21      "is_relay": false,
22      "relay_provider_name": "",
23      "is_anonymous": true,
24      "is_known_attacker": true,
25      "is_bot": false,
26      "bot_confidence_score": 0,
27      "bot_operator_name": "",
28      "bot_type": "",
29      "is_known_good_bot": false,
30      "bot_last_seen": "",
31      "is_spam": true,
32      "is_cloud_provider": true,
33      "cloud_provider_name": "Brander Group Inc.",
34      "is_corporate_gateway": false,
35      "corporate_gateway_type": "",
36      "corporate_gateway_provider_name": ""
37    }
38  },
39  {
40    "ip": "2.56.188.35",
41    "security": {
42      "is_tor": false,
43      "is_proxy": false,
44      "proxy_provider_names": [],
45      "proxy_confidence_score": 0,
46      "is_residential_proxy": false,
47      "is_vpn": false,
48      "vpn_provider_names": [],
49      "vpn_confidence_score": 0,
50      "is_relay": false,
51      "relay_provider_name": "",
52      "is_anonymous": false,
53      "is_known_attacker": true,
54      "is_bot": false,
55      "bot_confidence_score": 0,
56      "bot_operator_name": "",
57      "bot_type": "",
58      "is_known_good_bot": false,
59      "bot_last_seen": "",
60      "is_spam": false,
61      "is_cloud_provider": true,
62      "cloud_provider_name": "Packethub S.A.",
63      "is_corporate_gateway": false,
64      "corporate_gateway_type": "",
65      "corporate_gateway_provider_name": ""
66    }
67  }
68]

3. Bulk Lookup Response for Invalid IPs

In a bulk request, each IP address is processed independently.

If an IP address is invalid (non-public, non-routable, or malformed), the API returns an object containing only a descriptive message field for that entry along with the valid public IP address responses.

curl -X POST 'https://api.ipgeolocation.io/v3/security-bulk?apiKey=API_KEY' \
-H 'Content-Type: application/json' \
-d '{"ips":["10.0.0.0","2.56.188.35"]}'

Response Preview

1[
2  {
3    "message": "'10.0.0.0' is a bogon IP address."
4  },
5  {
6    "ip": "2.56.188.35",
7    "security": {
8      "threat_score": 35,
9      "is_tor": false,
10      "is_proxy": false,
11      "proxy_provider_names": [],
12      "proxy_confidence_score": 0,
13      "proxy_last_seen": "",
14      "is_residential_proxy": false,
15      "is_vpn": false,
16      "vpn_provider_names": [],
17      "vpn_confidence_score": 0,
18      "vpn_last_seen": "",
19      "is_relay": false,
20      "relay_provider_name": "",
21      "is_anonymous": false,
22      "is_known_attacker": true,
23      "is_bot": false,
24      "bot_confidence_score": 0,
25      "bot_operator_name": "",
26      "bot_type": "",
27      "is_known_good_bot": false,
28      "bot_last_seen": "",
29      "is_spam": false,
30      "is_cloud_provider": true,
31      "cloud_provider_name": "Packethub S.A.",
32      "is_corporate_gateway": false,
33      "corporate_gateway_type": "",
34      "corporate_gateway_provider_name": ""
35    }
36  }
37]

Security Details in Main IPGeolocation Endpoint

Security data is available only on the Paid plan of the IP Geolocation API. See the Pricing page for plan details.

You can retrieve security details using the /v3/ipgeo endpoint by explicitly including include=security in the query parameters. When requested, the response includes security information along with location, abuse contact, timezone, ASN data, user-agent, network, company and other fields described in the IP Geolocation API documentation.

Security details are returned in the /v3/ipgeo response once the security object is enabled, as shown below.

curl -X GET 'https://api.ipgeolocation.io/v3/ipgeo?apiKey=API_KEY&ip=145.223.7.7&include=security'

Response Preview

1{
2  "ip": "145.223.7.7",
3  "security": {
4    "threat_score": 90,
5    "is_tor": false,
6    "is_proxy": true,
7    "proxy_provider_names": [
8      "NetNut",
9      "ProxyScrape",
10      "Oxy Labs",
11      "DataImpulse"
12    ],
13    "proxy_confidence_score": 99,
14    "proxy_last_seen": "2026-09-01",
15    "is_residential_proxy": true,
16    "is_vpn": true,
17    "vpn_provider_names": [
18      "SurfShark VPN",
19      "Ishaan VPN"
20    ],
21    "vpn_confidence_score": 99,
22    "vpn_last_seen": "2026-07-31",
23    "is_relay": false,
24    "relay_provider_name": "",
25    "is_anonymous": true,
26    "is_known_attacker": true,
27    "is_bot": false,
28    "bot_confidence_score": 0,
29    "bot_operator_name": "",
30    "bot_type": "",
31    "is_known_good_bot": false,
32    "bot_last_seen": "",
33    "is_spam": true,
34    "is_cloud_provider": true,
35    "cloud_provider_name": "Brander Group Inc.",
36    "is_corporate_gateway": false,
37    "corporate_gateway_type": "",
38    "corporate_gateway_provider_name": ""
39  },
40  "location": {
41    "continent_code": "NA",
42    "continent_name": "North America",
43    "country_code2": "US",
44    "country_code3": "USA",
45    "country_name": "United States",
46    "country_name_official": "United States of America",
47    "country_capital": "Washington, D.C.",
48    "state_prov": "Nebraska",
49    "state_code": "US-NE",
50    "district": "Douglas",
51    "city": "Omaha",
52    "zipcode": "68102",
53    "latitude": "41.26068",
54    "longitude": "-95.94026",
55    "is_eu": false,
56    "country_flag": "https://ipgeolocation.io/static/flags/us_64.png",
57    "geoname_id": "5080421",
58    "country_emoji": "🇺🇸"
59  },
60  "country_metadata": {
61    "calling_code": "+1",
62    "tld": ".us",
63    "languages": [
64      "en-US",
65      "es-US",
66      "haw",
67      "fr"
68    ]
69  },
70  "network": {
71    "connection_type": "",
72    "route": "145.223.7.0/24",
73    "is_anycast": false,
74    "is_cdn": false,
75    "cdn_provider_name": ""
76  },
77  "currency": {
78    "code": "USD",
79    "name": "US Dollar",
80    "symbol": "$"
81  },
82  "asn": {
83    "as_number": "AS209854",
84    "organization": "Cyberzone S.A.",
85    "country": "PA",
86    "type": "ISP",
87    "domain": "cyberzonehub.com",
88    "date_allocated": "2018-11-21",
89    "rir": "RIPE"
90  },
91  "company": {
92    "name": "Brander Group Inc.",
93    "type": "BUSINESS",
94    "domain": "brandergroup.net"
95  },
96  "time_zone": {
97    "name": "America/Chicago",
98    "offset": -6,
99    "offset_with_dst": -5,
100    "current_time": "2026-09-07 09:55:30.103-0500",
101    "current_time_unix": 1788792930.103,
102    "current_tz_abbreviation": "CDT",
103    "current_tz_full_name": "Central Daylight Time",
104    "standard_tz_abbreviation": "CST",
105    "standard_tz_full_name": "Central Standard Time",
106    "is_dst": true,
107    "dst_savings": 1,
108    "dst_exists": true,
109    "dst_tz_abbreviation": "CDT",
110    "dst_tz_full_name": "Central Daylight Time",
111    "dst_start": {
112      "utc_time": "2026-03-08 TIME 08:00",
113      "duration": "+1.00H",
114      "gap": true,
115      "date_time_after": "2026-03-08 TIME 03:00",
116      "date_time_before": "2026-03-08 TIME 02:00",
117      "overlap": false
118    },
119    "dst_end": {
120      "utc_time": "2026-11-01 TIME 07:00",
121      "duration": "-1.00H",
122      "gap": false,
123      "date_time_after": "2026-11-01 TIME 01:00",
124      "date_time_before": "2026-11-01 TIME 02:00",
125      "overlap": true
126    }
127  }
128}

Reference to IP Security API Response

Below, we provide separate tables for each JSON object in the response, listing all possible fields available across the security endpoint.

1. Standalone Fields Reference

Field	Type	Description	Can be empty?
ip	string	IP address that is used to lookup security information.	No

2. `security` JSON Object Reference

Field	Type	Description	Can be empty?
threat_score	number	Overall threat score for the IP address. Ranges from 0 to 100. 100 indicates the highest risk.	No
is_tor	boolean	Indicates whether the IP is a Tor exit node.	No
is_proxy	boolean	Indicates whether the IP is associated with a proxy network.	No
proxy_provider_names	array[string]	List of detected proxy provider names, when available.	Yes
proxy_confidence_score	number	Confidence score (0–100) for proxy detection, when flag is true. Defaults to 0.	No
proxy_last_seen	string	Last seen date (YYYY-MM-DD) for proxy activity, when available.	Yes
is_residential_proxy	boolean	Indicates whether the IP is associated with a residential proxy network.	No
is_vpn	boolean	Indicates whether the IP is associated with a VPN network.	No
vpn_provider_names	array[string]	List of detected VPN provider names, when available.	Yes
vpn_confidence_score	number	Confidence score (0–100) for VPN detection, when flag is true. Defaults to 0.	No
vpn_last_seen	string	Last seen date (YYYY-MM-DD) for VPN activity, when available.	Yes
is_relay	boolean	Indicates whether the IP is associated with a relay network.	No
relay_provider_name	string	Relay provider name, when available.	Yes
is_anonymous	boolean	Indicates whether the IP is anonymous. True if VPN, proxy, Tor, or relay is detected.	No
is_known_attacker	boolean	Indicates whether the IP is flagged for known attacker behavior.	No
is_bot	boolean	Indicates whether the IP is associated with bot activity.	No
bot_confidence_score	number	Confidence score (0-100) indicating how likely the IP is associated with bot activity. This field is populated only when `is_bot` is `true` . Defaults to `0` .	No
bot_operator_name	string	Name of the organization operating the bot, when available. This is typically provided only for known good bots.	Yes
bot_type	string	Type of bot activity detected, when available. See the bot_type values table below for the complete list of supported values.	Yes
is_known_good_bot	boolean	Indicates whether the bot is a declared and verifiable bot, such as a search engine crawler, monitoring service, or security scanner.	No
bot_last_seen	string	The most recent date the bot activity was observed, in `YYYY-MM-DD` format.	Yes
is_spam	boolean	Indicates whether the IP is associated with spam activity.	No
is_cloud_provider	boolean	Indicates whether the IP belongs to a cloud provider.	No
cloud_provider_name	string	Name of the Cloud Provider, if the IP address belongs to a cloud provider.	Yes
is_corporate_gateway	boolean	Indicates whether the IP is an egress address of a corporate secure web gateway (SWG), Secure Service Edge (SSE), or Secure Access Service Edge (SASE).	No
corporate_gateway_type	string	Type of corporate gateway service, when available. See the corporate_gateway_type values table below for the complete list of supported values.	Yes
corporate_gateway_provider_name	string	Name of the corporate gateway provider, when available.	Yes

3. `bot-type` values

bot_type describes what the automated client does, not whether it is welcome. Values are added over time, so treat the field as a plain string.

I. Declared bots

Bots with a published, verifiable operator, such as search engines, SEO tools and monitoring services. Returned with is_known_good_bot : true and a bot_operator_name .

Value	Description
search_engine	Indexing crawler that builds a search index, such as Googlebot, Bingbot, Applebot, or OAI-SearchBot (ChatGPT Search).
ai_crawler	Bulk crawler that collects content for AI model training, such as GPTBot or ClaudeBot. No user is waiting for the response.
ai_assistant	Request made by an AI assistant because a user asked it something, such as ChatGPT-User. A user is waiting for the response.
seo_crawler	Backlink and keyword crawler operated by an SEO platform, such as Ahrefs or Semrush.
site_monitor	Uptime or performance monitoring service, such as Pingdom or UptimeRobot.
link_preview	Fetcher that retrieves a page to generate a link preview, such as Slackbot or Twitterbot.
feed_fetcher	Fetcher for RSS feeds, podcasts, sitemaps, and site verification, including Google Feedfetcher.
archiver	Crawler that builds a public archive or research corpus, such as Common Crawl or the Wayback Machine.
ad_verification	Ad crawler or ad verification service, such as AdsBot-Google or DoubleVerify.
scanner	Internet-wide security scanner that probes hosts, ports, or URLs, such as Censys or Shodan.

II. Bad bot types

Automation with no recognized operator, from scraping to active attacks. Returned with is_known_good_bot : false ; the four attack types also set is_known_attacker : true .

Value	Description
scanner	Internet-wide probing of hosts, ports or URLs with no published operator (reconnaissance). Same value as above; use `is_known_good_bot` to tell them apart.
scraper	Automated content harvesting with no declared, identifiable operator.
exploit	Automated attempts against known vulnerabilities such as path traversal, injection or CVE probes. Returned with `is_known_attacker: true` .
credential_stuffing	Replay of stolen username and password pairs against login endpoints. Returned with `is_known_attacker: true` .
brute_force	Credential guessing against login, SSH or admin endpoints. Returned with `is_known_attacker: true` .
worm	Self-propagating infection attempts, usually from a compromised host. Returned with `is_known_attacker: true` .

4. `corporate-gateway-type` values

Value	Description
secure_web_gateway	Standard secure web gateway (SWG / SSE / SASE) egress. Employee browser traffic is proxied and inspected in the vendor's cloud, then forwarded to your site from this IP. Covers the large majority of gateway ranges.
browser_isolation	Remote browser isolation egress. The page is rendered in the vendor's cloud browser, so this IP fetches the site instead of the user's own device.

Error Codes

IP Security API returns HTTP status code 200 for a successful API request along with the response.

In case of a bad or invalid request, IP Security API returns 4xx HTTP status code along with a descriptive message explaining the reason for the error.

Below is a detailed explanation of the specific HTTP status codes and their corresponding error conditions:

HTTP Status	Description
400 Bad Request	It is returned for one of the following reasons: If the provided IPv4 or IPv6 address is invalid. If special character(s) ( ) [ ] { } \| ^ ` is passed in the API URL either as parameter or its value. Specially in case of API key. If the request payload is empty or missing, or the provided JSON does not contain the `ips` field, or the IP addresses JSON list is empty while querying the `security-bulk` endpoint. If more than 50,000 IP addresses are provided while querying from `security-bulk` endpoint.
401 Unauthorized	It is returned for one of the following reasons: If API key (as `apiKey` URL parameter) is missing from the request to IP Security API. If an invalid (a random value) API key is provided. If your account has been disabled or locked to use due to abuse or illegal activity. When the request to IP Security API is made using API key for a database subscription. When the request to IP Security API is made using a free subscription API key. When the request to IP Security API is made on the 'paused' subscription. If a domain name is passed in the `ip` parameter when making a request to the IP Security API. If you're making API requests after your subscription trial has expired. If your account's active-until date has passed and you need to renew or upgrade your subscription. If bulk IP to security lookup endpoint is called using free subscription API key. If the bulk IP to security lookup endpoint is called using Request Origin (CORS) authentication. Bulk requests require an `apiKey` and cannot be authenticated using Request Origin.
404 Not Found	It is returned for one of the following reasons: If the IPv4 or IPv6 address does not exist in our database. If the IPv4, IPv6 or domain name passed as a path variable, instead of URL parameter as `ip=` . If the wrong endpoint is called, that does not exist in our API.
405 Method Not Allowed	If wrong HTTP request method is used for calling the endpoints. Only GET and POST methods are allowed. POST method for `security-bulk` endpoint and GET method for `security` endpoint requests.
413 Content Too Large	If the passed data in the POST requests is more than the limit of the API.
415 Unsupported Media Type	If the `Content-Type` header is not set to `application/json` , while sending a request to the `security-bulk` endpoint.
423 Locked	If the passed IP address is from a bogon IP ranges, or is part of a private network.
429 Too Many Requests	It is returned for one of the following reasons: If the API usage limit has been reached for the paid subscriptions with the status 'past due', 'deleted' or 'trial expired'. If the surcharge API usage limit has been reached against the subscribed plan.
499 Client Closed Request	If the client has set the very short request or connection timeout, leading to the server closing the request prematurely.
5XX Server Side Error	If a `500` (Internal Server Error), `502` (Bad Gateway), `503` (Service Unavailable), `504` (Gateway Timeout), or `505` (HTTP Version Not Supported) status code is returned, it indicates an issue on our end. Please contact us with your request at support@ipgeolocation.io for further assistance.

API SDKs

To facilitate the developers, we have added some SDKs for various programming languages. The detailed documentation on how to use these SDKs is available in the respective SDK's documentation page linked below.

Our SDKs are also available on GitHub. Feel free to help us improve them. Following are the available SDKs:

Frequently Asked Questions

Each Security lookup costs 2 credits per valid IP. The X-Credits-Charged response header shows the total credits charged for the request. For details, please refer to our Credits Usage Guide.

In bulk lookup, 2 credits are charged for each valid IP in the payload. Bogon, private, or malformed IPs are not counted. The X-Credits-Charged response header shows the total credits charged for the request. For details, please refer to our Credits Usage Guide.

A confidence score is a 0 to 100 indicator of how strongly a signal (for example, VPN, proxy or bot) is detected.

A score of 0 is the default value when the related detection flag is false.

Please use the Threat Score as a quick way to route traffic, and then use the flags to understand why. Each team uses the score differently depending on the product and the risk level of the action. For example, is_anonymous can be true when is_proxy or is_tor is true. If is_proxy is true, the IP is using a proxy route, which can be a commercial or residential proxy, and that can be determined by the is_residential_proxy flag. Use the separate flags to know what else it is: is_vpn, is_residential_proxy, or is_relay. Use these details to decide when to allow, challenge, restrict, or block, especially for sensitive actions.

is_anonymous indicates that the connection is using an anonymizing route such as a VPN, proxy, relay, or Tor. Many teams use it as a quick signal to apply extra verification on sensitive endpoints.
Corporate gateway IPs are not anonymous: the ranges are published by the vendor and belong to an identifiable enterprise, so is_anonymous remains false even though many users share the address.

A relay is a privacy-focused routing service that can mask the original IP, similar to how a VPN or proxy hides location. Relays are often used for privacy and tracking protection, and they can also be used to bypass controls.

Proxy: Forwards traffic through another server and mainly masks the IP.
VPN: Routes traffic through a remote server and encrypts and tunnels the connection.
Tor: Routes traffic through multiple nodes to provide stronger anonymity.

Our security data is updated at least twice every 24 hours to capture changes across IP ranges. Downloadable security databases are available with daily and weekly update options, depending on your plan. Please see the Security Databases documentation for update details.

is_bot says automated activity is associated with the IP. is_known_good_bot says the operator is declared and verifiable, such as a search engine crawler, an uptime or SEO service, or an internet-wide security scanner, usually because the operator publishes the IP range itself. When it is true , bot_operator_name and bot_type identify the bot. When is_bot is true and is_known_good_bot is false , the traffic is automated but has no recognized legitimate operator, and your own bot policy applies.

bot_type tells you what kind of automation was seen, for example search_engine , scanner or brute_force . It describes the activity, not whether it is welcome: a scanner can be a published security research service or reconnaissance, so pair it with is_known_good_bot and is_known_attacker . Attack types such as exploit , credential_stuffing , brute_force and worm are always returned with is_known_attacker: true . See the bot_type values table in the Reference section for the full list.

A corporate gateway is the egress IP of an enterprise secure web gateway (SWG / SSE / SASE) such as Zscaler or Netskope. Employee traffic is routed through the vendor's cloud for inspection and reaches your site from the vendor's address space, so the IP belongs to the security vendor while the user is a company employee. is_corporate_gateway marks these IPs, corporate_gateway_type tells you whether it is a standard web gateway or a remote browser isolation service, and corporate_gateway_provider_name names the vendor.

No. One gateway IP can front an entire workforce, so blocking it locks out a whole organization. Treat the flag as a reason to relax per-IP rate limits, to avoid using the IP for per-user identity or deduplication, and to expect the geolocation to be the gateway location rather than the user's own city or country. Corporate gateways are not anonymity services, so is_anonymous stays false and the gateway flag alone does not raise threat_score

We refresh security data regularly and track VPNs, proxies, relays, and Tor exit nodes as providers add and rotate IP ranges. Like any IP-based detection, results can change over time, so we recommend monitoring outcomes and tuning your policy based on real traffic.

Our Security data is available on all paid plans. See our pricing page for details. We charge 2 credits per valid IP lookup for the Security data. If you include Security data in the /ipgeo endpoint, an additional 2 credits will be charged. The X-Credits-Charged response header shows the total credits charged for the request. To understand credits in detail, please refer to Credits Usage Guide.

Yes. Along with the Threat Score, the API returns flags such as VPN or proxy usage, relay signals, Tor, bot activity with the bot type and operator, spam indicators, known attacker signals, cloud hosting context and corporate gateway context. These fields help you understand what was detected and support auditing and logging.

Tor is a privacy network that routes traffic through multiple nodes to make tracking harder. A Tor exit node is the last node that reaches the public internet, so websites typically see the exit node IP instead of the user’s real IP.

Yes. The API detects free and paid VPNs, commercial and residential proxies, privacy relays, and Tor exit nodes. It also returns related risk signals such as bot indicators, spam signals, known attacker flags, and anonymity status.

No. The API does not block anything. Well-known search engine crawlers and other declared bots are returned with is_bot : true and is_known_good_bot : true , together with the bot_operator_name and bot_type. Use is_known_good_bot to allow legitimate crawlers, monitors and security scanners while applying your own bot policy when is_bot is true and is_known_good_bot is false.

Yes. A free trial is available so you can test accuracy and integration. Please contact us via customer support or use the live chat on our website to request access.

Yes. You can download sample VPN and proxy data that includes the same risk flags returned by this API, so you can review the structure and quality. Please see Security Databases for examples and formats, or contact support if you want help choosing the right dataset or if you want data for your own IP ranges.

Proxy & VPN Detection APIwith Threat Scoring

Looking for features, modules, and use cases? Visit the IP Security API page.

Explore IP Security API

IP Security API

Overview

IP Security API Lookup Endpoints

Single IP Lookup Endpoint

1. Lookup the Caller IP (No ip Parameter)

2. Lookup a Specific IP Address

3. Bot Activity Lookup

I. Bad bot activity

II. Known good bot activity

4. Lookup a Corporate Gateway IP

Additional Query Parameters

1. Exclude Fields ( excludes )

2. Return Specific Fields ( fields )

Bulk IP Security Lookup Endpoint

1. Bulk lookup request

2. Bulk Lookup with Additional Request Parameters

I. Using fields Parameter

II. Using excludes Parameter

3. Bulk Lookup Response for Invalid IPs

Security Details in Main IPGeolocation Endpoint

Reference to IP Security API Response

1. Standalone Fields Reference

2. security JSON Object Reference

3. bot-type values

I. Declared bots

II. Bad bot types

4. corporate-gateway-type values

Error Codes

API SDKs

Frequently Asked Questions

Subscribe to Our Newsletter

1. Lookup the Caller IP (No `ip` Parameter)

1. Exclude Fields ( `excludes` )

2. Return Specific Fields ( `fields` )

2. `security` JSON Object Reference

3. `bot-type` values

4. `corporate-gateway-type` values