IP Security API for Precise VPN & Proxy Detection

Protect your application with real-time IP risk intelligence. Our IP Security API detects VPNs, proxies (commercial and residential), relays, Tor exit nodes, bots, spam, hosting, and abusive IPs, and returns a dynamic Threat Score (0–100) with provider attribution, plus optional network, geolocation, time zone, and user agent context.

Get Free API Access
    • stringip:"216.73.216.43",
    • stringhostname:"216.73.216.43",
    • objectsecurity:Object,
      • numberthreat_score:5,
      • booleanis_tor:false,
      • booleanis_proxy:false,
      • stringproxy_type:"",
      • stringproxy_provider:"",
      • booleanis_anonymous:false,
      • booleanis_known_attacker:false,
      • booleanis_spam:false,
      • booleanis_bot:false,
      • booleanis_cloud_provider:true,
      • stringcloud_provider:"Amazon.com, Inc.",
    • objectlocation:Object,
      • stringcontinent_code:"NA",
      • stringcontinent_name:"North America",
      • stringcountry_code2:"US",
      • stringcountry_code3:"USA",
      • stringcountry_name:"United States",
      • stringcountry_name_official:"United States of America",
      • stringcountry_capital:"Washington, D.C.",
      • stringstate_prov:"Ohio",
      • stringstate_code:"US-OH",
      • stringdistrict:"Franklin",
      • stringcity:"Columbus",
      • stringzipcode:"43215",
      • stringlatitude:"39.96199",
      • stringlongitude:"-83.00275",
      • booleanis_eu:false,
      • stringcountry_flag:"https://ipgeolocation.io/static/flags/us_64.png",
      • stringgeoname_id:"4516394",
      • stringcountry_emoji:"🇺🇸",
    • objectcountry_metadata:Object,
      • stringcalling_code:"+1",
      • stringtld:".us",
      • languages:Array[4],
        • stringlanguages[0]:"en-US",
        • stringlanguages[1]:"es-US",
        • stringlanguages[2]:"haw",
        • stringlanguages[3]:"fr",
    • objectnetwork:Object,
      • objectasn:Object,
        • stringas_number:"AS16509",
        • stringorganization:"Amazon.com, Inc.",
        • stringcountry:"US",
      • objectcompany:Object,
        • stringname:"Anthropic, PBC",
    • objectcurrency:Object,
      • stringcode:"USD",
      • stringname:"US Dollar",
      • stringsymbol:"$",
    • objecttime_zone:Object,
      • stringname:"America/New_York",
      • numberoffset:-5,
      • numberoffset_with_dst:-5,
      • stringcurrent_time:"2026-02-07 01:53:15.718-0500",
      • numbercurrent_time_unix:1770447195.718,
      • stringcurrent_tz_abbreviation:"EST",
      • stringcurrent_tz_full_name:"Eastern Standard Time",
      • stringstandard_tz_abbreviation:"EST",
      • stringstandard_tz_full_name:"Eastern Standard Time",
      • booleanis_dst:false,
      • numberdst_savings:0,
      • booleandst_exists:true,
      • stringdst_tz_abbreviation:"EDT",
      • stringdst_tz_full_name:"Eastern Daylight Time",
      • objectdst_start:Object,
        • stringutc_time:"2026-03-08 TIME 07",
        • stringduration:"+1H",
        • booleangap:true,
        • stringdate_time_after:"2026-03-08 TIME 03",
        • stringdate_time_before:"2026-03-08 TIME 02",
        • booleanoverlap:false,
      • objectdst_end:Object,
        • stringutc_time:"2026-11-01 TIME 06",
        • stringduration:"-1H",
        • booleangap:false,
        • stringdate_time_after:"2026-11-01 TIME 01",
        • stringdate_time_before:"2026-11-01 TIME 02",
        • booleanoverlap:true,
    • objectuser_agent:Object,
      • stringuser_agent_string:"Mozilla/5.0 AppleWebKit/537.36 (KHTML, like Gecko; compatible; ClaudeBot/1.0; +claudebot@anthropic.c...",
      • stringname:"ClaudeBot",
      • stringtype:"Robot",
      • stringversion:"1.0",
      • stringversion_major:"1",
      • objectdevice:Object,
        • stringname:"Anthropic ClaudeBot",
        • stringtype:"Robot",
        • stringbrand:"Anthropic",
        • stringcpu:"Unknown",
      • objectengine:Object,
        • stringname:"ClaudeBot",
        • stringtype:"Robot",
        • stringversion:"1.0",
        • stringversion_major:"1",
      • objectoperating_system:Object,
        • stringname:"Cloud",
        • stringtype:"Cloud",
        • stringversion:"??",
        • stringversion_major:"??",
        • stringbuild:"??",

    • IP Security Lookup

    Our VPN and proxy detection API evaluates IP risk in real time and returns a Threat Score from 0 to 100 along with key risk flags. It classifies traffic as VPN, PROXY (including commercial and residential proxy networks), or RELAY and returns the provider name when available. It also flags Tor exit nodes, bots, spam sources, anonymous connections, known attacker signals, and cloud-provider hosting, including the cloud provider name when detected. By using our VPN and proxy detection software, you can stop fraud at the edge by identifying high-risk anonymous and masked traffic before it reaches your application.

    Our data-driven Threat Score aggregates telemetry from active honeypots, proprietary blocklists, VPN and proxy enumeration, and real-time behavioral analysis to produce a single risk score per IP.

    Request
    curl -X GET 'https://api.ipgeolocation.io/v2/security?apiKey=API_KEY&ip=2.56.188.34'
    Response
    1{
2  "ip": "2.56.188.34",
3  "security": {
4    "threat_score": 75,
5    "is_tor": false,
6    "is_proxy": true,
7    "proxy_type": "VPN",
8    "proxy_provider": "Nord VPN",
9    "is_anonymous": true,
10    "is_known_attacker": true,
11    "is_spam": false,
12    "is_bot": false,
13    "is_cloud_provider": true,
14    "cloud_provider": "Packethub S.A."
15  }
16}

    Residential Proxy Detection

    Standard proxy detection can miss abuse routed through residential proxy networks on consumer ISP connections. Our VPN and Proxy Detection API helps you identify both datacenter-hosted proxy traffic and residential proxy networks in the same API call by returning proxy provider attribution when available (for example, Evomi or Oxylabs), so you can apply the right policy for each risk profile. This capability is critical for preventing account takeovers (ATO), credential stuffing, and ad fraud, where attackers deliberately blend in behind legitimate-looking ISP assignments.

    The example shows an IP tied to an ISP in the network ownership details, yet our API still flags it as a PROXY because it is being routed through a proxy provider, as indicated by the provider name.

    Request
    curl -X GET 'https://api.ipgeolocation.io/v2/security?apiKey=API_KEY&ip=152.58.153.65&include=network'
    Response
    1{
2  "ip": "152.58.153.65",
3  "security": {
4    "threat_score": 50,
5    "is_tor": false,
6    "is_proxy": true,
7    "proxy_type": "PROXY",
8    "proxy_provider": "922 Proxy",
9    "is_anonymous": true,
10    "is_known_attacker": false,
11    "is_spam": false,
12    "is_bot": false,
13    "is_cloud_provider": false,
14    "cloud_provider": ""
15  },
16  "network": {
17    "asn": {
18      "as_number": "AS55836",
19      "organization": "Reliance Jio Infocomm Limited",
20      "country": "IN"
21    },
22    "company": {
23      "name": "Reliance Jio Infocomm Limited"
24    }
25  }
26}

    IP Security With Network Details

    The API provides both the Autonomous System (AS) Number and organization details about the specified IP address. The API response provides network identification data about the IP address which enables easier detection of service providers as well as potential malicious networks.

    Enriching security data with AS number details helps detect risky patterns and supports proactive threat response. Blocking dangerous IP ranges, along with restricting access to IPs associated with specific AS numbers, organizations, or ISPs, helps enhance your cyber security posture.

    Request
    curl -X GET 'https://api.ipgeolocation.io/v2/security?apiKey=API_KEY&ip=2.56.188.34&include=network'
    Response
    1{
2  "ip": "2.56.188.34",
3  "security": {
4    "threat_score": 75,
5    "is_tor": false,
6    "is_proxy": true,
7    "proxy_type": "VPN",
8    "proxy_provider": "Nord VPN",
9    "is_anonymous": true,
10    "is_known_attacker": true,
11    "is_spam": false,
12    "is_bot": false,
13    "is_cloud_provider": true,
14    "cloud_provider": "Packethub S.A."
15  },
16  "network": {
17    "asn": {
18      "as_number": "3640",
19      "organization": "C I C E S E",
20      "country": "MX"
21    },
22    "company": {
23      "name": "Packethub S.A."
24    }
25  }
26}

    IP Security With Geolocation

    The geolocation information for the provided IP can also be included in the default response of the Security API. The geolocation data contains the country, state, city, and ZIP code, along with the latitude and longitude of the IP address. This cybersecurity intelligence helps identify region-specific threats and block high-risk IPs by location.

    Request
    curl -X GET 'https://api.ipgeolocation.io/v2/security?apiKey=API_KEY&ip=2.56.188.34&include=location'
    Response
    1{
2  "ip": "2.56.188.34",
3  "security": {
4    "threat_score": 75,
5    "is_tor": false,
6    "is_proxy": true,
7    "proxy_type": "VPN",
8    "proxy_provider": "Nord VPN",
9    "is_anonymous": true,
10    "is_known_attacker": true,
11    "is_spam": false,
12    "is_bot": false,
13    "is_cloud_provider": true,
14    "cloud_provider": "Packethub S.A."
15  },
16  "location": {
17    "continent_code": "OC",
18    "continent_name": "Oceania",
19    "country_code2": "AU",
20    "country_code3": "AUS",
21    "country_name": "Australia",
22    "country_name_official": "Commonwealth of Australia",
23    "country_capital": "Canberra",
24    "state_prov": "Queensland",
25    "state_code": "AU-QLD",
26    "district": "",
27    "city": "Brisbane",
28    "zipcode": "4101",
29    "latitude": "-27.47306",
30    "longitude": "153.01421",
31    "is_eu": false,
32    "country_flag": 
33      "https://ipgeolocation.io/static/flags/au_64.png",
34    "geoname_id": "10113228",
35    "country_emoji": "🇦🇺"
36  }
37}

    Bulk IP Security Lookup

    Our IP Security API allows you to retrieve security details for up to 50,000 IPs at once using the bulk lookup feature. This powerful capability saves time and enables users to analyze large volumes of IP behavior patterns quickly and efficiently. Through bulk IP security lookups, organizations can detect VPN usage at scale, perform VPN checks, identify proxies, bots, and known attackers across large datasets, and automate threat detection workflows for real-time security monitoring.

    Whether you're monitoring user activity, blocking suspicious traffic, or conducting cybersecurity audits, the bulk lookup API is built to support high-performance threat intelligence operations.

    Request
    curl -X POST 'https://api.ipgeolocation.io/v2/security-bulk?apiKey=API_KEY' -H 'Content-Type: application/json' -d '{
  "ips": ["1.0.0.0", "1.0.0.1", "1.0.0.2"]
}'
    Response
    1[
2    {
3        "ip": "1.0.0.0",
4        "security": {
5            "threat_score": 5,
6            "is_tor": false,
7            "is_proxy": false,
8            "proxy_type": "",
9            "proxy_provider": "",
10            "is_anonymous": false,
11            "is_known_attacker": false,
12            "is_spam": false,
13            "is_bot": false,
14            "is_cloud_provider": true,
15            "cloud_provider": "Cloudflare, Inc."
16        }
17    },
18    {
19        "ip": "1.0.0.1",
20        "security": {
21            "threat_score": 5,
22            "is_tor": false,
23            "is_proxy": false,
24            "proxy_type": "",
25            "proxy_provider": "",
26            "is_anonymous": false,
27            "is_known_attacker": false,
28            "is_spam": false,
29            "is_bot": false,
30            "is_cloud_provider": true,
31            "cloud_provider": "Cloudflare, Inc."
32        }
33    },
34    {
35        "ip": "1.0.0.2",
36        "security": {
37            "threat_score": 5,
38            "is_tor": false,
39            "is_proxy": false,
40            "proxy_type": "",
41            "proxy_provider": "",
42            "is_anonymous": false,
43            "is_known_attacker": false,
44            "is_spam": false,
45            "is_bot": false,
46            "is_cloud_provider": true,
47            "cloud_provider": "Cloudflare, Inc."
48        }
49    }
50]

    Response in Multiple Languages

    You can retrieve the geolocation information for an IP address in the following languages:

    • English FlagEnglish
    • German FlagGerman
    • Russian FlagRussian
    • Japanese FlagJapanese
    • French FlagFrench
    • Chinese Simplified FlagChinese Simplified
    • Spanish FlagSpanish
    • Czech Republic FlagCzech Republic
    • Italian FlagItalian
    • Korean FlagKorean
    • Persian FlagPersian
    • Portuguese FlagPortuguese
    • Standard Arabic FlagStandard Arabic

    Use Cases

    Preventing Account Takeover (ATO)

    When a user attempts to log in, their IP address can be analyzed for threat level, proxy or VPN usage, and whether it is associated with known attackers, spam, or bots. Leveraging advanced VPN detection, this API stands out as one of the most reliable VPN detector services.

    It plays a key role in controlling unauthorized logins and reducing the risk of multiple account creation. This use case is especially important for banking platforms, SaaS applications, and any user-based systems where security and identity integrity are paramount.

    Account Takeover Prevention image

    Reducing Chargebacks & Payments Fraud Prevention

    During the checkout process, the API works as a reliable proxy checker by analyzing the customer’s IP address. It can detect whether the IP is associated with a VPN, proxy, Tor, bot, spam, cloud provider, or shows a suspicious location mismatch. This helps prevent fraudulent transactions, such as fake orders or the use of stolen credit cards, protecting both your business and your customers.

    Reducing Chargebacks & Payment Fraud Prevention image

    Digital Rights Management (DRM)

    Prevent geo-circumvention by detecting VPNs used to access region-locked content. Use our VPN & Proxy Detection API during playback, login, or download events to identify VPN, proxy, relay, or Tor traffic and evaluate the Threat Score. Combine these signals with geolocation to enforce licensing rules by country or region, and apply policies such as blocking access, step-up verification, or session limits when high-risk anonymized traffic is detected.

    Digital Rights Management image

    Real-Time Chat & Community Filtering

    Before allowing users to send messages or join live chats, you can leverage the API’s bot detection and threat analysis features to evaluate their IP address. This helps identify spammy behavior, anonymous access, or any history of malicious activity. It ensures a safer and more trustworthy environment for gaming platforms, community forums, and live chat applications.

    Chat Protection image

    Location Based Restriction

    Combining geolocation data with security analysis provides a more comprehensive defense against privacy and security threats. The combination of geolocation with IP address security features enables you to make stronger security decisions.The method proves useful in blocking specific regions that take part in harmful activities thus minimizing security threats.

    Location Based Restriction image

    AS Number Based Protection

    Our IP Security API not only provides the AS Number but also reveals the associated ASN organization and company name, along with detailed security insights and geolocation data. This empowers security teams to identify and block entire networks or specific organizations involved in malicious activity. It allows for broader, more accurate, and proactive threat mitigation through enhanced visibility and context.

    AS Number Based Protection image

    Ready to get started? Get Started with IP Security API Today

    Enrich every request with precise geolocation and real-time threat intelligence, delivered on a global edge with a 99.99% uptime SLA. Start free and scale when you’re ready.

    Get Started
    CTA Illustration
    CTA Illustration

    Documentation

    IP Security API

    Overview

    The IP Security API returns detailed threat flags for any IPv4 or IPv6 address. It detects whether an IP is associated with a VPN, proxy (including residential proxies), Tor exit node, bot activity, spam activity, or known attacker behavior. This helps you reliably identify anonymous and masked traffic before it reaches your systems.

    The API also checks whether the IP is linked to a cloud provider and, when available, returns the cloud provider name. For additional context in the same request, developers can optionally include geolocation, network details (company and ASN information), time zone, and user agent data.

    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.

    Important

    Please note the following:

    • After adding your website as a Request Origin in the Billing Dashboard, you can call the endpoints below directly from the client-side without including the apiKey query parameter to help prevent unauthorized use of your API key.
    • Base URL (v2): https://api.ipgeolocation.io/v2/security
    • Responses are returned in JSON by default. To receive XML, add output=xml . You can also explicitly request JSON with output=json .
    Note
    is_proxy is true when the IP uses any of these anonymizing routes: VPN (encrypted), PROXY (including residential proxies), or RELAY (privacy relays). proxy_type indicates the route type: VPN, PROXY, or RELAY. It is empty when is_proxy is false (no VPN, proxy, or relay).

    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 indicators and the provider name when available). Use this option when you want to assess the IP risk of the requesting client without specifying an IP address.

    cUrl
    curl -X GET 'https://api.ipgeolocation.io/v2/security?apiKey=API_KEY'
    Response
    1{
2  "ip": "207.244.89.161",
3  "security": {
4    "threat_score": 90,
5    "is_tor": false,
6    "is_proxy": true,
7    "proxy_type": "VPN",
8    "proxy_provider": "Vpnsurf VPN",
9    "is_anonymous": true,
10    "is_known_attacker": true,
11    "is_spam": true,
12    "is_bot": false,
13    "is_cloud_provider": false,
14    "cloud_provider": ""
15  }
16}

    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/Tor/bot/spam/hosting flags and the provider name when available).

    cUrl
    curl -X GET 'https://api.ipgeolocation.io/v2/security?apiKey=API_KEY&ip=2.56.188.34'
    Response
    1{
2  "ip": "2.56.188.34",
3  "security": {
4    "threat_score": 75,
5    "is_tor": false,
6    "is_proxy": true,
7    "proxy_type": "VPN",
8    "proxy_provider": "Nord VPN",
9    "is_anonymous": true,
10    "is_known_attacker": true,
11    "is_spam": false,
12    "is_bot": false,
13    "is_cloud_provider": true,
14    "cloud_provider": "Packethub S.A."
15  }
16}

    Additional Query Parameters

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

    1.Include Additional Data ( include )

    Use include to add extra data to the response. You can pass one or more comma-separated values.

    Available values:

    • Enrichment data: location , network , currency , time_zone , user_agent , country_metadata
    • Hostname options: hostname , liveHostname , hostnameFallbackLive

    Examples and details for each value are provided in the sections below.

    I.Combine IP Security with Geolocation

    Add include=location to return geolocation data along with the default security response.

    The response includes a location object in addition to ip and security .

    An example request and response are shown below.

    cUrl
    curl -X GET 'https://api.ipgeolocation.io/v2/security?apiKey=API_KEY&ip=2.56.188.34&include=location'
    Response
    1{
2  "ip": "2.56.188.34",
3  "security": {
4    "threat_score": 75,
5    "is_tor": false,
6    "is_proxy": true,
7    "proxy_type": "VPN",
8    "proxy_provider": "Nord VPN",
9    "is_anonymous": true,
10    "is_known_attacker": true,
11    "is_spam": false,
12    "is_bot": false,
13    "is_cloud_provider": true,
14    "cloud_provider": "Packethub S.A."
15  },
16  "location": {
17    "continent_code": "OC",
18    "continent_name": "Oceania",
19    "country_code2": "AU",
20    "country_code3": "AUS",
21    "country_name": "Australia",
22    "country_name_official": "Commonwealth of Australia",
23    "country_capital": "Canberra",
24    "state_prov": "Queensland",
25    "state_code": "AU-QLD",
26    "district": "",
27    "city": "Brisbane",
28    "zipcode": "4101",
29    "latitude": "-27.47306",
30    "longitude": "153.01421",
31    "is_eu": false,
32    "country_flag": 
33      "https://ipgeolocation.io/static/flags/au_64.png",
34    "geoname_id": "10113228",
35    "country_emoji": "🇦🇺"
36  }
37}

    II.Combine IP Security with Network Details

    Add include=network to return network details along with the default security response.

    The network object includes ASN details (AS number, organization, and ASN registration country) and company details for the IP.

    The ASN organization and company name may be the same or different, depending on how the IP range is owned or leased.

    An example request and response are shown below.

    cUrl
    curl -X GET 'https://api.ipgeolocation.io/v2/security?apiKey=API_KEY&ip=2.56.188.34&include=network'
    Response
    1{
2  "ip": "2.56.188.34",
3  "security": {
4    "threat_score": 75,
5    "is_tor": false,
6    "is_proxy": true,
7    "proxy_type": "VPN",
8    "proxy_provider": "Nord VPN",
9    "is_anonymous": true,
10    "is_known_attacker": true,
11    "is_spam": false,
12    "is_bot": false,
13    "is_cloud_provider": true,
14    "cloud_provider": "Packethub S.A."
15  },
16  "network": {
17    "asn": {
18      "as_number": "3640",
19      "organization": "C I C E S E",
20      "country": "MX"
21    },
22    "company": {
23      "name": "Packethub S.A."
24    }
25  }
26}

    III.Combine IP Security with Both Geolocation and Network Details

    Add include=location,network to return both geolocation and network details along with the default security response.

    The response includes location and network objects in addition to ip and security .

    An example request and response are shown below.

    cUrl
    curl -X GET 'https://api.ipgeolocation.io/v2/security?apiKey=API_KEY&ip=2.56.188.34&include=location,network'
    Response
    1{
2  "ip": "2.56.188.34",
3  "security": {
4    "threat_score": 75,
5    "is_tor": false,
6    "is_proxy": true,
7    "proxy_type": "VPN",
8    "proxy_provider": "Nord VPN",
9    "is_anonymous": true,
10    "is_known_attacker": true,
11    "is_spam": false,
12    "is_bot": false,
13    "is_cloud_provider": true,
14    "cloud_provider": "Packethub S.A."
15  },
16  "location": {
17    "continent_code": "OC",
18    "continent_name": "Oceania",
19    "country_code2": "AU",
20    "country_code3": "AUS",
21    "country_name": "Australia",
22    "country_name_official": "Commonwealth of Australia",
23    "country_capital": "Canberra",
24    "state_prov": "Queensland",
25    "state_code": "AU-QLD",
26    "district": "",
27    "city": "Brisbane",
28    "zipcode": "4101",
29    "latitude": "-27.47306",
30    "longitude": "153.01421",
31    "is_eu": false,
32    "country_flag": 
33      "https://ipgeolocation.io/static/flags/au_64.png",
34    "geoname_id": "10113228",
35    "country_emoji": "🇦🇺"
36  },
37  "network": {
38    "asn": {
39      "as_number": "3640",
40      "name": "C I C E S E",
41      "country": "MX"
42    },
43    "company": {
44      "name": "Packethub S.A."
45    }
46  }
47}

    IV.Combine IP Security with Time Zone Details

    Add include=time_zone to return time zone data along with the default security response.

    The response includes a time_zone object in addition to ip and security .

    An example request and response are shown below.

    cUrl
    curl -X GET 'https://api.ipgeolocation.io/v2/security?apiKey=API_KEY&ip=2.56.188.34&include=time_zone'
    Response
    1{
2  "ip": "2.56.188.34",
3  "security" : {
4    "threat_score" : 80,
5    "is_tor" : false,
6    "is_proxy" : true,
7    "proxy_type" : "VPN",
8    "proxy_provider" : "Nord VPN",
9    "is_anonymous" : true,
10    "is_known_attacker" : true,
11    "is_spam" : false,
12    "is_bot" : false,
13    "is_cloud_provider" : true,
14    "cloud_provider" : "Packethub S.A."
15  },
16  "time_zone" : {
17    "name" : "America/Chicago",
18    "offset" : -6,
19    "offset_with_dst" : -5,
20    "current_time" : "2025-05-14 06:22:30.204-0500",
21    "current_time_unix" : 1.747221750204E9,
22    "is_dst" : true,
23    "dst_savings" : 1,
24    "dst_exists" : true,
25    "dst_start" : {
26      "utc_time" : "2025-03-09 TIME 08",
27      "duration" : "+1H",
28      "gap" : true,
29      "date_time_after" : "2025-03-09 TIME 03",
30      "date_time_before" : "2025-03-09 TIME 02",
31      "overlap" : false
32    },
33    "dst_end" : {
34      "utc_time" : "2025-11-02 TIME 07",
35      "duration" : "-1H",
36      "gap" : false,
37      "date_time_after" : "2025-11-02 TIME 01",
38      "date_time_before" : "2025-11-02 TIME 02",
39      "overlap" : true
40    }
41  }
42}

    V.Combine IP Security with User Agent

    Add include=user_agent to include parsed user agent details in the response.

    If you do not send a User-Agent header, the API uses the user agent of the requesting client and parses it automatically. This is useful for client-side requests.

    For server-side requests, send the visitor’s User-Agent value in the User-Agent header so the API returns details for the correct user.

    i.Without a User-Agent header

    The API parses the user agent of the requesting client.

    An example request and response are shown below.

    cUrl
    curl -X GET 'https://api.ipgeolocation.io/v2/security?apiKey=API_KEY&ip=2.56.188.34&include=user_agent'
    Response
    1{
2  "ip": "2.56.188.34",
3  "security" : {
4    "threat_score" : 80,
5    "is_tor" : false,
6    "is_proxy" : true,
7    "proxy_type" : "VPN",
8    "proxy_provider" : "Nord VPN",
9    "is_anonymous" : true,
10    "is_known_attacker" : true,
11    "is_spam" : false,
12    "is_bot" : false,
13    "is_cloud_provider" : true,
14    "cloud_provider" : "Packethub S.A."
15  },
16"user_agent" : {
17    "user_agent_string" : "Mozilla/5.0 (X11; Ubuntu; Linux x86_64; rv:138.0) Gecko/20100101 Firefox/138.0",
18    "name" : "Firefox",
19    "type" : "Browser",
20    "version" : "138.0",
21    "version_major" : "138",
22    "device" : {
23      "name" : "Linux Desktop",
24      "type" : "Desktop",
25      "brand" : "Unknown",
26      "cpu" : "Intel x86_64"
27    },
28    "engine" : {
29      "name" : "Gecko",
30      "type" : "Browser",
31      "version" : "138.0",
32      "version_major" : "138"
33    },
34    "operating_system" : {
35      "name" : "Ubuntu",
36      "type" : "Desktop",
37      "version" : "??",
38      "build" : "??",
39      "version_major" : "??"
40    }
41  }
42}
    ii.With a User-Agent header

    The API parses the user agent value you provide in the User-Agent header.

    An example request and response are shown below.

    cUrl
    curl -X GET 'https://api.ipgeolocation.io/v2/security?apiKey=API_KEY&ip=2.56.188.34&include=user_agent' \
-H 'User-Agent: Mozilla/5.0 (Android 4.4; Mobile; rv:41.0) Gecko/41.0 Firefox/41.0'
    Response
    1{
2    "ip": "2.56.188.34",
3    "security": {
4        "threat_score": 80,
5        "is_tor": false,
6        "is_proxy": true,
7        "proxy_type": "VPN",
8        "proxy_provider": "Nord VPN",
9        "is_anonymous": true,
10        "is_known_attacker": true,
11        "is_spam": false,
12        "is_bot": false,
13        "is_cloud_provider": true,
14        "cloud_provider": "Packethub S.A."
15    },
16    "user_agent": {
17        "user_agent_string": "Mozilla/5.0 (Android 4.4; Mobile; rv:41.0) Gecko/41.0 Firefox/41.0",
18        "name": "Firefox",
19        "type": "Browser",
20        "version": "41.0",
21        "version_major": "41",
22        "device": {
23            "name": "Android Mobile",
24            "type": "Phone",
25            "brand": "Unknown",
26            "cpu": "Unknown"
27        },
28        "engine": {
29            "name": "Gecko",
30            "type": "Browser",
31            "version": "41.0",
32            "version_major": "41"
33        },
34        "operating_system": {
35            "name": "Android",
36            "type": "Mobile",
37            "version": "4.4",
38            "version_major": "4",
39            "build": "??"
40        }
41    }
42}

    VI.Combine IP Security with Currency Details

    Add include=currency to return currency details along with the default security response.

    The response includes a currency object in addition to ip and security .

    An example request and response are shown below.

    cUrl
    curl -X GET 'https://api.ipgeolocation.io/v2/security?apiKey=API_KEY&ip=2.56.188.34&include=currency'
    Response
    1{
2  "ip": "2.56.188.34",
3  "security" : {
4    "threat_score" : 80,
5    "is_tor" : false,
6    "is_proxy" : true,
7    "proxy_type" : "VPN",
8    "proxy_provider" : "Nord VPN",
9    "is_anonymous" : true,
10    "is_known_attacker" : true,
11    "is_spam" : false,
12    "is_bot" : false,
13    "is_cloud_provider" : true,
14    "cloud_provider" : "Packethub S.A."
15  },
16  "currency" : {
17    "code" : "USD",
18    "name" : "US Dollar",
19    "symbol" : "$"
20  }
21}

    VII.Combine IP Security with Country Metadata Details

    Add include=country_metadata to return country metadata along with the default security response.

    The response includes a country_metadata object in addition to ip and security .

    An example request and response are shown below.

    cUrl
    curl -X GET 'https://api.ipgeolocation.io/v2/security?apiKey=API_KEY&ip=2.56.188.34&include=country_metadata'
    Response
    1{
2  "ip": "2.56.188.34",
3  "security" : {
4    "threat_score" : 80,
5    "is_tor" : false,
6    "is_proxy" : true,
7    "proxy_type" : "VPN",
8    "proxy_provider" : "Nord VPN",
9    "is_anonymous" : true,
10    "is_known_attacker" : true,
11    "is_spam" : false,
12    "is_bot" : false,
13    "is_cloud_provider" : true,
14    "cloud_provider" : "Packethub S.A."
15  },
16  "country_metadata" : {
17    "tld" : ".us",
18    "languages" : ["en-US", "es-US", "haw", "fr"],
19    "calling_code" : "+1"
20  }
21}

    VIII.Combine IP Security with Hostname

    You can also include the hostname for the queried IP address.

    Use one of the following values in include :

    1. hostname – Returns the hostname from our local IP-to-hostname database.
    2. liveHostname – Performs a live hostname lookup.
    3. hostnameFallbackLive – Checks the local database first, then falls back to a live lookup if no result is found.

    An example request and response are shown below.

    cUrl
    curl -X GET 'https://api.ipgeolocation.io/v2/security?apiKey=API_KEY&ip=195.154.221.54&include=hostname'
    Response
    1{
2"ip" : "195.154.221.54",
3 "hostname" : "195-154-221-54.rev.poneytelecom.eu",
4 "security" : {
5    "threat_score" : 50,
6    "is_tor" : false,
7    "is_proxy" : true,
8    "proxy_type" : "VPN",
9    "proxy_provider" : "Keep Solid VPN",
10    "is_anonymous" : true,
11    "is_known_attacker" : false,
12    "is_spam" : false,
13    "is_bot" : false,
14    "is_cloud_provider" : true,
15    "cloud_provider" : "Scaleway"
16  }
17}
    Note
    Hostname behavior: If a hostname cannot be resolved, the API returns the queried IP address in the hostname field.

    IX.Combine IP Security with All Fields

    Use this option when you want security signals plus all available enrichment data in a single response.

    Set the include parameter to include every optional object:

    include=location,network,currency,time_zone,user_agent,country_metadata,hostname

    An example request and response are shown below.

    cUrl
    curl -X GET 'https://api.ipgeolocation.io/v2/security?apiKey=API_KEY&ip=195.154.221.54&include=location,network,currency,time_zone,user_agent,country_metadata,hostname'
    Response
    1{
2  "ip": "195.154.221.54",
3  "hostname": "195-154-221-54.rev.poneytelecom.eu",
4  "security": {
5    "threat_score": 50,
6    "is_tor": false,
7    "is_proxy": true,
8    "proxy_type": "VPN",
9    "proxy_provider": "Keep Solid VPN",
10    "is_anonymous": true,
11    "is_known_attacker": false,
12    "is_spam": false,
13    "is_bot": false,
14    "is_cloud_provider": true,
15    "cloud_provider": "Scaleway"
16  },
17  "location": {
18    "continent_code": "EU",
19    "continent_name": "Europe",
20    "country_code2": "FR",
21    "country_code3": "FRA",
22    "country_name": "France",
23    "country_name_official": "Republic of France",
24    "country_capital": "Paris",
25    "state_prov": "Ile-de-France",
26    "state_code": "FR-IDF",
27    "district": "8e Arrondissement",
28    "city": "Paris",
29    "zipcode": "75008",
30    "latitude": "48.87135",
31    "longitude": "2.32115",
32    "is_eu": true,
33    "country_flag": 
34      "https://ipgeolocation.io/static/flags/fr_64.png",
35    "geoname_id": "12535167",
36    "country_emoji": "🇫🇷"
37  },
38  "country_metadata": {
39    "calling_code": "+33",
40    "tld": ".fr",
41    "languages": [
42      "fr-FR",
43      "frp",
44      "br",
45      "co",
46      "ca",
47      "eu",
48      "oc"
49    ]
50  },
51  "network": {
52    "asn": {
53      "as_number": "AS12876",
54      "organization": "SCALEWAY S.A.S.",
55      "country": "FR"
56    },
57    "company": {
58      "name": "Scaleway"
59    }
60  },
61  "currency": {
62    "code": "EUR",
63    "name": "Euro",
64    "symbol": "€"
65  },
66  "time_zone": {
67    "name": "Europe/Paris",
68    "offset": 1,
69    "offset_with_dst": 2,
70    "current_time": "2025-05-21 14:04:26.910+0200",
71    "current_time_unix": 1747829066.91,
72    "is_dst": true,
73    "dst_savings": 1,
74    "dst_exists": true,
75    "dst_start": {
76      "utc_time": "2025-03-30 TIME 01",
77      "duration": "+1H",
78      "gap": true,
79      "date_time_after": "2025-03-30 TIME 03",
80      "date_time_before": "2025-03-30 TIME 02",
81      "overlap": false
82    },
83    "dst_end": {
84      "utc_time": "2025-10-26 TIME 01",
85      "duration": "-1H",
86      "gap": false,
87      "date_time_after": "2025-10-26 TIME 02",
88      "date_time_before": "2025-10-26 TIME 03",
89      "overlap": true
90    }
91  },
92  "user_agent": {
93    "user_agent_string": "Mozilla/5.0 (X11; Ubuntu; Linux x86_64; rv:138.0) Gecko/20100101 Firefox/138.0",
94    "name": "Firefox",
95    "type": "Browser",
96    "version": "138.0",
97    "version_major": "138",
98    "device": {
99      "name": "Linux Desktop",
100      "type": "Desktop",
101      "brand": "Unknown",
102      "cpu": "Intel x86_64"
103    },
104    "engine": {
105      "name": "Gecko",
106      "type": "Browser",
107      "version": "138.0",
108      "version_major": "138"
109    },
110    "operating_system": {
111      "name": "Ubuntu",
112      "type": "Desktop",
113      "version": "??",
114      "version_major": "??",
115      "build": "??"
116    }
117  }
118}
    Note
    This returns the largest response. If you only need a few objects, include only those to reduce response size and improve performance.

    2.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 or object.nested.field . For example:

    • Exclude security flags: security.is_tor , security.is_cloud_provider
    • Exclude a location field: location.city
    • Exclude an ASN field: network.asn.as_number
    Note
    • ip is always included and cannot be excluded.
    • To exclude a field from an object that is not returned by default (for example location or network ), you must first add that object using include .

    An example request and response are shown below.

    cUrl
    curl -X GET 'https://api.ipgeolocation.io/v2/security?apiKey=API_KEY&ip=2.56.188.34&excludes=security.is_tor,security.is_cloud_provider,location.city,network.asn.as_number&include=location,network'
    Response
    1{
2    "ip": "2.56.188.34",
3    "security": {
4        "threat_score": 80,
5        "is_proxy": true,
6        "proxy_type": "VPN",
7        "proxy_provider": "Nord VPN",
8        "is_anonymous": true,
9        "is_known_attacker": true,
10        "is_spam": false,
11        "is_bot": false,
12        "cloud_provider": "Packethub S.A."
13    },
14    "location": {
15        "continent_code": "NA",
16        "continent_name": "North America",
17        "country_code2": "US",
18        "country_code3": "USA",
19        "country_name": "United States",
20        "country_name_official": "United States of America",
21        "country_capital": "Washington, D.C.",
22        "state_prov": "Texas",
23        "state_code": "US-TX",
24        "district": "Dallas",
25        "zipcode": "75201",
26        "latitude": "32.77822",
27        "longitude": "-96.79512",
28        "is_eu": false,
29        "country_flag": "https://ipgeolocation.io/static/flags/us_64.png",
30        "geoname_id": "4684902",
31        "country_emoji": "🇺🇸"
32    },
33    "network": {
34        "asn": {
35            "organization": "Clouvider Limited",
36            "country": "GB"
37        },
38        "company": {
39            "name": "Packethub S.A."
40        }
41    }
42}

    In this example, the response does not contain is_tor and is_cloud_provider in the security object, the city field in the location object, and as_number in the network.asn object.

    3.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 or object.nested.field . For example:

    • Security score: security.threat_score
    • City (from location): location.city
    • ASN number (from network): network.asn.as_number
    Note
    • To select fields from an object that is not returned by default (for example location or network ), you must first add that object using include .
    • If you request a field from an object that is not included, it will not appear in the response.

    An example request and response are shown below.

    cUrl
    curl -X GET 'https://api.ipgeolocation.io/v2/security?apiKey=API_KEY&ip=2.56.188.34&include=location,network&fields=security.threat_score,location.city,network.asn.as_number'
    Response
    1{
2  "ip": "2.56.188.34",
3  "security": {
4    "threat_score": 75
5  },
6  "location": {
7    "city": "Brisbane"
8  },
9  "network": {
10    "asn": {
11      "as_number": "AS62240"
12    }
13  }
14}

    Response in Multiple Languages ( lang )

    When you include location data, you can return location names (such as country, state, and city) in different languages using the lang query parameter.

    • English ( en )
    • German ( de )
    • Russian ( ru )
    • Japanese ( ja )
    • French ( fr )
    • Chinese (Simplified) ( cn )
    • Spanish ( es )
    • Czech ( cs )
    • Italian ( it )
    • Korean ( ko )
    • Persian ( fa )
    • Portuguese ( pt )

    By default, the API responds in English. To change the language, add lang with one of the codes above (for example, lang=cn ). An example request and response are shown below.

    Note
    lang applies to the location object only. Other objects (such as security , network etc.) are not translated.
    cUrl
    curl -X GET 'https://api.ipgeolocation.io/v2/security?apiKey=API_KEY&ip=2.56.188.34&include=location&lang=cn'
    Response
    1{
2  "ip": "2.56.188.34",
3  "security": {
4    "threat_score": 80,
5    "is_tor": false,
6    "is_proxy": true,
7    "proxy_type": "VPN",
8    "proxy_provider": "Nord VPN",
9    "is_anonymous": true,
10    "is_known_attacker": true,
11    "is_spam": false,
12    "is_bot": false,
13    "is_cloud_provider": false,
14    "cloud_provider": ""
15  },
16  "location": {
17    "continent_code": "NA",
18    "continent_name": "北美洲",
19    "country_code2": "US",
20    "country_code3": "USA",
21    "country_name": "美国",
22    "country_name_official": "",
23    "country_capital": "",
24    "state_prov": "德克萨斯州",
25    "state_code": "US-TX",
26    "district": "達拉斯縣",
27    "city": "達拉斯縣",
28    "zipcode": "75207",
29    "latitude": "32.78916",
30    "longitude": "-96.82170",
31    "is_eu": false,
32    "country_flag": 
33      "https://ipgeolocation.io/static/flags/us_64.png",
34    "geoname_id": "7181768",
35    "country_emoji": "🇺🇸"
36  }
37}

    Bulk IP Security Lookup Endpoint

    Use this endpoint to assess IP risk for large lists of IP addresses in a single request (up to 50,000 IPs per request).

    The bulk lookup supports the same query parameters as the single lookup, so you can use include , excludes , and fields to control the response. If you include location , you can also translate location names using lang .

    In the response, each IP is returned with its own security result. This makes it easy to process results in batches for signups, log analysis, fraud checks, and monitoring workflows.

    An example request and response are shown below.

    cUrl
    curl -X POST 'https://api.ipgeolocation.io/v2/security-bulk?apiKey=API_KEY&include=location,network&fields=location.city,network.asn.as_number' \
-H 'Content-Type: application/json' \
-d '{"ips":["2.56.188.34","2.56.188.35"]}'
    Response
    1[
2    {
3        "ip": "2.56.188.34",
4        "security": {
5            "threat_score": 75,
6            "is_tor": false,
7            "is_proxy": true,
8            "proxy_type": "VPN",
9            "proxy_provider": "Nord VPN",
10            "is_anonymous": true,
11            "is_known_attacker": true,
12            "is_spam": false,
13            "is_bot": false,
14            "is_cloud_provider": true,
15            "cloud_provider": "Packethub S.A."
16        },
17        "location": {
18            "city": "Los Angeles"
19        },
20        "network": {
21            "asn": {
22                "as_number": "AS62240"
23            }
24        }
25    },
26    {
27        "ip": "2.56.188.35",
28        "security": {
29            "threat_score": 75,
30            "is_tor": false,
31            "is_proxy": true,
32            "proxy_type": "VPN",
33            "proxy_provider": "Nord VPN",
34            "is_anonymous": true,
35            "is_known_attacker": true,
36            "is_spam": false,
37            "is_bot": false,
38            "is_cloud_provider": true,
39            "cloud_provider": "Packethub S.A."
40        },
41        "location": {
42            "city": "Los Angeles"
43        },
44        "network": {
45            "asn": {
46                "as_number": "AS62240"
47            }
48        }
49    }
50]
    Note
    Quota and billing: In bulk lookup, the number of requests counted toward your quota equals the number of valid IP addresses in the payload. Bogon, private, or malformed IPs are not counted.

    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

    FieldTypeDescriptionCan be empty?
    ipstring

    IP address that is used to lookup security information.

    		No
    hostnamestring

    Hostname of the IP address used to query IP Security API.

    		No

    2. security json object reference

    FieldTypeDescriptionCan be empty?
    threat_scorenumber

    IP address’ threat score. It ranges from 0 to 100. 100 indicates highest threat and vice versa for lower score.

    		No
    is_torboolean

    Indicates if the IP address is being consumed on a Tor endpoint.

    		No
    is_proxyboolean

    Indicates whether the IP address is associated with any anonymization network —VPN, PROXY, or RELAY.

    		No
    proxy_typestring

    Specifies which of the three types (VPN, PROXY, or RELAY) applies when is_proxy is true; otherwise remains empty.

    		Yes
    proxy_providerstring

    Name of the provider, if the IP address belongs to either a proxy, a VPN, or a relay network.

    		Yes
    is_anonymousboolean

    Indicates if the IP address is being used anonymously.

    		No
    is_known_attackerboolean

    Indicates if the IP address is enlisted as an attacking IP address.

    		No
    is_spamboolean

    Indicates if the IP address is enlisted as a spam IP address.

    		No
    is_botboolean

    Indicates if the IP address is enlisted as a bot IP address.

    		No
    is_cloud_providerboolean

    Indicates if the IP address belongs to a cloud provider (computing infrastructure providers).

    		No
    cloud_providerstring

    Name of the Cloud Provider, if the IP address belongs to a cloud provider.

    		Yes

    3. location json object reference

    FieldTypeDescriptionCan be empty?
    continent_codestring

    2-letter code of the continent.

    		No
    continent_namestring

    Name of the continent.

    		No
    country_code2string

    Country code (ISO 3166-1 alpha-2) of the country.

    		No
    country_code3string

    Country code (ISO 3166-1 alpha-3) of the country.

    		No
    country_namestring

    Name of the country.

    		No
    country_name_officialstring

    Official name (ISO 3166) of the country.

    		No
    country_capitalstring

    Name of the country’s capital.

    		No
    state_provstring

    Name of the state/province/region.

    		Yes
    state_codestring

    Code of the state/province/region.

    		Yes
    districtstring

    Name of the district or county.

    		Yes
    citystring

    Name of the city.

    		Yes
    zipcodestring

    ZIP/Postal code of the place.

    		Yes
    latitudestring

    Latitude of the place.

    		No
    longitudestring

    Longitude of the place.

    		No
    is_euboolean

    Is the country belong to European Union?

    		No
    country_flagstring

    URL to get the country flag.

    		No
    geoname_idstring

    Geoname ID of the place from geonames.org

    		Yes
    country_emojistring

    Emoji of the Country flag.

    		Yes

    4. network json object reference

    FieldTypeDescriptionCan be empty?
    asn.as_numberstring

    Autonomous system number of the autonomous system, to which IP address belongs to.

    		Yes
    asn.organizationstring

    Legal Full Name of AS organization holding the IP address.

    		Yes
    asn.countrystring

    Name of the country, ASN is residing.

    		Yes
    company.namestring

    Name of the company/ISP holding the IP address.

    		No

    5. currency json object reference

    FieldTypeDescriptionCan be empty?
    codestring

    Currency code (ISO 4217).

    		No
    namestring

    Currency name (ISO 4217).

    		No
    symbolstring

    Currency symbol.

    		No

    6. country_metadata json object reference

    FieldTypeDescriptionCan be empty?
    calling_codestring

    Calling code/Dialing code of the country.

    		No
    tldstring

    Top Level Domain Name (TLD) of the country, which is also called ccTLD.

    		No
    languageslist of strings

    List of the languages’ codes, spoken in the country.

    		No

    7. time_zone json object reference

    FieldTypeDescriptionCan be empty?
    namestring

    Name (ISO 8601) of the time zone.

    		No
    offsetnumber

    Time zone offset from UTC.

    		No
    offset_with_dstnumber

    Time zone with DST offset from UTC.

    		No
    current_timestring

    Current time in ‘yyyy-MM-dd HH:mm:ss.SSS±ZZZ’ format.

    		No
    current_time_unixfloat

    Current time in seconds since 1970.

    		No
    is_dstboolean

    Is the time zone in daylight savings?

    		No
    dst_savingsnumber

    Total daylight savings.

    		No
    dst_existsboolean

    Indicates whether Daylight Saving Time (DST) is observed in the region. If true, the dst_start and dst_end objects will include detailed DST transition information.

    		No
    dst_start.utc_timestring

    The date and time in UTC when DST begins.

    		No
    dst_start.durationstring

    The time change that occurs when DST starts.

    		No
    dst_start.gapboolean

    Is there a gap when the clocks jump forward or not.

    		No
    dst_start.date_time_afterstring

    The local date and time that immediately follows the start of DST.

    		No
    dst_start.date_time_beforestring

    The local date and time immediately before DST begins.

    		No
    dst_start.overlapboolean

    Whether there is an overlap of time due to clocks being set back when DST starts.

    		No
    dst_end.utc_timestring

    The date and time in UTC when DST ends.

    		No
    dst_end.durationstring

    The time change that occurs when DST ends.

    		No
    dst_end.gapboolean

    Is there a gap when the clocks jump backward or not.

    		No
    dst_end.date_time_afterstring

    The local date and time that immediately follows the ends of DST.

    		No
    dst_end.date_time_beforestring

    The local date and time immediately before DST ends.

    		No
    dst_end.overlapboolean

    Whether there is an overlap of time due to clocks being set back when DST ends.

    		No

    8. user_agent json object reference

    FieldTypeDescriptionCan be empty?
    user_agent_stringstring

    User-Agent string passed along with the query in the 'User-Agent' header.

    		No
    namestring

    User-Agent Name.

    		No
    typestring

    User-Agent Class.

    		No
    versionstring

    User-Agent Version.

    		No
    version_majorstring

    User-Agent Version Major.

    		No
    device.namestring

    Device Name.

    		No
    device.typestring

    Device Type.

    		No
    device.brandstring

    Device Brand.

    		No
    device.cpustring

    Device CPU Model.

    		No
    engine.namestring

    Layout Engine Name

    		No
    engine.typestring

    Layout Engine Class

    		No
    engine.versionstring

    Layout Engine Version.

    		No
    engine.version_majorstring

    Layout Engine Version Major.

    		No
    operating_system.namestring

    Operating System Name.

    		No
    operating_system.typestring

    Operating System Class.

    		No
    operating_system.versionstring

    Operating System Version.

    		No
    operating_system.version_majorstring

    Operating System Version Major.

    		No
    operating_system.buildstring

    Operating System Version Major.

    		No

    Error Codes

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

    While, 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 StatusDescription
    400
    Bad Request

    It is returned for one of the following reasons:

    • If the provided IPv4, IPv6 address, or domain name 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 IP addresses JSON list is empty, or the provided JSON does not have 'ips' field while querying 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 the API request is made from an unverified ipgeolocation.io account.

    • If your account has been disabled or locked to use by the admin 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 on the 'paused' subscription.

    • If you’re making API requests after your subscription trial has been expired.

    • If your active until date has passed and you need to upgrade your account.

    • If bulk IP to security look-ups endpoint is called using free subscription API key.

    404
    Not Found

    It is returned for one of the following reasons:

    • If the IPv4, IPv6, or domain name does not not exists in our database.

    • If the IPv4, IPv6, or domain name is passed as a path variable, instead of url parameter as ip= .

    • If the wrong endpoint is called, that does not exists 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 payload for IPs in security-bulk endpoint is missing, or the content type is not mentioned as JSON.

    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 reached for the free subscriptions, or paid subscriptions with the status 'past due', 'deleted' or 'trial expired'.

    • If the surcharge API usage limit has 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

    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, a VPN service (free or paid), or a privacy 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.
    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 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.
    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 plan starts at $39/month for 50,000 requests (monthly billing). Higher-usage plans are available. Annual billing includes 2 months free (12 months of access for the price of 10). Please compare Security plans and pricing for full details.

    Yes. Along with the Threat Score, the API returns flags such as VPN or proxy usage, relay signals, Tor, bot activity, spam indicators, known attacker signals, and cloud hosting context. These fields help you understand what was detected and support auditing and logging.
    is_proxy is true when the IP is using a proxy route, which can include VPN services, proxy networks, and privacy relays. proxy_type classifies the route type as VPN, PROXY, or RELAY when is_proxy is true.
    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. We do not flag well known search engine crawlers and other clean bots as bots. The is_bot field is intended to indicate suspicious or abusive automation, so if you use is_bot in your rules, legitimate crawlers should not be blocked.

    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 the 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.

    Subscribe Our Newsletter

    Get the latest in geolocation tech, straight to your inbox.