IP Geolocation API JavaScript Client Side Plugin

Overview

This document provides a comprehensive guide for setting up and using the IP Geolocation API client-side JavaScript plugin. It includes detailed descriptions of configuration options, example usage, and error handling. The plugin lets you use two APIs: the IP Geolocation API and the IP Security API, so you can add geolocation and IP threat detection features to your website or app.

This plugin helps you get accurate geolocation details for any IPv4 or IPv6 address. It provides important information such as country, state, city, ZIP code, latitude, longitude, accuracy radius, confidence level, DMA code, connection type, ISP/company information, and ASN data. These details are useful for showing location-based content or understanding where your users are coming from. You can also get abuse contact information, which is helpful for reporting suspicious or malicious activity.

Along with location data, the plugin also includes security lookup capability if you have a paid plan subscription. It can detect VPNs, proxy usage, residential proxies, Tor connections, relay networks, anonymous activity, known attackers, bots, spam sources, and cloud hosting providers, and also provides a threat score to assess risk.

The plugin further offers extra features like timezone details, currency information, and device data parsed from the User-Agent string. These details can help you customize content, set correct time zones, or display prices in the user's local currency.

Client Side Plugin Purpose

With our Free plan, you get basic location details like country, state, city, ZIP code, currency, basic ASN, and timezone. Paid plans give progressively more information which includes network details (ASN type, domain, RIR, company), user-agent parsing, hostname resolution, security threat detection, abuse contact data, geo accuracy fields, and DMA codes.

This plugin allows developers to integrate and utilize IP geolocation data within their web projects. Developers can use this plugin for various purposes, such as:

Geographic Redirection: Redirect visitors to region-specific site versions to enhance user experience and compliance with local regulations.
Analytics Enhancement: Use geolocation data to analyze web traffic and user behavior, enhancing site and content strategies.
Marketing Geo-targeting & Region Segmentation: Personalize content, offers, or marketing campaigns based on the visitor's region, DMA code, or currency for higher engagement and conversion.
Form Automation: Pre-fill forms with country, state, city, zip code, and currency information, speeding up the checkout and registration processes.
Digital Rights Management: Restrict or grant access to content based on the user's location to comply with legal restrictions.
ISP & ASN Attribution: Determine the internet service provider and ASN ownership behind an IP address for auditing, routing analysis, and attribution.
Suspicious Traffic Detection & Filtering: Detect and mitigate malicious activities by identifying traffic from suspicious locations or those using VPNs, proxies, Tor, relays, and known attackers.
Abuse Contact Identification: Identify abusive or malicious IPs by retrieving their registered abuse contacts, enabling automated reporting and proactive threat response.
Access Control: Block or restrict access from specific countries to comply with export controls or to reduce fraud and abuse.
Hostname Resolution (DB, Live, Fallback): Retrieve the hostname of an IP using a fast internal database, live DNS lookup, or a fallback of both. Useful for reverse DNS auditing and attribution.
Client Environment Profiling: Gain insights into the client's device, browser, and operating system to support adaptive UI/UX and environment-specific optimizations.
Timezone Synchronization: Display times and dates in the local timezone for events, posts, or deadlines, ensuring clarity and consistency for global users.
Language and Currency Customization: Automatically display content in the user's language and currency based on their geographic location.

Requirements

Active internet connection
API Key: Sign up at IPGeolocation.io

How to Get Your API Key

Sign up here: https://app.ipgeolocation.io/signup
(Optional) Verify your email if you signed up using an email address.
Log in to your account: https://app.ipgeolocation.io/login
After logging in, navigate to your Dashboard to find your API key: https://app.ipgeolocation.io/dashboard

Configurations

1. IPGeolocationAPI: Authentication & Input

Option	Type	Description
`apiKey`	string	Your API key. Required unless request origin is whitelisted (available only on paid plans).
`ipAddress`	string	IPv4, IPv6, or domain name to query. If omitted, the plugin auto-detects the user's IP.

2. IPGeolocationAPI: Basic Response Customization

Option	Type	Description
`fields`	string	Comma-separated list of fields to include in the response. Available on all plans.
`excludes`	string	Comma-separated list of fields to exclude from the response. Available on all plans.
`lang`	string	Language code for translated fields (default: `en` ). Requires a paid plan. Supported values: `de` , `ru` , `ja` , `fr` , `cn` , `es` , `cs` , `it` , `ko` , `fa` , `pt` .

3. IPGeolocationAPI: include Options and Plan Availability

Option	Type	Description
`includeHostname`	boolean	Include hostname from IPGeolocation's IP-Hostname database.
`includeLiveHostname`	boolean	Use live DNS sources to resolve hostname.
`includeHostnameFallbackLive`	boolean	Try database first, fall back to live sources if not found.
`includeUserAgent`	boolean	Include parsed client browser and device info.
`includeGeoAccuracy`	boolean	Add `accuracy_radius` , `confidence` , and `locality` to `location` .
`includeDmaCode`	boolean	Add `dma_code` to the `location` object (US IPs only).
`includeAbuse`	boolean	Include IP abuse contact information.
`includeSecurity`	boolean	Include VPN, proxy, Tor, relay, and threat detection.
`includeAll`	boolean	Include all optional modules in a single request ( `include=*` ).

4. IPGeolocationAPI: Storage Option

Option	Type	Description
`saveToSessionStorage`	boolean	If enabled, stores the geolocation response in `sessionStorage` to avoid repeated API calls during the same browser session, improving performance and reducing API usage.

5. IPSecurityAPI: Authentication & Input

Option	Type	Description
`apiKey`	string	Your API key. Required unless request origin is whitelisted (available only on paid plans).
`ipAddress`	string	IPv4 or IPv6 address to query. If omitted, the plugin auto-detects the user's IP.

6. IPSecurityAPI: Response Customization

Option	Type	Description
`fields`	string	Comma-separated list of `security` object fields to include (e.g. `security.threat_score` ).
`excludes`	string	Comma-separated list of `security` object fields to exclude (e.g. `security.is_tor` ).

7. IPSecurityAPI: Storage Option

Option	Type	Description
`saveToSessionStorage`	boolean	If enabled, stores the security response in `sessionStorage` to avoid repeated API calls during the same browser session, improving performance and reducing API usage.

Setup Plugin

To access this service, add the following JavaScript tag (usually within the <head> block of your pages).

<script src="https://static.ipgeolocation.io/ipgeolocation-api-plugin.v3.0.0.js"></script>

API Key Usage Example

Demonstrates how to use the plugin with and without an API key. The API key is optional if the request originates from a whitelisted domain (available only on paid plans).

1. No API Key (Request Origin is Whitelisted)

<script>
    (async () => {
        const ipGeoAPI = new IPGeolocationAPI();

        const resp = await ipGeoAPI.getGeolocation();

        if (!resp.error_message) {
            console.log(resp);
        } else {
            console.log("Something went wrong while fetching data", resp);
        }
    })();
</script>

2. With API Key

<script>
    (async () => {
        const ipGeoAPI = new IPGeolocationAPI({
            apiKey: "YOUR_IPGEOLOCATION_API_KEY",
        });

        const resp = await ipGeoAPI.getGeolocation();

        if (!resp.error_message) {
            console.log(resp);
        } else {
            console.log("Something went wrong while fetching data", resp);
        }
    })();
</script>

Free Plan Examples

1. Get Default Geolocation Fields

<script>
    (async () => {
        const ipGeoAPI = new IPGeolocationAPI({
            apiKey: "YOUR_IPGEOLOCATION_API_KEY",
        });

        const resp = await ipGeoAPI.getGeolocation();

        if (!resp.error_message) {
            console.log(resp);
        } else {
            console.log("Something went wrong while fetching data", resp);
        }
    })();
</script>

Sample Response:

Response Preview

1{
2  "ip": "8.8.8.8",
3  "location": {
4    "continent_code": "NA",
5    "continent_name": "North America",
6    "country_code2": "US",
7    "country_code3": "USA",
8    "country_name": "United States",
9    "country_name_official": "United States of America",
10    "country_capital": "Washington, D.C.",
11    "state_prov": "California",
12    "state_code": "US-CA",
13    "district": "Santa Clara",
14    "city": "Mountain View",
15    "zipcode": "94043-1351",
16    "latitude": "37.42240",
17    "longitude": "-122.08421",
18    "is_eu": false,
19    "country_flag": "https://ipgeolocation.io/static/flags/us_64.png",
20    "geoname_id": "6301403",
21    "country_emoji": "🇺🇸"
22  },
23  "country_metadata": {
24    "calling_code": "+1",
25    "tld": ".us",
26    "languages": ["en-US", "es-US", "haw", "fr"]
27  },
28  "currency": {
29    "code": "USD",
30    "name": "US Dollar",
31    "symbol": "$"
32  },
33  "asn": {
34    "as_number": "AS15169",
35    "organization": "Google LLC",
36    "country": "US"
37  },
38  "time_zone": {
39    "name": "America/Los_Angeles",
40    "offset": -8,
41    "offset_with_dst": -7,
42    "current_time": "2026-03-27 10:00:00.000-0700",
43    "current_time_unix": 1743087600.000,
44    "current_tz_abbreviation": "PDT",
45    "current_tz_full_name": "Pacific Daylight Time",
46    "standard_tz_abbreviation": "PST",
47    "standard_tz_full_name": "Pacific Standard Time",
48    "is_dst": true,
49    "dst_savings": 1,
50    "dst_exists": true,
51    "dst_tz_abbreviation": "PDT",
52    "dst_tz_full_name": "Pacific Daylight Time",
53    "dst_start": {
54      "utc_time": "2026-03-08 TIME 10:00",
55      "duration": "+1.00H",
56      "gap": true,
57      "date_time_after": "2026-03-08 TIME 03:00",
58      "date_time_before": "2026-03-08 TIME 02:00",
59      "overlap": false
60    },
61    "dst_end": {
62      "utc_time": "2026-11-01 TIME 09:00",
63      "duration": "-1.00H",
64      "gap": false,
65      "date_time_after": "2026-11-01 TIME 01:00",
66      "date_time_before": "2026-11-01 TIME 02:00",
67      "overlap": true
68    }
69  }
70}

2. Filtering Specific Fields from the Response

Use fields and excludes together to get the location object while omitting continent fields.

<script>
    (async () => {
        const ipGeoAPI = new IPGeolocationAPI({
            apiKey: "YOUR_IPGEOLOCATION_API_KEY",
            fields: "location",
            excludes: "location.continent_code,location.continent_name",
        });

        const resp = await ipGeoAPI.getGeolocation();

        if (!resp.error_message) {
            console.log(resp);
        } else {
            console.log("Something went wrong while fetching data", resp);
        }
    })();
</script>

Sample Response:

Response Preview

1{
2  "ip": "8.8.8.8",
3  "location": {
4    "country_code2": "US",
5    "country_code3": "USA",
6    "country_name": "United States",
7    "country_name_official": "United States of America",
8    "country_capital": "Washington, D.C.",
9    "state_prov": "California",
10    "state_code": "US-CA",
11    "district": "Santa Clara",
12    "city": "Mountain View",
13    "zipcode": "94043-1351",
14    "latitude": "37.42240",
15    "longitude": "-122.08421",
16    "is_eu": false,
17    "country_flag": "https://ipgeolocation.io/static/flags/us_64.png",
18    "geoname_id": "6301403",
19    "country_emoji": "🇺🇸"
20  }
21}

Paid Plan Examples

1. Geolocation with Default Fields

On a paid plan, the default response includes additional objects such as network , asn , company , and richer asn fields.

<script>
    (async () => {
        const ipGeoAPI = new IPGeolocationAPI({
            apiKey: "YOUR_IPGEOLOCATION_API_KEY",
        });

        const resp = await ipGeoAPI.getGeolocation();

        if (!resp.error_message) {
            console.log(resp);
        } else {
            console.log("Something went wrong while fetching data", resp);
        }
    })();
</script>

Sample Response:

Response Preview

1{
2  "ip": "8.8.8.8",
3  "location": {
4    "continent_code": "NA",
5    "continent_name": "North America",
6    "country_code2": "US",
7    "country_code3": "USA",
8    "country_name": "United States",
9    "country_name_official": "United States of America",
10    "country_capital": "Washington, D.C.",
11    "state_prov": "California",
12    "state_code": "US-CA",
13    "district": "Santa Clara",
14    "city": "Mountain View",
15    "zipcode": "94043-1351",
16    "latitude": "37.42240",
17    "longitude": "-122.08421",
18    "is_eu": false,
19    "country_flag": "https://ipgeolocation.io/static/flags/us_64.png",
20    "geoname_id": "6301403",
21    "country_emoji": "🇺🇸"
22  },
23  "country_metadata": {
24    "calling_code": "+1",
25    "tld": ".us",
26    "languages": ["en-US", "es-US", "haw", "fr"]
27  },
28  "network": {
29    "connection_type": "wired",
30    "route": "8.8.8.0/24",
31    "is_anycast": true
32  },
33  "currency": {
34    "code": "USD",
35    "name": "US Dollar",
36    "symbol": "$"
37  },
38  "asn": {
39    "as_number": "AS15169",
40    "organization": "Google LLC",
41    "country": "US",
42    "type": "HOSTING",
43    "domain": "about.google",
44    "date_allocated": "2000-03-30",
45    "rir": "ARIN"
46  },
47  "company": {
48    "name": "Google LLC",
49    "type": "HOSTING",
50    "domain": "google.com"
51  },
52  "time_zone": {
53    "name": "America/Los_Angeles",
54    "offset": -8,
55    "offset_with_dst": -7,
56    "current_time": "2026-03-27 10:00:00.000-0700",
57    "current_time_unix": 1743087600.000,
58    "current_tz_abbreviation": "PDT",
59    "current_tz_full_name": "Pacific Daylight Time",
60    "standard_tz_abbreviation": "PST",
61    "standard_tz_full_name": "Pacific Standard Time",
62    "is_dst": true,
63    "dst_savings": 1,
64    "dst_exists": true,
65    "dst_tz_abbreviation": "PDT",
66    "dst_tz_full_name": "Pacific Daylight Time",
67    "dst_start": {
68      "utc_time": "2026-03-08 TIME 10:00",
69      "duration": "+1.00H",
70      "gap": true,
71      "date_time_after": "2026-03-08 TIME 03:00",
72      "date_time_before": "2026-03-08 TIME 02:00",
73      "overlap": false
74    },
75    "dst_end": {
76      "utc_time": "2026-11-01 TIME 09:00",
77      "duration": "-1.00H",
78      "gap": false,
79      "date_time_after": "2026-11-01 TIME 01:00",
80      "date_time_before": "2026-11-01 TIME 02:00",
81      "overlap": true
82    }
83  }
84}

2. Retrieving Geolocation Data in Multiple Languages

Here is an example to get the geolocation data for the client's IP address in Russian ( ru ):

<script>
    (async () => {
        const ipGeoAPI = new IPGeolocationAPI({
            apiKey: "YOUR_IPGEOLOCATION_API_KEY",
            lang: "ru",
        });

        const resp = await ipGeoAPI.getGeolocation();

        if (!resp.error_message) {
            console.log(resp);
        } else {
            console.log("Something went wrong while fetching data", resp);
        }
    })();
</script>

3. Include Hostname and User-Agent

includeHostname , includeLiveHostname , and includeHostnameFallbackLive are available on paid plans. Use only one at a time.

<script>
    (async () => {
        const ipGeoAPI = new IPGeolocationAPI({
            apiKey: "YOUR_IPGEOLOCATION_API_KEY",
            fields: "location.country_name,location.country_capital",
            includeHostname: true,
            includeUserAgent: true,
        });

        const resp = await ipGeoAPI.getGeolocation();

        if (!resp.error_message) {
            console.log(resp);
        } else {
            console.log("Something went wrong while fetching data", resp);
        }
    })();
</script>

Sample Response:

Response Preview

1{
2  "ip": "4.5.6.7",
3  "hostname": "4.5.6.7",
4  "location": {
5    "country_name": "United States",
6    "country_capital": "Washington, D.C."
7  },
8  "user_agent": {
9    "user_agent_string": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/143.0.0.0 Safari/537.36",
10    "name": "Chrome",
11    "type": "Browser",
12    "version": "143.0.0.0",
13    "version_major": "143",
14    "device": {
15      "name": "Linux Desktop",
16      "type": "Desktop",
17      "brand": "Unknown",
18      "cpu": "Intel x86_64"
19    },
20    "engine": {
21      "name": "Blink",
22      "type": "Browser",
23      "version": "143.0.0.0",
24      "version_major": "143"
25    },
26    "operating_system": {
27      "name": "Linux",
28      "type": "Desktop",
29      "version": "??",
30      "version_major": "??",
31      "build": "??"
32    }
33  }
34}

4. Include Geo Accuracy Fields

Pass includeGeoAccuracy: true to add accuracy_radius , confidence , and locality to the location object.

<script>
    (async () => {
        const ipGeoAPI = new IPGeolocationAPI({
            apiKey: "YOUR_IPGEOLOCATION_API_KEY",
            fields: "location",
            includeGeoAccuracy: true,
        });

        const resp = await ipGeoAPI.getGeolocation();

        if (!resp.error_message) {
            console.log(resp);
        } else {
            console.log("Something went wrong while fetching data", resp);
        }
    })();
</script>

Sample Response (relevant location fields shown):

Response Preview

1{
2  "ip": "91.128.103.196",
3  "location": {
4    "continent_code": "EU",
5    "continent_name": "Europe",
6    "country_code2": "SE",
7    "country_code3": "SWE",
8    "country_name": "Sweden",
9    "country_name_official": "Kingdom of Sweden",
10    "country_capital": "Stockholm",
11    "state_prov": "Stockholms län",
12    "state_code": "SE-AB",
13    "district": "Stockholm",
14    "city": "Stockholm",
15    "locality": "Stockholm",
16    "accuracy_radius": "9.148",
17    "confidence": "high",
18    "zipcode": "164 40",
19    "latitude": "59.40510",
20    "longitude": "17.95510",
21    "is_eu": true,
22    "country_flag": "https://ipgeolocation.io/static/flags/se_64.png",
23    "geoname_id": "9972319",
24    "country_emoji": "🇸🇪"
25  }
26}

5. Include DMA Code

The DMA (Designated Market Area) code is a US-only field used for marketing and regional targeting. Pass includeDmaCode: true to include it.

<script>
    (async () => {
        const ipGeoAPI = new IPGeolocationAPI({
            apiKey: "YOUR_IPGEOLOCATION_API_KEY",
            fields: "location",
            includeDmaCode: true,
        });

        const resp = await ipGeoAPI.getGeolocation();

        if (!resp.error_message) {
            console.log(resp);
        } else {
            console.log("Something went wrong while fetching data", resp);
        }
    })();
</script>

Sample Response (US IP):

Response Preview

1{
2  "ip": "107.161.145.197",
3  "location": {
4    "continent_code": "NA",
5    "continent_name": "North America",
6    "country_code2": "US",
7    "country_code3": "USA",
8    "country_name": "United States",
9    "country_name_official": "United States of America",
10    "country_capital": "Washington, D.C.",
11    "state_prov": "Pennsylvania",
12    "state_code": "US-PA",
13    "district": "Philadelphia County",
14    "city": "Philadelphia",
15    "dma_code": "504",
16    "zipcode": "19102",
17    "latitude": "39.95258",
18    "longitude": "-75.16522",
19    "is_eu": false,
20    "country_flag": "https://ipgeolocation.io/static/flags/us_64.png",
21    "geoname_id": "9849057",
22    "country_emoji": "🇺🇸"
23  }
24}

6. Include Abuse Contact Information

Pass includeAbuse: true to add the abuse object to the response.

<script>
    (async () => {
        const ipGeoAPI = new IPGeolocationAPI({
            apiKey: "YOUR_IPGEOLOCATION_API_KEY",
            fields: "location.city,location.country_name",
            includeAbuse: true,
        });

        const resp = await ipGeoAPI.getGeolocation();

        if (!resp.error_message) {
            console.log(resp);
        } else {
            console.log("Something went wrong while fetching data", resp);
        }
    })();
</script>

Sample Response:

Response Preview

1{
2  "ip": "91.128.103.196",
3  "location": {
4    "city": "Stockholm",
5    "country_name": "Sweden"
6  },
7  "abuse": {
8    "route": "91.128.0.0/14",
9    "country": "SE",
10    "name": "Swipnet Staff",
11    "organization": "",
12    "kind": "group",
13    "address": "Tele2 AB/Swedish IP Network\nIP Registry\nTorshamnsgatan 17 164 40 Kista SWEDEN",
14    "emails": ["abuse@tele2.com"],
15    "phone_numbers": ["+46 8 5626 42 10"]
16  }
17}

7. Include Security Information

Pass includeSecurity: true to add the security object to the geolocation response.

<script>
    (async () => {
        const ipGeoAPI = new IPGeolocationAPI({
            apiKey: "YOUR_IPGEOLOCATION_API_KEY",
            fields: "location.city,location.country_name",
            includeSecurity: true,
        });

        const resp = await ipGeoAPI.getGeolocation();

        if (!resp.error_message) {
            console.log(resp);
        } else {
            console.log("Something went wrong while fetching data", resp);
        }
    })();
</script>

Sample Response:

Response Preview

1{
2  "ip": "2.56.188.34",
3  "location": {
4    "city": "Dallas",
5    "country_name": "United States"
6  },
7  "security": {
8    "threat_score": 80,
9    "is_tor": false,
10    "is_proxy": true,
11    "proxy_provider_names": ["Zyte Proxy"],
12    "proxy_confidence_score": 80,
13    "proxy_last_seen": "2025-12-12",
14    "is_residential_proxy": true,
15    "is_vpn": true,
16    "vpn_provider_names": ["Nord VPN"],
17    "vpn_confidence_score": 80,
18    "vpn_last_seen": "2026-01-19",
19    "is_relay": false,
20    "relay_provider_name": "",
21    "is_anonymous": true,
22    "is_known_attacker": true,
23    "is_bot": false,
24    "is_spam": false,
25    "is_cloud_provider": true,
26    "cloud_provider_name": "Packethub S.A."
27  }
28}

8. Include All Optional Modules

Pass includeAll: true to request every available optional module ( security , abuse , user_agent , hostname , geo_accuracy , dma_code ) in a single call. Equivalent to passing include=* to the API.

<script>
    (async () => {
        const ipGeoAPI = new IPGeolocationAPI({
            apiKey: "YOUR_IPGEOLOCATION_API_KEY",
            includeAll: true,
        });

        const resp = await ipGeoAPI.getGeolocation();

        if (!resp.error_message) {
            console.log(resp);
        } else {
            console.log("Something went wrong while fetching data", resp);
        }
    })();
</script>

IPSecurityAPI Examples

The IPSecurityAPI class calls the dedicated /v3/security endpoint and returns only IP threat signals. Use it when you need security data alone. To combine security data with geolocation, use IPGeolocationAPI with includeSecurity: true instead.

1. Basic Security Lookup

<script>
    (async () => {
        const ipSecAPI = new IPSecurityAPI({
            apiKey: "YOUR_IPGEOLOCATION_API_KEY",
            ipAddress: "2.56.188.34",
        });

        const resp = await ipSecAPI.getSecurity();

        if (!resp.error_message) {
            console.log(resp);
        } else {
            console.log("Something went wrong while fetching data", resp);
        }
    })();
</script>

Sample Response:

Response Preview

1{
2  "ip": "2.56.188.34",
3  "security": {
4    "threat_score": 80,
5    "is_tor": false,
6    "is_proxy": true,
7    "proxy_provider_names": ["Zyte Proxy"],
8    "proxy_confidence_score": 80,
9    "proxy_last_seen": "2025-12-12",
10    "is_residential_proxy": true,
11    "is_vpn": true,
12    "vpn_provider_names": ["Nord VPN"],
13    "vpn_confidence_score": 80,
14    "vpn_last_seen": "2026-01-19",
15    "is_relay": false,
16    "relay_provider_name": "",
17    "is_anonymous": true,
18    "is_known_attacker": true,
19    "is_bot": false,
20    "is_spam": false,
21    "is_cloud_provider": true,
22    "cloud_provider_name": "Packethub S.A."
23  }
24}

2. Return Only Specific Security Fields

Use fields to limit the response to only the security properties you need.

<script>
    (async () => {
        const ipSecAPI = new IPSecurityAPI({
            apiKey: "YOUR_IPGEOLOCATION_API_KEY",
            ipAddress: "2.56.188.34",
            fields: "security.threat_score,security.is_vpn,security.is_proxy",
        });

        const resp = await ipSecAPI.getSecurity();

        if (!resp.error_message) {
            console.log(resp);
        } else {
            console.log("Something went wrong while fetching data", resp);
        }
    })();
</script>

Sample Response:

Response Preview

1{
2  "ip": "2.56.188.34",
3  "security": {
4    "threat_score": 80,
5    "is_proxy": true,
6    "is_vpn": true
7  }
8}

3. Exclude Specific Security Fields

Use excludes to return the full security object while omitting fields you don't need.

<script>
    (async () => {
        const ipSecAPI = new IPSecurityAPI({
            apiKey: "YOUR_IPGEOLOCATION_API_KEY",
            ipAddress: "2.56.188.34",
            excludes: "security.is_tor,security.is_cloud_provider",
        });

        const resp = await ipSecAPI.getSecurity();

        if (!resp.error_message) {
            console.log(resp);
        } else {
            console.log("Something went wrong while fetching data", resp);
        }
    })();
</script>

Sample Response ( is_tor and is_cloud_provider omitted):

Response Preview

1{
2  "ip": "2.56.188.34",
3  "security": {
4    "threat_score": 80,
5    "is_proxy": true,
6    "proxy_provider_names": ["Zyte Proxy"],
7    "proxy_confidence_score": 80,
8    "proxy_last_seen": "2025-12-12",
9    "is_residential_proxy": true,
10    "is_vpn": true,
11    "vpn_provider_names": ["Nord VPN"],
12    "vpn_confidence_score": 80,
13    "vpn_last_seen": "2026-01-19",
14    "is_relay": false,
15    "relay_provider_name": "",
16    "is_anonymous": true,
17    "is_known_attacker": true,
18    "is_bot": false,
19    "is_spam": false,
20    "cloud_provider_name": "Packethub S.A."
21  }
22}

Error Handling

Inspect the error_message field in the response to detect any errors. A missing error_message typically indicates a successful request, while its presence signals an issue. For example, if you are using a free plan and trying to request security information, you will encounter an error as shown below:

<script>
    (async () => {
        const ipGeoAPI = new IPGeolocationAPI({
            apiKey: "YOUR_API_KEY",
            includeSecurity: true,
        });

        const resp = await ipGeoAPI.getGeolocation();

        if (!resp.error_message) {
            console.log(resp);
        } else {
            console.log("Something went wrong while fetching data", resp);
        }
    })();
</script>

Sample error response:

Response Preview

1{
2  "error_message": "IP-hostname lookup, IP-security lookup and user-agent parsing are not supported on your free subscription. These features are available to all paid subscriptions only.",
3  "error_status": 401
4}

IP Geolocation API JavaScript Client Side Plugin

Overview

Client Side Plugin Purpose

Requirements

How to Get Your API Key

Configurations

1. IPGeolocationAPI: Authentication & Input

2. IPGeolocationAPI: Basic Response Customization

3. IPGeolocationAPI: include Options and Plan Availability

4. IPGeolocationAPI: Storage Option

5. IPSecurityAPI: Authentication & Input

6. IPSecurityAPI: Response Customization

7. IPSecurityAPI: Storage Option

Setup Plugin

API Key Usage Example

1. No API Key (Request Origin is Whitelisted)

2. With API Key

Free Plan Examples

1. Get Default Geolocation Fields

2. Filtering Specific Fields from the Response

Paid Plan Examples

1. Geolocation with Default Fields

2. Retrieving Geolocation Data in Multiple Languages

3. Include Hostname and User-Agent

4. Include Geo Accuracy Fields

5. Include DMA Code

6. Include Abuse Contact Information

7. Include Security Information

8. Include All Optional Modules

IPSecurityAPI Examples

1. Basic Security Lookup

2. Return Only Specific Security Fields

3. Exclude Specific Security Fields

Error Handling

Subscribe to Our Newsletter