Single IP Geolocation Lookup API

Single IP Location API can be used in two ways to lookup any IP address or domain name with JSON or XML response. The URL for this endpoint is https://api.ipgeolocation.io/ipgeo and its full JSON response is below:

1{
2  "ip": "8.8.8.8",
3  "hostname": "dns.google",
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  "calling_code": "+1",
20  "country_tld": ".us",
21  "languages": "en-US,es-US,haw,fr",
22  "country_flag": "https://ipgeolocation.io/static/flags/us_64.png",
23  "geoname_id": "6301403",
24  "isp": "Google LLC",
25  "connection_type": "",
26  "organization": "Google LLC",
27  "country_emoji": "🇺🇸",
28  "asn": "AS15169",
29  "currency": {
30    "code": "USD",
31    "name": "US Dollar",
32    "symbol": "$"
33  },
34  "time_zone": {
35    "name": "America/Los_Angeles",
36    "offset": -8,
37    "offset_with_dst": -7,
38    "current_time": "2024-09-19 00:19:04.376-0700",
39    "current_time_unix": 1726730344.376,
40    "is_dst": true,
41    "dst_savings": 1,
42    "dst_exists": true,
43    "dst_start": {
44      "utc_time": "2024-03-10 TIME 10",
45      "duration": "+1H",
46      "gap": true,
47      "dateTimeAfter": "2024-03-10 TIME 03",
48      "dateTimeBefore": "2024-03-10 TIME 02",
49      "overlap": false
50    },
51    "dst_end": {
52      "utc_time": "2024-11-03 TIME 09",
53      "duration": "-1H",
54      "gap": false,
55      "dateTimeAfter": "2024-11-03 TIME 01",
56      "dateTimeBefore": "2024-11-03 TIME 02",
57      "overlap": true
58    }
59  }
60}

Without Passing an IP Address

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

Curl

Go

Java

JQuery

Javascript

Node.js

PHP

Python

Swift

Ruby

curl 'https://api.ipgeolocation.io/ipgeo?apiKey=API_KEY'

Note: apiKey parameter can also be ommitted from your API request when this endpoint is called from client side using Request Origin.

Bulk IP Geolocation Lookup API

This feature is available only on the paid API subscriptions. This endpoint allows you to perform the geolocation lookup for multiple IPv4, IPv6 addresses or domain names (maximum 50,000) at the same time. The requests count per lookup is equal to total IP addresses or domain names passed.

To perform bulk IP Geolocation Lookup, send a POST request and pass the "ips" array as JSON data along with it. Here is an example to query the geolocation data for multiple IPs at once.

Curl

Go

Java

JQuery

Javascript

Node.js

PHP

Python

Swift

Ruby

curl -X POST 'https://api.ipgeolocation.io/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 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)
• Persian (fa)
• Korean (ko)

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 adderss '1.1.1.1' in Chinese language:

Curl

Go

Java

JQuery

Javascript

Node.js

PHP

Python

Swift

Ruby

curl 'https://api.ipgeolocation.io/ipgeo?apiKey=API_KEY&ip=1.1.1.1&lang=cn'

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.

Filter Responses

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

You can filter the API response in two ways:

• Get the Required Fields Only

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 query parameter fields in the request. Here are a few examples to get only the required fields:

Get City Information Only

Curl

Go

Java

JQuery

Javascript

Node.js

PHP

Python

Swift

Ruby

curl 'https://api.ipgeolocation.io/ipgeo?apiKey=API_KEY&ip=1.1.1.1&fields=city'

Response

Response

1{
2  "ip": "1.1.1.1",
3  "city": "Kecamatan Margorejo"
4}

Get Country Name and Country Code (ISO2) Only

Curl

Go

Java

JQuery

Javascript

Node.js

PHP

Python

Swift

Ruby

curl 'https://api.ipgeolocation.io/ipgeo?apiKey=API_KEY&ip=1.1.1.1&fields=country_code2,country_name'

Response

Response

1{
2  "ip": "1.1.1.1",
3  "country_code2": "ID",
4  "country_name": "Indonesia",
5  "country_name_official": "Republic of Indonesia"
6}

Get the Time Zone Information Only

Curl

Go

Java

JQuery

Javascript

Node.js

PHP

Python

Swift

Ruby

curl 'https://api.ipgeolocation.io/ipgeo?apiKey=API_KEY&ip=8.8.8.8&fields=time_zone'

Response

Response

1{
2  "ip": "8.8.8.8",
3  "time_zone": {
4    "name": "America/Los_Angeles",
5    "offset": -8,
6    "offset_with_dst": -7,
7    "current_time": "2024-09-19 06:18:47.854-0700",
8    "current_time_unix": 1726751927.854,
9    "is_dst": true,
10    "dst_savings": 1,
11    "dst_exists": true,
12    "dst_start": {
13      "utc_time": "2024-03-10 TIME 10",
14      "duration": "+1H",
15      "gap": true,
16      "dateTimeAfter": "2024-03-10 TIME 03",
17      "dateTimeBefore": "2024-03-10 TIME 02",
18      "overlap": false
19    },
20    "dst_end": {
21      "utc_time": "2024-11-03 TIME 09",
22      "duration": "-1H",
23      "gap": false,
24      "dateTimeAfter": "2024-11-03 TIME 01",
25      "dateTimeBefore": "2024-11-03 TIME 02",
26      "overlap": true
27    }
28  }
29}

Get Only the Local Currency Information of Multiple IP Addresses

You can use our filters with Bulk IP Lookup as well. Here is an example:

Curl

Go

Java

JQuery

Javascript

Node.js

PHP

Python

Swift

Ruby

curl -X POST 'https://api.ipgeolocation.io/ipgeo-bulk?apiKey=API_KEY&fields=currency' \
-H 'Content-Type: application/json' \
-d '{ "ips": ["1.0.1.0", "8.8.8.8"] }'

Response

1[
2  {
3    "ip": "1.0.1.0",
4    "currency": {
5      "code": "CNY",
6      "name": "Yuan Renminbi",
7      "symbol": "¥"
8    }
9  },
10  {
11    "ip": "8.8.8.8",
12    "currency": {
13      "code": "USD",
14      "name": "US Dollar",
15      "symbol": "$"
16    }
17  }
18]

Get Geolocation Information Only

We know, most of the times, users are interested in geolocation information only. So, we have added a shortcut for you. You can specify just fields=geo in your query parameter.

Curl

Go

Java

JQuery

Javascript

Node.js

PHP

Python

Swift

Ruby

curl 'https://api.ipgeolocation.io/ipgeo?apiKey=API_KEY&ip=8.8.8.8&fields=geo'

Response

1{
2  "ip": "8.8.8.8",
3  "continent_code": "NA",
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  "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}

• Remove the Unnecessary Fields

Second, you can also filter the API response by specifying the names of fields (except IP address) that you want to remove from the API response. Names of the fields must be passed as a query parameter excludes in the request. Here are a few examples to exclude the unnecessary fields:

Exclude Continent Code, Currency and, Time zone Objects

Curl

Go

Java

JQuery

Javascript

Node.js

PHP

Python

Swift

Ruby

curl 'https://api.ipgeolocation.io/ipgeo?apiKey=API_KEY&ip=8.8.8.8&excludes=continent_code,currency,time_zone'

Response

1{
2  "ip": "8.8.8.8",
3  "continent_name": "North America",
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  "calling_code": "+1",
18  "country_tld": ".us",
19  "languages": "en-US,es-US,haw,fr",
20  "country_flag": "https://ipgeolocation.io/static/flags/us_64.png",
21  "geoname_id": "6301403",
22  "isp": "Google LLC",
23  "connection_type": "",
24  "organization": "Google LLC",
25  "country_emoji": "🇺🇸",
26  "asn": "AS15169"
27}

• Get the Geo Field and Exclude Continent Information

Third, You can combine the fields and excludes query parameters for fully customized API queries. This approach helps you retrieve only the necessary data while reducing response latency. Here's a sample code to demonstrate how to use both parameters effectively:

Curl

Go

Java

JQuery

Javascript

Node.js

PHP

Python

Swift

Ruby

curl 'https://api.ipgeolocation.io/ipgeo?apiKey=API_KEY&ip=8.8.8.8&fields=geo&excludes=continent_code,continent_name'

Response

1{
2  "ip": "8.8.8.8",
3  "country_code2": "US",
4  "country_code3": "USA",
5  "country_name": "United States",
6  "country_name_official": "United States of America",
7  "state_prov": "California",
8  "state_code": "US-CA",
9  "district": "Santa Clara",
10  "city": "Mountain View",
11  "zipcode": "94043-1351",
12  "latitude": "37.42240",
13  "longitude": "-122.08421"
14}

IP-Security Information for an IP Address

IP Geolocation API also provides IP-Security information on all the paid subscriptions, but doesn't respond it 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.

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

Curl

Go

Java

JQuery

Javascript

Node.js

PHP

Python

Swift

Ruby

curl 'https://api.ipgeolocation.io/ipgeo?apiKey=API_KEY&ip=8.8.8.8&fields=geo&include=security'

1{
2  "ip": "8.8.8.8",
3  "continent_code": "NA",
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  "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  "security": {
18    "threat_score": 80,
19    "is_tor": false,
20    "is_proxy": true,
21    "proxy_type": "VPN",
22    "is_anonymous": true,
23    "is_known_attacker": true,
24    "is_spam": false,
25    "is_bot": false,
26    "is_cloud_provider": true
27  }
28}

Hostname Lookup for an IP Address

IPGeolocation API also provide 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 three values hostname, liveHostname, hostnameFallbackLive as a URL parameter include=.

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

Curl

Go

Java

JQuery

Javascript

Node.js

PHP

Python

Swift

Ruby

curl 'https://api.ipgeolocation.io/ipgeo?apiKey=API_KEY&ip=8.8.8.8&fields=geo&include=liveHostname'

1{
2  "ip": "8.8.8.8",
3  "hostname": "dns.google",
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  "state_prov": "California",
11  "state_code": "US-CA",
12  "district": "Santa Clara",
13  "city": "Mountain View",
14  "zipcode": "94043-1351",
15  "latitude": "37.42240",
16  "longitude": "-122.08421",
17  "is_eu": false
18}

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.

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

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.

User-Agent Information for a Device

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=useragent as a query parameter in the URL.

Here is an example to IP Geolocation lookup that includes User-Agent information for a device from which the query originated:

Curl

Go

Java

JQuery

Javascript

Node.js

PHP

Python

Swift

Ruby

curl 'https://api.ipgeolocation.io/ipgeo?apiKey=API_KEY&ip=8.8.8.8&fields=geo&include=useragent'

1{
2  "ip": "8.8.8.8",
3  "continent_code": "NA",
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  "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  "user_agent": {
18    "userAgentString": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/128.0.0.0 Safari/537.36",
19    "name": "Chrome",
20    "type": "Browser",
21    "version": "128",
22    "versionMajor": "128",
23    "device": {
24      "name": "Linux Desktop",
25      "type": "Desktop",
26      "brand": "Unknown",
27      "cpu": "Intel x86_64"
28    },
29    "engine": {
30      "name": "Blink",
31      "type": "Browser",
32      "version": "128",
33      "versionMajor": "128"
34    },
35    "operatingSystem": {
36      "name": "Linux",
37      "type": "Desktop",
38      "version": "??",
39      "versionMajor": "??"
40    }
41  }
42}

Note: To get hostname, IP-Security information, and user-agent information together for an IP address and the device, you can pass include=hostname, security, useragent as a query parameter in the URL.

Reference to IPGeolocation API Response

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:

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:

• IP Geolocation API Java SDK
• IP Geolocation API C-Sharp dotNet SDK
• IP Geolocation API Typescript SDK
• IP Geolocation API PHP SDK
• IP Geolocation API JQuery SDK