IP Geolocation API

Overview

IP Geolocation API provides real-time and accurate geolocation, asn, company, abuse, and security information for any IPv4 or IPv6 address and domain name, along with the detailed timezone and user-agent details for the provided user-agent string. You can geolocate your online visitors and provide them with a customized user-experience accordingly.

IPGeolocation API Endpoints

The IP Lookup API provides two endpoints to get geolocation & IP data information:

Single IP Geolocation Lookup
Bulk IPGeolocation Lookup

Single IP Geolocation Lookup API

Use the Single IP Location API endpoint to look up any IPv4 or IPv6 address. You can also call this endpoint without an ip parameter to automatically look up the caller IP.

1.Lookup a specific IPv4 or IPv6 address (using `ip` )

I.IPv4 Example

Curl

Java

JQuery

Javascript

Node.js

PHP

Python

Swift

Ruby

cUrl

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

Response

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    "zipcode": "19102",
16    "latitude": "39.95258",
17    "longitude": "-75.16522",
18    "is_eu": false,
19    "country_flag": "https://ipgeolocation.io/static/flags/us_64.png",
20    "geoname_id": "9849057",
21    "country_emoji": "🇺🇸"
22  },
23  "country_metadata": {
24    "calling_code": "+1",
25    "tld": ".us",
26    "languages": [
27      "en-US",
28      "es-US",
29      "haw",
30      "fr"
31    ]
32  },
33  "currency": {
34    "code": "USD",
35    "name": "US Dollar",
36    "symbol": "$"
37  },
38  "asn": {
39    "as_number": "AS12167",
40    "organization": "LightWave Networks",
41    "country": "US"
42  },
43  "time_zone": {
44    "name": "America/New_York",
45    "offset": -5,
46    "offset_with_dst": -5,
47    "current_time": "2026-02-11 04:30:04.621-0500",
48    "current_time_unix": 1770802204.621,
49    "current_tz_abbreviation": "EST",
50    "current_tz_full_name": "Eastern Standard Time",
51    "standard_tz_abbreviation": "EST",
52    "standard_tz_full_name": "Eastern Standard Time",
53    "is_dst": false,
54    "dst_savings": 0,
55    "dst_exists": true,
56    "dst_tz_abbreviation": "EDT",
57    "dst_tz_full_name": "Eastern Daylight Time",
58    "dst_start": {
59      "utc_time": "2026-03-08 TIME 07",
60      "duration": "+1H",
61      "gap": true,
62      "date_time_after": "2026-03-08 TIME 03",
63      "date_time_before": "2026-03-08 TIME 02",
64      "overlap": false
65    },
66    "dst_end": {
67      "utc_time": "2026-11-01 TIME 06",
68      "duration": "-1H",
69      "gap": false,
70      "date_time_after": "2026-11-01 TIME 01",
71      "date_time_before": "2026-11-01 TIME 02",
72      "overlap": true
73    }
74  }
75}

II.IPv6 Example

Curl

Java

JQuery

Javascript

Node.js

PHP

Python

Swift

Ruby

cUrl

curl -X GET 'https://api.ipgeolocation.io/v3/ipgeo?apiKey=API_KEY&ip=2607:fb91:16c6:8860:e531:2d1d:4944:6c7c'

Note

The response format is the same as IPv4. The only difference is the ip value will be an IPv6 address.

2.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 IP data.

Curl

Java

JQuery

Javascript

Node.js

PHP

Python

Swift

Ruby

cUrl

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

Note

The response is the same as the ip= lookup. The difference is that ip will be the requesting client’s public IP.

Credits charged for this endpoint

One successful request (status code returned 200 ) from this endpoint will consume 1 API Credit.

You can also confirm the charged credits from the response header:

• X-Credits-Charged

For a detailed explanation of our API credit consumption logic, please consult the Credits & Billing documentation.

Single IP Geolocation Lookup API

The Single IP Location API endpoint can be used to look up any IPv4, IPv6, or domain name. This endpoint also works without passing an ip parameter, which makes it useful for detecting and geolocating the caller IP. See the section below for examples of each.

1.Passing an IPv4, IPv6 Address or a domain

Pass an IPv4/IPv6 address or domain using the ip query parameter. This endpoint is meant to be called from the server side.

To find the geolocation information for any IPV4/IPV6 address or a domain name, pass it as a query parameter ip like below.

I.IPv4 Example

Curl

Java

JQuery

Javascript

Node.js

PHP

Python

Swift

Ruby

cUrl

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

II.IPv6 Example

Curl

Java

JQuery

Javascript

Node.js

PHP

Python

Swift

Ruby

cUrl

curl -X GET 'https://api.ipgeolocation.io/v3/ipgeo?apiKey=API_KEY&ip=2607:fb91:16c6:8860:e531:2d1d:4944:6c7c'

III.Domain Example

Curl

Java

JQuery

Javascript

Node.js

PHP

Python

Swift

Ruby

cUrl

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

Note

The ip field in the response returns the requested IPV4/IPV6 address or, for a domain query, the resolved IP address.
For domain lookups, a domain key is included at the root level of the response, mirroring the value passed in the request.

Response

1{
2  "domain": "ipgeolocation.io",
3  "ip": "107.161.145.197",
4  "location": {
5    "continent_code": "NA",
6    "continent_name": "North America",
7    "country_code2": "US",
8    "country_code3": "USA",
9    "country_name": "United States",
10    "country_name_official": "United States of America",
11    "country_capital": "Washington, D.C.",
12    "state_prov": "Pennsylvania",
13    "state_code": "US-PA",
14    "district": "Philadelphia County",
15    "city": "Philadelphia",
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  "country_metadata": {
25    "calling_code": "+1",
26    "tld": ".us",
27    "languages": [
28      "en-US",
29      "es-US",
30      "haw",
31      "fr"
32    ]
33  },
34  "network": {
35    "connection_type": "",
36    "route": "107.161.144.0/23",
37    "is_anycast": false
38  },
39  "currency": {
40    "code": "USD",
41    "name": "US Dollar",
42    "symbol": "$"
43  },
44  "asn": {
45    "as_number": "AS12167",
46    "organization": "LightWave Networks",
47    "country": "US",
48    "type": "ISP",
49    "domain": "lightwavenetworks.com",
50    "date_allocated": "2024-11-14T00:00",
51    "rir": "ARIN"
52  },
53  "company": {
54    "name": "LightWave Networks",
55    "type": "ISP",
56    "domain": "lightwavenetworks.com"
57  },
58  "time_zone": {
59    "name": "America/New_York",
60    "offset": -5,
61    "offset_with_dst": -5,
62    "current_time": "2026-02-11 05:09:24.112-0500",
63    "current_time_unix": 1770804564.112,
64    "current_tz_abbreviation": "EST",
65    "current_tz_full_name": "Eastern Standard Time",
66    "standard_tz_abbreviation": "EST",
67    "standard_tz_full_name": "Eastern Standard Time",
68    "is_dst": false,
69    "dst_savings": 0,
70    "dst_exists": true,
71    "dst_tz_abbreviation": "EDT",
72    "dst_tz_full_name": "Eastern Daylight Time",
73    "dst_start": {
74      "utc_time": "2026-03-08 TIME 07",
75      "duration": "+1H",
76      "gap": true,
77      "date_time_after": "2026-03-08 TIME 03",
78      "date_time_before": "2026-03-08 TIME 02",
79      "overlap": false
80    },
81    "dst_end": {
82      "utc_time": "2026-11-01 TIME 06",
83      "duration": "-1H",
84      "gap": false,
85      "date_time_after": "2026-11-01 TIME 01",
86      "date_time_before": "2026-11-01 TIME 02",
87      "overlap": true
88    }
89  }
90}

2.Without Passing an IP Address (no `ip` parameter)

When this endpoint is queried without an IP address, it returns the geolocation information of the device/client that is calling it. This endpoint is meant to be called from the client side.

Curl

Java

JQuery

Javascript

Node.js

PHP

Python

Swift

Ruby

cUrl

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

Note

This response structure is the same as the ip= lookup shown above. The difference is that the ip field will populate with the requesting client’s public IP address.

To implement this endpoint client-side, use the Request Origin Whitelisting (Add Link here) feature available on all paid plans to prevent public use of your API Key.

Credits charged

One successful request (status code returned 200 ) from this endpoint will consume 1 API Credit.

You can also confirm the charged credits from the response header:

• X-Credits-Charged

Credit consumption may vary if you include Security or Abuse Contact Data in the response. Refer to the Credits & Billing documentationfor precise usage rates.

Response in Multiple Languages

The geolocation information for an IP address from the IP Geolocation API can be retrieved in the following languages:

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. You can change the response language by passing the language code as a query parameter lang . Here is an example to get the geolocation data for IP address '107.161.145.197' in Chinese language.

Curl

Java

JQuery

Javascript

Node.js

PHP

Python

Swift

Ruby

cUrl

curl -X GET 'https://api.ipgeolocation.io/v3/ipgeo?apiKey=API_KEY&ip=107.161.145.197&lang=cn'

Note

Only the paid plan subscriptions can get the response in languages other than English. All the other subscriptions will only get the response in English.

Additional Query Parameters

Use these query parameters to include additional data, exclude fields, or return only the fields you need. This helps you keep responses small, reduce bandwidth, and speed up processing on your side.

include adds optional modules that are not included by default
fields return only the fields you request
excludes removes fields or modules you don’t need

Note

The include parameter is available on Paid plans. The fields and excludes parameters are available on all plans, including Free, and can be used to select and filter response fields.

1.Include Additional Data ( `include` parameter)

Use include query parameter in your request to add extra data to the response.

Available values:

Use the include parameter with one or more of the values below (comma separated if more than one).

Enrichment data: geo_accuracy, dma_code, user_agent, security, abuse
Hostname options: hostname, liveHostname, hostnameFallbackLive

Examples and details for each option are provided below.

I.Include Additional Geo Accuracy Fields ( `include=geo_accuracy` )

Add include=geo_accuracy in your request to return three additional fields in the location object:

location.accuracy_radius :

Accuracy radius in km around location.latitude and location.longitude

location.confidence :

Confidence level for the accuracy radius: high, medium, or low.

location.locality :

Locality or neighborhood (may be the same as the city).

Example request and response are shown below.

Curl

Java

JQuery

Javascript

Node.js

PHP

Python

Swift

Ruby

cUrl

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

Response

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    "locality": "Philadelphia",
16    "accuracy_radius": "8.295",
17    "confidence": "high",
18    "zipcode": "19102",
19    "latitude": "39.95258",
20    "longitude": "-75.16522",
21    "is_eu": false,
22    "country_flag": "https://ipgeolocation.io/static/flags/us_64.png",
23    "geoname_id": "9849057",
24    "country_emoji": "🇺🇸"
25  },
26  "country_metadata": {
27    "...": "...",
28    ]
29  },
30  "network": {
31    "...": "..."
32  },
33  "currency": {
34    "...": "..."
35  },
36  "asn": {
37    "...": "..."
38  },
39  "company": {
40    "...": "..."
41  },
42  "time_zone": {
43    "...": "..."
44  }
45}

II.Include DMA Code ( `include=dma_code` parameter)

If you need the DMA (Designated Market Area) code, which is used in the United States for marketing and regional targeting, you can retrieve it through the IP Geolocation API on any Paid plan.

To include the DMA code in the location object, add include=dma_code to your request.

Below is an example IP Geolocation lookup request and response that includes the DMA code along with the location data for the IP address:

Curl

Java

JQuery

Javascript

Node.js

PHP

Python

Swift

Ruby

cUrl

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

Response

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  "country_metadata": {
25    "...": "...",
26    ]
27  },
28  "network": {
29    "...": "..."
30  },
31  "currency": {
32    "...": "..."
33  },
34  "asn": {
35    "...": "..."
36  },
37  "company": {
38    "...": "..."
39  },
40  "time_zone": {
41    "...": "..."
42  }
43}

Note

The location.dma_code field will be non-empty only for IPs in the USA.

III.Include User-Agent Information for a Device ( `include=user_agent` parameter)

IP Geolocation API also provides User-Agent information of the client on all the paid subscriptions, but doesn't respond it by default. To get User-Agent information along with the geolocation information, you must pass the include=user_agent as a query parameter in the request URL.

How User-Agent parsing works:

i.How User-Agent parsing works

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.

Example requests and responses for both scenarios are given below.

A.Without a User-Agent header

The API parses the user agent of the requesting client.

Curl

Java

JQuery

Javascript

Node.js

PHP

Python

Swift

Ruby

cUrl

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

Response

1{
2  "ip": "107.161.145.197",
3  "location": {
4    "...": "..."
5  },
6  "country_metadata": {
7    "...": "...",
8    ]
9  },
10  "network": {
11    "...": "..."
12  },
13  "currency": {
14    "...": "..."
15  },
16  "asn": {
17    "...": "..."
18  },
19  "company": {
20    "...": "..."
21  },
22  "time_zone": {
23    "...": "..."
24  },
25  "user_agent": {
26    "user_agent_string": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/143.0.0.0 Safari/537.36",
27    "name": "Chrome",
28    "type": "Browser",
29    "version": "143",
30    "version_major": "143",
31    "device": {
32      "name": "Linux Desktop",
33      "type": "Desktop",
34      "brand": "Unknown",
35      "cpu": "Intel x86_64"
36    },
37    "engine": {
38      "name": "Blink",
39      "type": "Browser",
40      "version": "143",
41      "version_major": "143"
42    },
43    "operating_system": {
44      "name": "Linux",
45      "type": "Desktop",
46      "version": "??",
47      "version_major": "??",
48      "build": "??"
49    }
50  }
51}

B.With a User-Agent header

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

Curl

Java

JQuery

Javascript

Node.js

PHP

Python

Swift

Ruby

cUrl

curl -X POST 'https://api.ipgeolocation.io/v3/ipgeo?apiKey=API_KEY&ip=107.161.145.197&include=user_agent' \
-H 'User-Agent: python-requests/2.32.5'

Response

1{
2  "ip": "107.161.145.197",
3  "location": {
4    "...": "..."
5  },
6  "country_metadata": {
7    "...": "...",
8    ]
9  },
10  "network": {
11    "...": "..."
12  },
13  "currency": {
14    "...": "..."
15  },
16  "asn": {
17    "...": "..."
18  },
19  "company": {
20    "...": "..."
21  },
22  "time_zone": {
23    "...": "..."
24  },
25    "user_agent": {
26    "user_agent_string": "python-requests/2.32.5",
27    "name": "Python-Requests",
28    "type": "Robot",
29    "version": "2.32.5",
30    "version_major": "2",
31    "device": {
32      "name": "Python Requests",
33      "type": "Robot",
34      "brand": "Python",
35      "cpu": "Unknown"
36    },
37    "engine": {
38      "name": "python-requests",
39      "type": "Robot",
40      "version": "2.32.5",
41      "version_major": "2"
42    },
43    "operating_system": {
44      "name": "Cloud",
45      "type": "Cloud",
46      "version": "??",
47      "version_major": "??",
48      "build": "??"
49    }
50  }
51}

IV.Hostname Lookup for an IP Address

IPGeolocation API also provides hostname lookup for an IP address on all the paid subscriptions, but doesn't respond it by default. To get the hostname for an IP address, you can pass one of the following three values in include request parameter:

hostname :

Returns the hostname from our local IP-to-hostname database.

liveHostname :

Performs a live hostname lookup.

hostnameFallbackLive :

Performs a live hostname lookup.

Here is an example to IP Geolocation lookup that includes the hostname for the IP address:

Curl

Java

JQuery

Javascript

Node.js

PHP

Python

Swift

Ruby

cUrl

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

Response

1{
2  "ip": "107.161.145.197",
3  "hostname": "host197.lightwavenetworks.com",
4  "location": {
5    "continent_code": "NA",
6    "continent_name": "North America",
7    "country_code2": "US",
8    "country_code3": "USA",
9    "country_name": "United States",
10    "country_name_official": "United States of America",
11    "country_capital": "Washington, D.C.",
12    "state_prov": "Pennsylvania",
13    "state_code": "US-PA",
14    "district": "Philadelphia County",
15    "city": "Philadelphia",
16    "locality": "Philadelphia",
17    "accuracy_radius": "8.295",
18    "confidence": "high",
19    "zipcode": "19102",
20    "latitude": "39.95258",
21    "longitude": "-75.16522",
22    "is_eu": false,
23    "country_flag": "https://ipgeolocation.io/static/flags/us_64.png",
24    "geoname_id": "9849057",
25    "country_emoji": "🇺🇸"
26  },
27  "country_metadata": {
28    "...": "...",
29    ]
30  },
31  "network": {
32    "...": "..."
33  },
34  "currency": {
35    "...": "..."
36  },
37  "asn": {
38    "...": "..."
39  },
40  "company": {
41    "...": "..."
42  },
43  "time_zone": {
44    "...": "..."
45  }
46}

Note

Hostname behavior: If a hostname cannot be resolved, the API returns the queried IP address in the hostname field.

i. `include=hostname` URL Parameter

This URL parameter enables the IPGeolocation API to lookup hostname from our IP-Hostname database and returns the same IP address if there is no hostname found for the queried IP address. Lookup thru IP-Hostname database is faster than other options but is experimental and under process and can produce unwanted output.

ii. `include=liveHostname` URL Parameter

This URL parameter enables the IPGeolocation API to lookup hostname from live sources. Lookup thru live sources is accurate but can introduce more latency to your query to IPGeolocation API.

iii. `include=hostnameFallbackLive` URL Parameter

This URL parameter enables the IPGeolocation API to lookup hostname from our IP-Hostname database and if there is no hostname found for the queried IP address, then lookup thru the live sources. This option has been introduced for faster and accurate lookup.

V.IP-Security Information for an IP Address ( `include=security` parameter)

IP Geolocation API also provides IP-Security information on all the Paid API subscriptions, but doesn't return it in the response by default. To get IP-Security information along with the geolocation information, you must pass the include=security as a query parameter in the URL.

The security object returns structured risk signals for the IP address, including an overall threat_score plus boolean flags for common anonymization and abuse categories such as is_proxy , is_residential_proxy , is_vpn , is_tor , is_relay , is_bot , is_spam , is_known_attacker , is_anonymous ,and and is_cloud_provider .

When a match is found, it can also include attribution and strength signals such as provider names (for example, proxy_provider_names , vpn_provider_names , cloud_provider_name ) along with confidence and recency fields like proxy_confidence_score , proxy_last_seen , vpn_confidence_score , and vpn_last_seen .

For an example request and sample response showing how to include the security object in the default response, see below.

Curl

Java

JQuery

Javascript

Node.js

PHP

Python

Swift

Ruby

cUrl

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

Response

1{
2  "ip": "107.161.145.197",
3  "hostname": "host197.lightwavenetworks.com",
4  "location": {
5    "...": "..."
6  },
7  "country_metadata": {
8    "...": "...",
9    ]
10  },
11  "network": {
12    "...": "..."
13  },
14  "currency": {
15    "...": "..."
16  },
17  "asn": {
18    "...": "..."
19  },
20  "company": {
21    "...": "..."
22  },
23  "security": {
24    "threat_score": 80,
25    "is_tor": false,
26    "is_proxy": true,
27    "proxy_provider_names": [
28      "Zyte Proxy"
29    ],
30    "proxy_confidence_score": 90,
31    "proxy_last_seen": "2025-12-12",
32    "is_residential_proxy": true,
33    "is_vpn": true,
34    "vpn_provider_names": [
35      "Nord VPN"
36    ],
37    "vpn_confidence_score": 90,
38    "vpn_last_seen": "2026-01-19",
39    "is_relay": false,
40    "relay_provider_name": "",
41    "is_anonymous": true,
42    "is_known_attacker": true,
43    "is_bot": false,
44    "is_spam": false,
45    "is_cloud_provider": true,
46    "cloud_provider_name": "Packethub S.A."
47  },
48  "time_zone": {
49    "...": "..."
50  }
51}

Important

Adding security to the lookup costs 2 additional credits. Since the base lookup (everything except security ' and abuse ) costs 1 credit, the total becomes 3 credits when security is included. For the exact charge on any request, check the X-Credits-Charged response header.

i.If you only need the `security` object

You have two options:

A.Use this unified endpoint and return only `security` using `fields`

This costs 2 credits in total (not 1 + 2).

Curl

Java

JQuery

Javascript

Node.js

PHP

Python

Swift

Ruby

cUrl

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

Response

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": [
8      "Zyte Proxy"
9    ],
10    "proxy_confidence_score": 90,
11    "proxy_last_seen": "2025-12-12",
12    "is_residential_proxy": true,
13    "is_vpn": true,
14    "vpn_provider_names": [
15      "Nord VPN"
16    ],
17    "vpn_confidence_score": 90,
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}

B.Use the dedicated Security endpoint ( `/v3/security` )

See the IP Security API documentation. Requests to /v3/security always cost 2 credits, since the endpoint returns security data only.

VI.Abuse Contact Information for an IP Address ( `include=abuse` parameter)

IP Geolocation API can also provide abuse contact information of an IP address on all the paid API subscriptions, but doesn't return it in the response by default. To get abuse contact information for any IPV4/IPV6 address along with the geolocation information, you must pass the include=abuse as a query parameter in the request URL.

An example request and response for this parameter is shown below.

Curl

Java

JQuery

Javascript

Node.js

PHP

Python

Swift

Ruby

cUrl

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

Response

1{
2  "ip": "2.56.188.34",
3  "location": {
4   "...": "..."
5  },
6  "country_metadata": {
7    "...": "..."
8  },
9  "network": {
10    "...": "..."
11  },
12  "currency": {
13    "...": "..."
14  },
15  "asn": {
16    "...": "..."
17  },
18  "company": {
19    "...": "..."
20  },
21  "abuse": {
22    "route": "2.56.188.32/27",
23    "country": "US",
24    "name": "Packethub S.A. Abuse Department",
25    "organization": "",
26    "kind": "group",
27    "address": "Packethub S.A., Office 76, Plaza 2000, 50 Street and Marbella, Bella Vista, Panama City, 0823, Republic of Panama",
28    "emails": [
29      "abuse@packethub.tech"
30    ],
31    "phone_numbers": [
32      "+5078336503"
33    ]
34  },
35  "time_zone": {
36    "...": "..."
37  }
38}

Important

Adding abuse to the lookup costs 1 additional credit. Since the base lookup (everything except security and abuse ) costs 1 credit, the total becomes 2 credits when abuse is included. For the exact charge on any request, check the X-Credits-Charged response header.

i.If you only need the `abuse` object

You have two options:

A.Use this unified endpoint and return only `abuse` using `fields`

This costs 1 credits in total (not 1 + 1).

Curl

Java

JQuery

Javascript

Node.js

PHP

Python

Swift

Ruby

cUrl

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

Response

1{
2  "ip": "2.56.188.34",
3  "abuse": {
4    "route": "2.56.188.32/27",
5    "country": "US",
6    "name": "Packethub S.A. Abuse Department",
7    "organization": "",
8    "kind": "group",
9    "address": "Packethub S.A., Office 76, Plaza 2000, 50 Street and Marbella, Bella Vista, Panama City, 0823, Republic of Panama",
10    "emails": [
11      "abuse@packethub.tech"
12    ],
13    "phone_numbers": [
14      "+5078336503"
15    ]
16  }
17}

B.Use the dedicated Abuse endpoint ( `/v3/abuse` )

See the IP Abuse Contact API documentation. Requests to /v3/abuse always cost 1 credit, since the endpoint returns abuse contact data only.

2.Include Everything in One API Call ( `include=*` )

Use this option when you want IP geolocation plus all the available additional data in a single response.

You can include all additional data in the IP Geolocation lookup response in two ways:

include=* : This option includes all additional data modules (geo_accuracy, dma_code, user_agent, security, abuse, hostname) in the response.
Include each module separately: You can also include all additional data by specifying each module name in the include parameter, separated by commas. For example: include=geo_accuracy,dma_code,user_agent,security,abuse,hostname .

Curl

Java

JQuery

Javascript

Node.js

PHP

Python

Swift

Ruby

cUrl

curl -X GET 'https://api.ipgeolocation.io/v3/ipgeo?apiKey=API_KEY&ip=2.56.188.34&include=security,abuse,user_agent,dma,geo_accuracy,hostname'

Curl

Java

JQuery

Javascript

Node.js

PHP

Python

Swift

Ruby

cUrl

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

Response

1{
2  "ip": "2.56.188.34",
3  "hostname": "2.56.188.34",
4  "location": {
5    "continent_code": "NA",
6    "continent_name": "North America",
7    "country_code2": "US",
8    "country_code3": "USA",
9    "country_name": "United States",
10    "country_name_official": "United States of America",
11    "country_capital": "Washington, D.C.",
12    "state_prov": "Texas",
13    "state_code": "US-TX",
14    "district": "Dallas",
15    "city": "Dallas",
16    "locality": "Dallas",
17    "accuracy_radius": "9.61",
18    "confidence": "medium",
19    "dma_code": "623",
20    "zipcode": "75201",
21    "latitude": "32.77822",
22    "longitude": "-96.79512",
23    "is_eu": false,
24    "country_flag": "https://ipgeolocation.io/static/flags/us_64.png",
25    "geoname_id": "4684902",
26    "country_emoji": "🇺🇸"
27  },
28  "country_metadata": {
29    "calling_code": "+1",
30    "tld": ".us",
31    "languages": [
32      "en-US",
33      "es-US",
34      "haw",
35      "fr"
36    ]
37  },
38  "network": {
39    "connection_type": "",
40    "route": "2.56.188.0/22",
41    "is_anycast": false
42  },
43  "currency": {
44    "code": "USD",
45    "name": "US Dollar",
46    "symbol": "$"
47  },
48  "asn": {
49    "as_number": "AS62240",
50    "organization": "Clouvider Limited",
51    "country": "GB",
52    "type": "HOSTING",
53    "domain": "clouvider.net",
54    "date_allocated": "2025-12-29T12:48:31",
55    "rir": "RIPE"
56  },
57  "company": {
58    "name": "Packethub S.A.",
59    "type": "BUSINESS",
60    "domain": "packethub.com"
61  },
62  "security": {
63    "threat_score": 80,
64    "is_tor": false,
65    "is_proxy": true,
66    "proxy_provider_names": [
67      "Zyte Proxy"
68    ],
69    "proxy_confidence_score": 90,
70    "proxy_last_seen": "2025-12-12",
71    "is_residential_proxy": true,
72    "is_vpn": true,
73    "vpn_provider_names": [
74      "Nord VPN"
75    ],
76    "vpn_confidence_score": 90,
77    "vpn_last_seen": "2026-01-19",
78    "is_relay": false,
79    "relay_provider_name": "",
80    "is_anonymous": true,
81    "is_known_attacker": true,
82    "is_bot": false,
83    "is_spam": false,
84    "is_cloud_provider": true,
85    "cloud_provider_name": "Packethub S.A."
86  },
87  "abuse": {
88    "route": "2.56.188.32/27",
89    "country": "US",
90    "name": "Packethub S.A. Abuse Department",
91    "organization": "",
92    "kind": "group",
93    "address": "Packethub S.A., Office 76, Plaza 2000, 50 Street and Marbella, Bella Vista, Panama City, 0823, Republic of Panama",
94    "emails": [
95      "abuse@packethub.tech"
96    ],
97    "phone_numbers": [
98      "+5078336503"
99    ]
100  },
101  "time_zone": {
102    "name": "America/Chicago",
103    "offset": -6,
104    "offset_with_dst": -6,
105    "current_time": "2026-02-11 05:22:51.856-0600",
106    "current_time_unix": 1770808971.856,
107    "current_tz_abbreviation": "CST",
108    "current_tz_full_name": "Central Standard Time",
109    "standard_tz_abbreviation": "CST",
110    "standard_tz_full_name": "Central Standard Time",
111    "is_dst": false,
112    "dst_savings": 0,
113    "dst_exists": true,
114    "dst_tz_abbreviation": "CDT",
115    "dst_tz_full_name": "Central Daylight Time",
116    "dst_start": {
117      "utc_time": "2026-03-08 TIME 08",
118      "duration": "+1H",
119      "gap": true,
120      "date_time_after": "2026-03-08 TIME 03",
121      "date_time_before": "2026-03-08 TIME 02",
122      "overlap": false
123    },
124    "dst_end": {
125      "utc_time": "2026-11-01 TIME 07",
126      "duration": "-1H",
127      "gap": false,
128      "date_time_after": "2026-11-01 TIME 01",
129      "date_time_before": "2026-11-01 TIME 02",
130      "overlap": true
131    }
132  },
133  "user_agent": {
134    "user_agent_string": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/143.0.0.0 Safari/537.36",
135    "name": "Chrome",
136    "type": "Browser",
137    "version": "143",
138    "version_major": "143",
139    "device": {
140      "name": "Linux Desktop",
141      "type": "Desktop",
142      "brand": "Unknown",
143      "cpu": "Intel x86_64"
144    },
145    "engine": {
146      "name": "Blink",
147      "type": "Browser",
148      "version": "143",
149      "version_major": "143"
150    },
151    "operating_system": {
152      "name": "Linux",
153      "type": "Desktop",
154      "version": "??",
155      "version_major": "??",
156      "build": "??"
157    }
158  }
159}

Note

This returns the largest response. If you only need a few objects, include only those to reduce response size and improve performance. You can also use fields and excludes to control which data is returned. Detailed usage for both parameters is covered in the next sections.

Important

Credits: This request costs 4 API credits total: 1 for the base lookup and free additional data (everything except security and abuse), 2for security ', and 1 for abuse .

Filter Responses

We’ve built the API to give you fine granularity. Specify what you want in the query parameter and get only those fields. This saves you processing time, bandwidth, and can improve API response time.

You can filter the API response in two ways using fields ' and/or excludes query parameters.

1.Get the Required Fields Only ( `fields` parameter)

First, you can filter the API response by specifying names of the fields that you want instead of getting the full response. Names of the required fields must be passed as a value (comma-separated if there are multiple) in the query Parameter fields in the request. Here are a few examples to get only the required fields:

I.Get Location Information Only

Curl

Java

JQuery

Javascript

Node.js

PHP

Python

Swift

Ruby

cUrl

curl -X GET 'https://api.ipgeolocation.io/v3/ipgeo?apiKey=API_KEY&fields=location&ip=107.161.145.197'

Response

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    "zipcode": "19102",
16    "latitude": "39.95258",
17    "longitude": "-75.16522",
18    "is_eu": false,
19    "country_flag": "https://ipgeolocation.io/static/flags/us_64.png",
20    "geoname_id": "9849057",
21    "country_emoji": "🇺🇸"
22  }
23}

II.Get country name and ASN organization only

Curl

Java

JQuery

Javascript

Node.js

PHP

Python

Swift

Ruby

cUrl

curl -X GET 'https://api.ipgeolocation.io/v3/ipgeo?apiKey=API_KEY&fields=location.country_name,asn.organization&ip=107.161.145.197'

Response

1{
2  "ip": "107.161.145.197",
3  "location": {
4    "country_name": "United States"
5  },
6  "asn": {
7    "organization": "LightWave Networks"
8  }
9}

Note

Note that we did not use the include parameter here, because the requested fields are part of the default response objects.

III.Get only the city, threat score, and VPN status

Because security is not returned by default, include it first, then use fields to select the specific fields you want:

Curl

Java

JQuery

Javascript

Node.js

PHP

Python

Swift

Ruby

cUrl

curl -X GET 'https://api.ipgeolocation.io/v3/ipgeo?apiKey=API_KEY&include=security&fields=location.city,security.threat_score,security.is_vpn'

Response

1{
2  "ip": "107.161.145.197",
3  "location": {
4    "city": "Philadelphia"
5  },
6  "security": {
7    "threat_score": 5,
8    "is_vpn": false
9  }
10}

Note

If you select a field from an object that is not returned by default (such as security , user_agent , geo_accuracy , hostname , or abuse ), include it first using include=... .
If you list both an object key and one of its fields in fields , the full object will be returned.
Use object_key.field_key to select nested fields. For root-level fields, use the field name directly (without the object_key prefix).

Remove any Unnecessary Fields ( `excludes` parameter)

Second, you can filter the API response by excluding specific fields (except the ip address) or entire objects you do not need. To do this, pass the object key (for example, currency) or a specific field path (for example, location.continent_code ) in the excludes query parameter.

Use excludes to remove fields or objects you do not need (the ip field is always returned).

Exclude an entire object: currency
Exclude a field: location.continent_code

Below are a few examples showing how to exclude unnecessary fields:

1.Exclude continent code, currency object, and company type

Curl

Java

JQuery

Javascript

Node.js

PHP

Python

Swift

Ruby

cUrl

curl -X GET 'https://api.ipgeolocation.io/v3/ipgeo?apiKey=API_KEY&ip=107.161.145.197&excludes=location.continent_code,currency,company.type'

Response

1{
2  "ip": "107.161.145.197",
3  "location": {
4    "continent_name": "North America",
5    "country_code2": "US",
6    "country_code3": "USA",
7    "country_name": "United States",
8    "country_name_official": "United States of America",
9    "country_capital": "Washington, D.C.",
10    "state_prov": "Pennsylvania",
11    "state_code": "US-PA",
12    "district": "Philadelphia County",
13    "city": "Philadelphia",
14    "zipcode": "19102",
15    "latitude": "39.95258",
16    "longitude": "-75.16522",
17    "is_eu": false,
18    "country_flag": "https://ipgeolocation.io/static/flags/us_64.png",
19    "geoname_id": "9849057",
20    "country_emoji": "🇺🇸"
21  },
22  "country_metadata": {
23    "calling_code": "+1",
24    "tld": ".us",
25    "languages": [
26      "en-US",
27      "es-US",
28      "haw",
29      "fr"
30    ]
31  },
32  "network": {
33    "connection_type": "",
34    "route": "107.161.144.0/23",
35    "is_anycast": false
36  },
37  "asn": {
38    "as_number": "AS12167",
39    "organization": "LightWave Networks",
40    "country": "US",
41    "type": "ISP",
42    "domain": "lightwavenetworks.com",
43    "date_allocated": "2024-11-14T00:00",
44    "rir": "ARIN"
45  },
46  "company": {
47    "name": "LightWave Networks",
48    "domain": "lightwavenetworks.com"
49  },
50  "time_zone": {
51    "name": "America/New_York",
52    "offset": -5,
53    "offset_with_dst": -5,
54    "current_time": "2026-02-11 07:11:50.320-0500",
55    "current_time_unix": 1770811910.32,
56    "current_tz_abbreviation": "EST",
57    "current_tz_full_name": "Eastern Standard Time",
58    "standard_tz_abbreviation": "EST",
59    "standard_tz_full_name": "Eastern Standard Time",
60    "is_dst": false,
61    "dst_savings": 0,
62    "dst_exists": true,
63    "dst_tz_abbreviation": "EDT",
64    "dst_tz_full_name": "Eastern Daylight Time",
65    "dst_start": {
66      "utc_time": "2026-03-08 TIME 07",
67      "duration": "+1H",
68      "gap": true,
69      "date_time_after": "2026-03-08 TIME 03",
70      "date_time_before": "2026-03-08 TIME 02",
71      "overlap": false
72    },
73    "dst_end": {
74      "utc_time": "2026-11-01 TIME 06",
75      "duration": "-1H",
76      "gap": false,
77      "date_time_after": "2026-11-01 TIME 01",
78      "date_time_before": "2026-11-01 TIME 02",
79      "overlap": true
80    }
81  }
82}

You can see that the currency object has been removed from the response. Similarly, company.type and location.continent_code are excluded as well.

Note

If you pass a field or object in excludes that does not exist, no error is returned. The API will still respond using the other parameters.
If a field or object is listed in both include and excludes, include takes priority.
To exclude fields from an object that is not returned by default (such as `security` or `abuse`), include it first.

Example: `include=security&excludes=security.threat_score`

Combine fields and excludes

You can use fields and excludes together to shape the response exactly the way you want.

A common pattern is:

Use fields to limit the response to a specific object (for example, location only).
Use excludes to remove a few fields from that object that you do not need.

1.Get location only and exclude continent fields

Curl

Java

JQuery

Javascript

Node.js

PHP

Python

Swift

Ruby

cUrl

curl -X GET 'https://api.ipgeolocation.io/v3/ipgeo?apiKey=API_KEY&ip=107.161.145.197&fields=location&excludes=location.continent_code,location.continent_name'

Response

1{
2  "ip": "107.161.145.197",
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": "Pennsylvania",
10    "state_code": "US-PA",
11    "district": "Philadelphia County",
12    "city": "Philadelphia",
13    "zipcode": "19102",
14    "latitude": "39.95258",
15    "longitude": "-75.16522",
16    "is_eu": false,
17    "country_flag": "https://ipgeolocation.io/static/flags/us_64.png",
18    "geoname_id": "9849057",
19    "country_emoji": "🇺🇸"
20  }
21}

Note

If a field or object appears in both fields and excludes , it will be included in the response. fields takes priority.

Bulk IP Geolocation Lookup API

This feature is available only on our paid API subscriptions.

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

The requests count per lookup is equal to the total valid IP addresses or domain names passed.
Bulk lookup supports the same query parameters as the single lookup ( include , excludes , and/or fields ).

1.Bulk lookup request

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

Curl

Java

JQuery

Javascript

Node.js

PHP

Python

Swift

Ruby

cUrl

curl -X POST 'https://api.ipgeolocation.io/v2/ipgeo-bulk?apiKey=API_KEY' \
-H 'Content-Type: application/json' \
-d '{"ips":["1.1.1.1","1.2.3.4","4.3.2.1"]}'

Response

1[
2  {
3    "ip": "1.1.1.1",
4    "location": {
5      "continent_code": "OC",
6      "continent_name": "Oceania",
7      "country_code2": "AU",
8      "country_code3": "AUS",
9      "country_name": "Australia",
10      "country_name_official": "Commonwealth of Australia",
11      "country_capital": "Canberra",
12      "state_prov": "Queensland",
13      "state_code": "AU-QLD",
14      "district": "Brisbane",
15      "city": "South Brisbane",
16      "zipcode": "4101",
17      "latitude": "-27.47306",
18      "longitude": "153.01421",
19      "is_eu": false,
20      "country_flag": "https://ipgeolocation.io/static/flags/au_64.png",
21      "geoname_id": "10113228",
22      "country_emoji": "🇦🇺"
23    },
24    "country_metadata": {
25      "calling_code": "+61",
26      "tld": ".au",
27      "languages": [
28        "en-AU"
29      ]
30    },
31    "network": {
32      "connection_type": "",
33      "route": "1.1.1.0/24",
34      "is_anycast": true
35    },
36    "currency": {
37      "code": "AUD",
38      "name": "Australian Dollar",
39      "symbol": "A$"
40    },
41    "asn": {
42      "as_number": "AS13335",
43      "organization": "Cloudflare, Inc.",
44      "country": "US",
45      "type": "BUSINESS",
46      "domain": "cloudflare.com",
47      "date_allocated": "2017-02-17T00:00",
48      "rir": "ARIN"
49    },
50    "company": {
51      "name": "APNIC Research and Development",
52      "type": "",
53      "domain": ""
54    },
55    "time_zone": {
56      "name": "Australia/Brisbane",
57      "offset": 10,
58      "offset_with_dst": 10,
59      "current_time": "2026-02-11 22:19:29.930+1000",
60      "current_time_unix": 1770812369.93,
61      "current_tz_abbreviation": "AEST",
62      "current_tz_full_name": "Australian Eastern Standard Time",
63      "standard_tz_abbreviation": "AEST",
64      "standard_tz_full_name": "Australian Eastern Standard Time",
65      "is_dst": false,
66      "dst_savings": 0,
67      "dst_exists": false,
68      "dst_tz_abbreviation": "",
69      "dst_tz_full_name": "",
70      "dst_start": {},
71      "dst_end": {}
72    }
73  },
74  {
75    "ip": "1.2.3.4",
76    "location": {
77      "continent_code": "OC",
78      "continent_name": "Oceania",
79      "country_code2": "AU",
80      "country_code3": "AUS",
81      "country_name": "Australia",
82      "country_name_official": "Commonwealth of Australia",
83      "country_capital": "Canberra",
84      "state_prov": "Queensland",
85      "state_code": "AU-QLD",
86      "district": "South Brisbane",
87      "city": "Brisbane",
88      "zipcode": "4101",
89      "latitude": "-27.47561",
90      "longitude": "153.01537",
91      "is_eu": false,
92      "country_flag": "https://ipgeolocation.io/static/flags/au_64.png",
93      "geoname_id": "6510512",
94      "country_emoji": "🇦🇺"
95    },
96    "country_metadata": {
97      "calling_code": "+61",
98      "tld": ".au",
99      "languages": [
100        "en-AU"
101      ]
102    },
103    "network": {
104      "connection_type": "",
105      "route": "",
106      "is_anycast": false
107    },
108    "currency": {
109      "code": "AUD",
110      "name": "Australian Dollar",
111      "symbol": "A$"
112    },
113    "asn": {
114      "as_number": "AS0",
115      "organization": "",
116      "country": "",
117      "type": "",
118      "domain": "",
119      "date_allocated": "",
120      "rir": ""
121    },
122    "company": {
123      "name": "Resource Quality Assurance",
124      "type": "",
125      "domain": ""
126    },
127    "time_zone": {
128      "name": "Australia/Brisbane",
129      "offset": 10,
130      "offset_with_dst": 10,
131      "current_time": "2026-02-11 22:19:29.930+1000",
132      "current_time_unix": 1770812369.93,
133      "current_tz_abbreviation": "AEST",
134      "current_tz_full_name": "Australian Eastern Standard Time",
135      "standard_tz_abbreviation": "AEST",
136      "standard_tz_full_name": "Australian Eastern Standard Time",
137      "is_dst": false,
138      "dst_savings": 0,
139      "dst_exists": false,
140      "dst_tz_abbreviation": "",
141      "dst_tz_full_name": "",
142      "dst_start": {},
143      "dst_end": {}
144    }
145  },
146  {
147    "ip": "4.3.2.1",
148    "location": {
149      "continent_code": "NA",
150      "continent_name": "North America",
151      "country_code2": "US",
152      "country_code3": "USA",
153      "country_name": "United States",
154      "country_name_official": "United States of America",
155      "country_capital": "Washington, D.C.",
156      "state_prov": "California",
157      "state_code": "US-CA",
158      "district": "Santa Clara",
159      "city": "Mountain View",
160      "zipcode": "94043-1351",
161      "latitude": "37.42240",
162      "longitude": "-122.08421",
163      "is_eu": false,
164      "country_flag": "https://ipgeolocation.io/static/flags/us_64.png",
165      "geoname_id": "6301403",
166      "country_emoji": "🇺🇸"
167    },
168    "country_metadata": {
169      "calling_code": "+1",
170      "tld": ".us",
171      "languages": [
172        "en-US",
173        "es-US",
174        "haw",
175        "fr"
176      ]
177    },
178    "network": {
179      "connection_type": "",
180      "route": "4.0.0.0/9",
181      "is_anycast": false
182    },
183    "currency": {
184      "code": "USD",
185      "name": "US Dollar",
186      "symbol": "$"
187    },
188    "asn": {
189      "as_number": "AS3356",
190      "organization": "Level 3 Parent, LLC",
191      "country": "US",
192      "type": "BUSINESS",
193      "domain": "level3.com",
194      "date_allocated": "2018-02-20T00:00",
195      "rir": "ARIN"
196    },
197    "company": {
198      "name": "Google LLC",
199      "type": "Hosting",
200      "domain": "google.com"
201    },
202    "time_zone": {
203      "name": "America/Los_Angeles",
204      "offset": -8,
205      "offset_with_dst": -8,
206      "current_time": "2026-02-11 04:19:29.930-0800",
207      "current_time_unix": 1770812369.93,
208      "current_tz_abbreviation": "PST",
209      "current_tz_full_name": "Pacific Standard Time",
210      "standard_tz_abbreviation": "PST",
211      "standard_tz_full_name": "Pacific Standard Time",
212      "is_dst": false,
213      "dst_savings": 0,
214      "dst_exists": true,
215      "dst_tz_abbreviation": "PDT",
216      "dst_tz_full_name": "Pacific Daylight Time",
217      "dst_start": {
218        "utc_time": "2026-03-08 TIME 10",
219        "duration": "+1H",
220        "gap": true,
221        "date_time_after": "2026-03-08 TIME 03",
222        "date_time_before": "2026-03-08 TIME 02",
223        "overlap": false
224      },
225      "dst_end": {
226        "utc_time": "2026-11-01 TIME 09",
227        "duration": "-1H",
228        "gap": false,
229        "date_time_after": "2026-11-01 TIME 01",
230        "date_time_before": "2026-11-01 TIME 02",
231        "overlap": true
232      }
233    }
234  }
235]

Note

Quota and billing: In bulk lookup, the number of credits counted toward your quota equals the number of valid IP addresses in the payload. Bogon, private, or malformed IPs are not counted.

2.Bulk lookup with additional request parameters

This example uses include, fields, and excludes together. The goal is to return only:

location.city
the full currency object)
the security object, but without security.threat_score

Here is how each parameter is used:

Include security (not returned by default): include=security
tSelect only the required objects and fields: fields=location.city,currency,security
Exclude threat_score from security : excludes=security.threat_score

Curl

Java

JQuery

Javascript

Node.js

PHP

Python

Swift

Ruby

cUrl

curl -X POST 'https://api.ipgeolocation.io/v2/ipgeo-bulk?apiKey=API_KEY&include=security&fields=location.city,currency,security&exclude=security.threat_score' \
-H 'Content-Type: application/json' \
-d '{"ips":["107.161.145.197","107.161.145.196","107.161.145.198"]}'

Response

1[
2  {
3    "ip": "107.161.145.197",
4    "location": {
5      "city": "Philadelphia"
6    },
7    "currency": {
8      "code": "USD",
9      "name": "US Dollar",
10      "symbol": "$"
11    },
12    "security": {
13      "threat_score": 5,
14      "is_tor": false,
15      "is_proxy": false,
16      "proxy_provider_names": [],
17      "proxy_confidence_score": 0,
18      "proxy_last_seen": "",
19      "is_residential_proxy": false,
20      "is_vpn": false,
21      "vpn_provider_names": [],
22      "vpn_confidence_score": 0,
23      "vpn_last_seen": "",
24      "is_relay": false,
25      "relay_provider_name": "",
26      "is_anonymous": false,
27      "is_known_attacker": false,
28      "is_bot": false,
29      "is_spam": false,
30      "is_cloud_provider": true,
31      "cloud_provider_name": "LightWave Networks"
32    }
33  },
34  {
35    "ip": "107.161.145.196",
36    "location": {
37      "city": "Philadelphia"
38    },
39    "currency": {
40      "code": "USD",
41      "name": "US Dollar",
42      "symbol": "$"
43    },
44    "security": {
45      "threat_score": 5,
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": false,
60      "is_bot": false,
61      "is_spam": false,
62      "is_cloud_provider": true,
63      "cloud_provider_name": "LightWave Networks"
64    }
65  },
66  {
67    "ip": "107.161.145.198",
68    "location": {
69      "city": "Philadelphia"
70    },
71    "currency": {
72      "code": "USD",
73      "name": "US Dollar",
74      "symbol": "$"
75    },
76    "security": {
77      "threat_score": 35,
78      "is_tor": false,
79      "is_proxy": false,
80      "proxy_provider_names": [],
81      "proxy_confidence_score": 0,
82      "proxy_last_seen": "",
83      "is_residential_proxy": false,
84      "is_vpn": false,
85      "vpn_provider_names": [],
86      "vpn_confidence_score": 0,
87      "vpn_last_seen": "",
88      "is_relay": false,
89      "relay_provider_name": "",
90      "is_anonymous": false,
91      "is_known_attacker": true,
92      "is_bot": false,
93      "is_spam": false,
94      "is_cloud_provider": true,
95      "cloud_provider_name": "LightWave Networks"
96    }
97  }
98]

Curl

Java

JQuery

Javascript

Node.js

PHP

Python

Swift

Ruby

cUrl

curl -X POST 'https://api.ipgeolocation.io/v2/ipgeo-bulk?apiKey=API_KEY' \
-H 'Content-Type: application/json' \
-d '{"ips":["1.1.1.1","1.2.3.4","4.3.2.1"]}'

Plan-wise Reference to IPGeolocation API Response

This section documents every field that can appear in the unified IPGeolocation API response. Each table covers one JSON object, and the Availability column shows the minimum plan required to access that field.

Field availability is cumulative: everything available in the Free plan is also included in any Paid plan.

1.Full Response Examples

I.Free Plan

Response

1{
2  "ip": "2.56.188.34",
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": "Texas",
12    "state_code": "US-TX",
13    "district": "Dallas",
14    "city": "Dallas",
15    "zipcode": "75201",
16    "latitude": "32.77822",
17    "longitude": "-96.79512",
18    "is_eu": false,
19    "country_flag": "https://ipgeolocation.io/static/flags/us_64.png",
20    "geoname_id": "4684902",
21    "country_emoji": "🇺🇸"
22  },
23  "country_metadata": {
24    "calling_code": "+1",
25    "tld": ".us",
26    "languages": [
27      "en-US",
28      "es-US",
29      "haw",
30      "fr"
31    ]
32  },
33  "currency": {
34    "code": "USD",
35    "name": "US Dollar",
36    "symbol": "$"
37  },
38  "asn": {
39    "as_number": "AS62240",
40    "organization": "Clouvider Limited",
41    "country": "GB"
42  },
43  "time_zone": {
44    "name": "America/Chicago",
45    "offset": -6,
46    "offset_with_dst": -6,
47    "current_time": "2026-02-11 06:28:20.432-0600",
48    "current_time_unix": 1770812900.432,
49    "current_tz_abbreviation": "CST",
50    "current_tz_full_name": "Central Standard Time",
51    "standard_tz_abbreviation": "CST",
52    "standard_tz_full_name": "Central Standard Time",
53    "is_dst": false,
54    "dst_savings": 0,
55    "dst_exists": true,
56    "dst_tz_abbreviation": "CDT",
57    "dst_tz_full_name": "Central Daylight Time",
58    "dst_start": {
59      "utc_time": "2026-03-08 TIME 08",
60      "duration": "+1H",
61      "gap": true,
62      "date_time_after": "2026-03-08 TIME 03",
63      "date_time_before": "2026-03-08 TIME 02",
64      "overlap": false
65    },
66    "dst_end": {
67      "utc_time": "2026-11-01 TIME 07",
68      "duration": "-1H",
69      "gap": false,
70      "date_time_after": "2026-11-01 TIME 01",
71      "date_time_before": "2026-11-01 TIME 02",
72      "overlap": true
73    }
74  }
75}

II.Paid Plan

Response

1{
2  "ip": "2.56.188.34",
3  "hostname": "2.56.188.34",
4  "location": {
5    "continent_code": "NA",
6    "continent_name": "North America",
7    "country_code2": "US",
8    "country_code3": "USA",
9    "country_name": "United States",
10    "country_name_official": "United States of America",
11    "country_capital": "Washington, D.C.",
12    "state_prov": "Texas",
13    "state_code": "US-TX",
14    "district": "Dallas",
15    "city": "Dallas",
16    "locality": "Dallas",
17    "accuracy_radius": "9.61",
18    "confidence": "medium",
19    "dma_code": "623",
20    "zipcode": "75201",
21    "latitude": "32.77822",
22    "longitude": "-96.79512",
23    "is_eu": false,
24    "country_flag": "https://ipgeolocation.io/static/flags/us_64.png",
25    "geoname_id": "4684902",
26    "country_emoji": "🇺🇸"
27  },
28  "country_metadata": {
29    "calling_code": "+1",
30    "tld": ".us",
31    "languages": [
32      "en-US",
33      "es-US",
34      "haw",
35      "fr"
36    ]
37  },
38  "network": {
39    "connection_type": "",
40    "route": "2.56.188.0/22",
41    "is_anycast": false
42  },
43  "currency": {
44    "code": "USD",
45    "name": "US Dollar",
46    "symbol": "$"
47  },
48  "asn": {
49    "as_number": "AS62240",
50    "organization": "Clouvider Limited",
51    "country": "GB",
52    "type": "HOSTING",
53    "domain": "clouvider.net",
54    "date_allocated": "2025-12-29T12:48:31",
55    "rir": "RIPE"
56  },
57  "company": {
58    "name": "Packethub S.A.",
59    "type": "BUSINESS",
60    "domain": "packethub.com"
61  },
62  "security": {
63    "threat_score": 80,
64    "is_tor": false,
65    "is_proxy": true,
66    "proxy_provider_names": [
67      "Zyte Proxy"
68    ],
69    "proxy_confidence_score": 90,
70    "proxy_last_seen": "2025-12-12",
71    "is_residential_proxy": true,
72    "is_vpn": true,
73    "vpn_provider_names": [
74      "Nord VPN"
75    ],
76    "vpn_confidence_score": 90,
77    "vpn_last_seen": "2026-01-19",
78    "is_relay": false,
79    "relay_provider_name": "",
80    "is_anonymous": true,
81    "is_known_attacker": true,
82    "is_bot": false,
83    "is_spam": false,
84    "is_cloud_provider": true,
85    "cloud_provider_name": "Packethub S.A."
86  },
87  "abuse": {
88    "route": "2.56.188.32/27",
89    "country": "US",
90    "name": "Packethub S.A. Abuse Department",
91    "organization": "",
92    "kind": "group",
93    "address": "Packethub S.A., Office 76, Plaza 2000, 50 Street and Marbella, Bella Vista, Panama City, 0823, Republic of Panama",
94    "emails": [
95      "abuse@packethub.tech"
96    ],
97    "phone_numbers": [
98      "+5078336503"
99    ]
100  },
101  "time_zone": {
102    "name": "America/Chicago",
103    "offset": -6,
104    "offset_with_dst": -6,
105    "current_time": "2026-02-11 06:28:15.544-0600",
106    "current_time_unix": 1770812895.544,
107    "current_tz_abbreviation": "CST",
108    "current_tz_full_name": "Central Standard Time",
109    "standard_tz_abbreviation": "CST",
110    "standard_tz_full_name": "Central Standard Time",
111    "is_dst": false,
112    "dst_savings": 0,
113    "dst_exists": true,
114    "dst_tz_abbreviation": "CDT",
115    "dst_tz_full_name": "Central Daylight Time",
116    "dst_start": {
117      "utc_time": "2026-03-08 TIME 08",
118      "duration": "+1H",
119      "gap": true,
120      "date_time_after": "2026-03-08 TIME 03",
121      "date_time_before": "2026-03-08 TIME 02",
122      "overlap": false
123    },
124    "dst_end": {
125      "utc_time": "2026-11-01 TIME 07",
126      "duration": "-1H",
127      "gap": false,
128      "date_time_after": "2026-11-01 TIME 01",
129      "date_time_before": "2026-11-01 TIME 02",
130      "overlap": true
131    }
132  },
133  "user_agent": {
134    "user_agent_string": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/143.0.0.0 Safari/537.36",
135    "name": "Chrome",
136    "type": "Browser",
137    "version": "143",
138    "version_major": "143",
139    "device": {
140      "name": "Linux Desktop",
141      "type": "Desktop",
142      "brand": "Unknown",
143      "cpu": "Intel x86_64"
144    },
145    "engine": {
146      "name": "Blink",
147      "type": "Browser",
148      "version": "143",
149      "version_major": "143"
150    },
151    "operating_system": {
152      "name": "Linux",
153      "type": "Desktop",
154      "version": "??",
155      "version_major": "??",
156      "build": "??"
157    }
158  }
159}

Reference to IPGeolocation API Response

1.Standalone fields reference

These fields can appear at the root level of the response.

Field	Type	Description	Can be empty?	Availability
ip	string	The IP address used for the lookup (IPv4 or IPv6).	No	FREE
domain	string	The input domain, returned only for domain-based lookups.	No	PAID
hostname	string	Reverse DNS hostname (PTR) for the input IP; returns the input IP if not resolvable.	No	PAID

2. `location` json object reference

This object is included in the response by default (no include parameter required).

Field	Type	Description	Can be empty?	Availability
continent_code	string	Continent code as 2 uppercase letters (set: `AF` , `AN` , `AS` , `EU` , `NA` , `OC` , `SA` ).	No	FREE
continent_name	string	Continent name, like `Europe` .	No	FREE
country_code2	string	Country code in ISO 3166-1 alpha-2 format (2 uppercase letters), like `CZ` .	No	FREE
country_code3	string	Country code in ISO 3166-1 alpha-3 format (3 uppercase letters), like `CZE` .	No	FREE
country_name	string	Common country name, like `Czech Republic` .	No	FREE
country_name_official	string	Official country name (ISO-style), when different from `country_name` .	No	FREE
country_capital	string	Capital city for the country, like `Prague` .	No	FREE
state_prov	string	State/province/region name for the IP location.	Yes	FREE
state_code	string	State/province/region code; format varies by country (often ISO 3166-2 or a local short code).	Yes	FREE
district	string	District/county name, if available.	Yes	FREE
city	string	City name, if available.	Yes	FREE
locality	string	Smaller area within the city (neighborhood/suburb); may match `city` .	Yes	PAID
accuracy_radius	string	Estimated accuracy radius in kilometers (numeric string) around `latitude` / `longitude` (example: `9.333` ).	Yes	PAID
confidence	string	Location confidence level as a lowercase set: `low` , `medium` , `high` .	Yes	PAID
dma_code	string	US-only DMA market code as digits in a string (example: `501` ).	Yes	PAID
zipcode	string	Postal/ZIP code; format varies by country (digits/letters/spaces), like `779 00` .	Yes	FREE
latitude	string	Latitude in decimal degrees (string), range `-90` to `90` (example: `49.59378` ).	No	FREE
longitude	string	Longitude in decimal degrees (string), range `-180` to `180` (example: `17.25088` ).	No	FREE
is_eu	boolean	`true` if the country is in the European Union.	No	FREE
country_flag	string	Country flag image URL.	No	FREE
geoname_id	string	GeoNames place ID as a numeric string (digits), when available.	Yes	FREE
country_emoji	string	Unicode country flag emoji (example: `🇨🇿` ).	Yes	FREE

3. `country_metadata` json object reference

This object is included in the response by default (no include parameter required).

Field	Type	Description	Can be empty?	Availability
calling_code	string	International dialing prefix for the country (example: `+420` ).	No	FREE
tld	string	Country-code top-level domain assigned to the country (example: `.cz` ).	No	FREE
languages	list of strings	List of common language codes spoken in the country (ISO 639-1).	No	FREE

4. `currency` json object reference

This object is included in the response by default (no include parameter required).

Field	Type	Description	Can be empty?	Availability
code	string	Currency code in ISO 4217 format (3 uppercase letters), like `USD` .	Yes	FREE
name	string	Currency name for the ISO 4217 code, like `US Dollar` .	Yes	FREE
symbol	string	Currency symbol used for display, like `$` .	Yes	FREE

5. `asn` json object reference

This object is included in the response by default (no include parameter required).

Field	Type	Description	Can be empty?
ip	string	IP address for which ASN data is required (appears only when IP is queried).	Yes
asn.as_number	string	Complete Autonomous System Number that was looked up.	Yes
asn.organization	string	The name of the organization to which that ASN is assigned.	Yes
asn.country	string	The two-letter country code where the organization is registered.	Yes
asn.asn_name	string	The official ASN handle.	Yes
asn.type	string	Type of the ASN (e.g., “isp”, “hosting”).	Yes
asn.domain	string	The domain associated with the ASN.	Yes
asn.date_allocated	string	The date the ASN was originally allocated.	Yes
asn.allocation_status	string	Current status of the ASN (“assigned”, “allocated”, etc.).	Yes
asn.num_of_ipv4_routes	string	Number of distinct IPv4 prefixes announced by this ASN.	Yes
asn.num_of_ipv6_routes	string	Number of distinct IPv6 prefixes announced by this ASN.	Yes
asn.peers	array	Directly connected ASes (asNumber, description, country).	Yes
asn.downstreams	array	Downstream (customer) ASNs with their details.	Yes
asn.upstreams	array	Upstream (provider) ASNs with their details.	Yes
asn.routes	array	IPv4 and IPv6 prefixes managed by the provided ASN.	Yes
asn.whois_response	string	Raw WHOIS record text returned for the ASN.	Yes

Note

Free plan subscribers receive as_number , organization , and country in the asn object. Paid plan subscribers receive all fields listed in the ASN table above.

For deeper ASN intelligence on paid plans, use the dedicated ASN API endpoint ( /v3/asn ). It supports lookups by IPv4, IPv6, or ASN and returns additional data beyond the unified response, such as routes, upstreams, downstreams, and the ASN WHOIS details. Each dedicated ASN lookup costs 1 credit. For details, refer to the official ASN API documentation.

6. `network` json object reference

This object is included in the response by default (no include parameter required).

Field	Type	Description	Can be empty?	Availability
as_number	string	ASN identifier in `AS<number>` format (example: `AS13036` ) associated with the IP’s network.	Yes	FREE
organization	string	ASN operator name (typically the organization registered for the ASN).	Yes	FREE
country	string	ASN registration country as ISO 3166-1 alpha-2 (2 uppercase letters), like `CZ` .	Yes	FREE
type	string	ASN category (set), like `ISP` , `HOSTING` , `BUSINESS` , `EDUCATION` , `GOVERNMENT` (when available).	Yes	PAID
domain	string	ASN operator domain name (no scheme), like `t-mobile.cz` .	Yes	PAID
date_allocated	string	ASN allocation/registration date in `YYYY-MM-DD` format, when available (example: `2021-11-19` ).	Yes	PAID
rir	string	RIR that allocated the ASN (set), like `RIPE` , `ARIN` , `APNIC` , `LACNIC` , `AFRINIC` .	Yes	PAID
connection_type	string	Network access type classification (set), like `DSL` , `CABLE` , `MOBILE` , `WIRELESS` , `5G` etc. (when available).	Yes	PAID
route	string	Network prefix in CIDR notation ( `<ip>/<prefix_length>` ), like `2.36.96.0/22` , that contains the IP.	Yes	PAID
is_anycast	boolean	`true` if the IP is anycast (same IP announced from multiple locations).	No	PAID

7. `company` json object reference

This object is included in the response by default (no include parameter required).

Field	Type	Description	Can be empty?	Availability
name	string	Company name mapped to the IP (often the ISP or network operator).	Yes	PAID
type	string	Company category (set), like `ISP` , `HOSTING` , `BUSINESS` , `EDUCATION` , `GOVERNMENT` (when available).	Yes	PAID
domain	string	Company domain name (no scheme), like `verizon.co.uk` , when available.	Yes	PAID

8. `time_zone` json object reference

This object is included in the response by default (no include parameter required).

Field	Type	Description	Can be empty?	Availability
name	string	Time zone in IANA TZDB format (example: `America/Los_Angeles` ).	No	FREE
offset	float	Standard time UTC offset in hours (example: `-8` for UTC-08:00).	No	FREE
offset_with_dst	float	Current effective UTC offset in hours, including DST when active.	No	FREE
date	string	Local date in `YYYY-MM-DD` for the time zone.	No	FREE
date_time	string	Local date/time in `YYYY-MM-DD HH:mm:ss` .	No	FREE
date_time_txt	string	Local date/time as a human-readable string (example: `Wednesday, February 11, 2026 09:02:24` ).	No	FREE
date_time_wti	string	Local date/time in RFC 2822-style format (example: `Wed, 11 Feb 2026 09:02:24 -0800` ).	No	FREE
date_time_ymd	string	Local date/time in `YYYY-MM-DDTHH:mm:ss±ZZZZ` format (example: `2026-02-11T09:02:24-0800` ).	No	FREE
date_time_unix	float	Local time as Unix epoch seconds (may include decimals).	No	FREE
time_24	string	Local time in 24-hour format `HH:mm:ss` .	No	FREE
time_12	string	Local time in 12-hour format `hh:mm:ss AM/PM` .	No	FREE
week	int	Week number within the year (1–53), based on the API’s week rule.	No	FREE
month	int	Month number (1–12).	No	FREE
year	int	4-digit year (example: `2026` ).	No	FREE
year_abbr	string	2-digit year string (example: `26` ).	No	FREE
current_tz_abbreviation	string	Current time zone abbreviation (example: `PST` ).	Yes	FREE
current_tz_full_name	string	Current time zone full name (example: `Pacific Standard Time` ).	Yes	FREE
standard_tz_abbreviation	string	Standard (non-DST) abbreviation (example: `PST` ).	Yes	FREE
standard_tz_full_name	string	Standard (non-DST) full name.	Yes	FREE
is_dst	boolean	`true` if DST is active at the returned local time.	No	FREE
dst_savings	float	DST shift amount in hours (example: `1` ). `0` when DST is not active.	No	FREE
dst_exists	boolean	`true` if the time zone observes DST at any point in the year; when `true` , `dst_start` and `dst_end` are present.	No	FREE
dst_tz_abbreviation	string	DST abbreviation used when DST is active (example: `PDT` ).	Yes	FREE
dst_tz_full_name	string	DST full name used when DST is active (example: `Pacific Daylight Time` ).	Yes	FREE
dst_start.utc_time	string	DST start moment in UTC (string; format follows API output).	Yes	FREE
dst_start.duration	string	Clock change at DST start in hours (positive means clocks move forward). Example: `1.00H` .	Yes	FREE
dst_start.gap	boolean	`true` if local time jumps forward and some local times do not exist.	Yes	FREE
dst_start.date_time_after	string	Local date/time immediately after the DST start transition.	Yes	FREE
dst_start.date_time_before	string	Local date/time immediately before the DST start transition.	Yes	FREE
dst_start.overlap	boolean	`true` if local times repeat at DST start (rare; most zones have a gap instead).	Yes	FREE
dst_end.utc_time	string	DST end moment in UTC (string; format follows API output).	Yes	FREE
dst_end.duration	string	Clock change at DST end in hours (negative means clocks move back). Example: `-1.00H` .	Yes	FREE
dst_end.gap	boolean	`true` if local time jumps forward at DST end (rare; most zones have an overlap instead).	Yes	FREE
dst_end.date_time_after	string	Local date/time immediately after the DST end transition.	Yes	FREE
dst_end.date_time_before	string	Local date/time immediately before the DST end transition.	Yes	FREE
dst_end.overlap	boolean	`true` if local times repeat (clocks move back) and the same local time occurs twice.	Yes	FREE

Note

All the time zone fields listed above are also available via the dedicated Time Zone API (/v3/timezone), which is accessible to both Free and Paid subscribers. Each successful lookup costs 1 credit.

The dedicated Time Zone API supports additional lookup methods beyond IP, including time zone name, IATA code, ICAO code, LOCODE, latitude/longitude, and location. For time conversions, use the Time Zone Conversion endpoint (/v3/timezone/convert), which supports the same lookup methods.

For more details, refer to the Time Zone API documentation.

9. `user_agent` json object reference

This object is included in the response by default (no include parameter required).

Field	Type	Description	Can be empty?	Availability
user_agent_string	string	Raw User-Agent string used for parsing (from the request `User-Agent` header or provided UA input).	Yes	PAID
name	string	Detected user agent product name (example: `Chrome` ).	Yes	PAID
type	string	User agent category (enum), like `Browser` , `Mobile App` , `Bot` (when available).	Yes	PAID
version	string	Full product version string (example: `143.0.0.0` ).	Yes	PAID
version_major	string	Major version extracted from `version` (example: `143` ).	Yes	PAID
device.name	string	Detected device label (example: `Linux Desktop` ).	Yes	PAID
device.type	string	Device category (enum), like `Desktop` , `Mobile` , `Tablet` , `Bot` .	Yes	PAID
device.brand	string	Device vendor/brand when identified (example: `Apple` , `Samsung` ).	Yes	PAID
device.cpu	string	CPU / architecture string (example: `Intel x86_64` , `ARM64` ) when detected.	Yes	PAID
engine.name	string	Rendering engine name (example: `Blink` , `WebKit` , `Gecko` ).	Yes	PAID
engine.type	string	Engine category (typically `Browser` ).	Yes	PAID
engine.version	string	Full engine version string, when available.	Yes	PAID
engine.version_major	string	Major engine version extracted from `engine.version` , when available.	Yes	PAID
operating_system.name	string	Operating system name (example: `Linux` , `Windows` , `Android` ).	Yes	PAID
operating_system.type	string	OS category (enum), like `Desktop` , `Mobile` , `Server` .	Yes	PAID
operating_system.version	string	OS version string, when available (example: `14.4` , `11` ).	Yes	PAID
operating_system.version_major	string	Major OS version extracted from `operating_system.version` , when available.	Yes	PAID
operating_system.build	string	OS build identifier, when available (example: `22631` ).	Yes	PAID

Note

For all possible values of the User Agent type fields, please check here.

The User Agent Parser API is also available as a dedicated endpoint (/v3/user-agent) for both Free and Paid subscribers. Each successful lookup costs 1 credit. Free plan subscribers cannot include the user_agent module in the unified IP Geolocation API response, which is why its availability in the table above is marked as PAID.

For more details, refer to the User Agent Parser API documentation.

For all possible values of the User Agent type fields, please check here

11. `security` json object reference

This object is included in the response by default (no include=security parameter required).

Field	Type	Description	Can be empty?	Availability
threat_score	number	Aggregate risk score from 0 to 100. Higher means higher likelihood of abusive or anonymous usage.	No	PAID
is_tor	boolean	`true` if the IP matches a Tor exit node.	No	PAID
is_proxy	boolean	`true` if the IP is associated with a proxy service/network.	No	PAID
proxy_provider_names	array[string]	Detected proxy provider names, when identified.	Yes	PAID
proxy_confidence_score	number	Proxy detection confidence from 0 to 100. `0` if not detected or unknown.	No	PAID
proxy_last_seen	string	Last observed proxy activity date in `YYYY-MM-DD` , when available.	Yes	PAID
is_residential_proxy	boolean	`true` if the IP is linked to a residential proxy network (consumer ISP exits).	No	PAID
is_vpn	boolean	`true` if the IP is associated with a VPN service/network.	No	PAID
vpn_provider_names	array[string]	Detected VPN provider names, when identified.	Yes	PAID
vpn_confidence_score	number	VPN detection confidence from 0 to 100. `0` if not detected or unknown.	No	PAID
vpn_last_seen	string	Last observed VPN activity date in `YYYY-MM-DD` , when available.	Yes	PAID
is_relay	boolean	`true` if the IP is associated with a relay/anonymization relay network.	No	PAID
relay_provider_name	string	Relay provider/name, when identified.	Yes	PAID
is_anonymous	boolean	`true` if any anonymity signal is present (VPN, proxy, Tor, or relay).	No	PAID
is_known_attacker	boolean	`true` if the IP is flagged for known attacker behavior based on your detection sources.	No	PAID
is_bot	boolean	`true` if the IP is associated with automated/bot activity.	No	PAID
is_spam	boolean	`true` if the IP is associated with spam activity.	No	PAID
is_cloud_provider	boolean	`true` if the IP belongs to a cloud or hosting provider range.	No	PAID
cloud_provider_name	string	Cloud/hosting provider name, when identified.	Yes	PAID

Note

The security fields listed above are also available via the dedicated IP Security API (/v3/security). Each successful lookup through dedicated IP Security API endpoint costs 2 credits.

If security is included in the unified IP Geolocation API response, the request costs 3 credits total: 2 credits for the security module and 1 credit for the rest of the unified lookup data.

For more details on the Security API, refer to the IP Security API documentation. For credit rules and billing details, refer to the Credits & Usage page.

12. `abuse` json object reference

Field	Type	Description	Can be empty?	Availability
route	string	Abuse-handling IP range in CIDR notation ( `<ip>/<prefix_length>` ), like `195.39.4.200/29` , when available.	Yes	PAID
country	string	Responsible entity country as ISO 3166-1 alpha-2 (2 uppercase letters), like `CZ` .	Yes	PAID
name	string	Display name for the abuse contact (team/person/org) from registry data.	Yes	PAID
organization	string	Organization name for the abuse contact, when provided separately from `name` .	Yes	PAID
kind	string	Contact type from registry data (enum), like `group` , `individual` , `organization` .	Yes	PAID
address	string	Postal address for the contact; may include line breaks ( `\n` ).	Yes	PAID
emails	array[string]	Abuse contact email addresses (one or more).	Yes	PAID
phone_numbers	array[string]	Abuse contact phone numbers, typically in international format (often E.164).	Yes	PAID

Note

The IP Abuse Contact fields listed above are also available via the dedicated IP Abuse Contact API (/v3/abuse). Each successful lookup through the dedicated IP Abuse Contact API endpoint costs 1 credit.

If abuse contact data is included in the unified IP Geolocation API response, the request costs 2 credits total: 1 credit for the abuse module and 1 credit for the rest of the unified lookup data.

For more details on the Security API, refer to the IP Abuse Contact API documentation. For credit rules and billing details, refer to the Credits & Usage page.

Error Codes

IP Geolocation 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 Geolocation 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, 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 `ipgeo-bulk` endpoint. If more than 50,000 IP addresses are provided while querying from `ipgeo-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 Geolocation 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 Geolocation API is made using API key for a database subscription When the request to IP Geolocation 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 IP-hostname lookup, IP-security lookup or user-agent parsing endpoint is called using free subsciption API key. If bulk IP to geolocation look-ups endpoint is called using free subscription API key.
403 Forbidden	If IP to geolocation look-up for a domain name is done using a 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 `ipgeo-bulk` endpoint and GET method for `ipgeo` 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 `ipgeo-bulk` endpoint is mising, 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

The IP Location API provides detailed geographical data based on IP addresses, including information like country, city, state, latitude, longitude, user’s time zone information, currency details, ISP, ASN, and organization name. You can also access threat intelligence, VPN/proxy status, and device data from the user-agent string.

Yes, the IP Location API supports batch IP address lookups, allowing you to query up to 50,000 IPs in a single request. However, this feature is available only on paid plans. The requests made in the batch will count towards your total API usage.

IPGeolocation offers SDKs for popular programming languages such as Java, Python, JavaScript, jQuery, TypeScript, C#, and PHP. These SDKs simplify the integration of the IP Location API into your projects. Additionally, detailed guides are available to assist with integrating the API and databases with Splunk.

Our IP Location API data updates every 24 hours. Our downloadable databases are available with weekly and monthly updates, providing you with the most up-to-date geolocation information.

The IP Location API ensures data security with secure HTTPS connections for all API endpoints. Our infrastructure features globally distributed data and edge nodes, enhancing reliability and protection against DDoS attacks. Additionally, IPGeolocation complies with data protection regulations, including the General Data Protection Regulation (GDPR), to ensure user privacy and data security.

IP Geolocation identifies the physical location of a device by analyzing its IP address along with data from internet registries, ISPs, network routing, and user reports. It helps determine key details such as country, state/region, city, ZIP code, ISP, and more. ipgeolocation.io combines multiple reliable data sources and frequent updates to deliver accurate, real-time location insights for both IPv4 and IPv6 addresses.

IP Geolocation is typically over 99% accurate at the country level and around 85% or higher at the city level, with a 20–50 km accuracy radius depending on the region and ISP. ipgeolocation.io maintains high accuracy by updating its database daily and using reliable data sources to deliver precise geolocation, along with ISP, timezone, and currency details.

IP Geolocation helps personalize user experiences, display region-specific content, detect fraud, enforce compliance, and improve analytics. With ipgeolocation.io’s API, developers can easily integrate features like automatic timezone detection, localized content, and fraud prevention using security data such as is_bot, is_proxy, and more.

An IP Geolocation API allows applications to retrieve detailed location data about an IP address through simple API requests. ipgeolocation.io’s API returns data such as country, city, ISP, timezone, currency, and even detects VPN, proxy, and TOR usage, making it easy to enhance applications with location intelligence.

You can get an API key by signing up for a free account at ipgeolocation.io. Once registered and logged into your dashboard, you’ll find your unique API key, which you can use to send requests to the API.

Yes, ipgeolocation.io offers a free IP Geolocation API plan that includes up to 1,000 requests per day. The free plan covers core features like country, city, ISP, timezone, and currency details, with options to upgrade for higher limits and advanced capabilities like VPN, Proxy, TOR detection, and more.

IP Geolocation API

Overview