Included in
Advance PlanSecurity PlanStandard PlanFree PlanIP Geolocation API
IP Geolocation API provides real-time and accurate geolocation, network, abuse, and security information for any IPv4 or IPv6 address and domain name along with the user-agent detail for the provided user-agent string. You can geolocate your online visitors and provide them the customized user-experience accordingly.
We provide the two endpoints in our IP Lookup API to get geolocation information.
• Standard IPGeolocation API
Accurate IP geolocation with ASN and Company/ISP details. IP security data is not included. See the documentation below for examples.
• IP Security API
Detects VPNs, Tor, proxies, spam sources, attackers, and cloud providers (including names when available), along with standard geolocation, ASN, and Company/ISP data. View Documentation
• Advanced IPGeolocation API
Combines precise IP geolocation data with enhanced ASN and Company data, IP abuse details, and IP Security insights—all accessible via a single /v2/ipgeo endpoint. For full examples and usage guides, please refer to the documentation below.
For client-side calls to the endpoints mentioned below using the Request Origin (available on paid plans only), the apiKey parameter can be omitted.
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/v2/ipgeo and its full JSON response is below:
1{
2 "ip": "8.8.8.8",
3 "hostname": "dns.google",
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": "California",
13 "state_code": "US-CA",
14 "district": "Santa Clara",
15 "city": "Mountain View",
16 "locality": "Mountain View",
17 "accuracy_radius": "5",
18 "confidence": "High",
19 "dma_code": "807",
20 "zipcode": "94043-1351",
21 "latitude": "37.42240",
22 "longitude": "-122.08421",
23 "is_eu": false,
24 "country_flag":
25 "https://ipgeolocation.io/static/flags/us_64.png",
26 "geoname_id": "6301403",
27 "country_emoji": "🇺🇸"
28 },
29 "country_metadata": {
30 "calling_code": "+1",
31 "tld": ".us",
32 "languages": [
33 "en-US",
34 "es-US",
35 "haw",
36 "fr"
37 ]
38 },
39 "network": {
40 "asn": {
41 "as_number": "AS15169",
42 "organization": "Google LLC",
43 "country": "US",
44 "asn_name": "GOOGLE",
45 "type": "isp",
46 "domain": "about.google",
47 "date_allocated": "",
48 "allocation_status": "Assigned",
49 "num_of_ipv4_routes": "1099",
50 "num_of_ipv6_routes": "107",
51 "rir": "ARIN"
52 },
53 "connection_type": "wired",
54 "company": {
55 "name": "Google LLC",
56 "type": "hosting",
57 "domain": "google.com"
58 }
59 },
60 "currency": {
61 "code": "USD",
62 "name": "US Dollar",
63 "symbol": "$"
64 },
65 "security": {
66 "threat_score": 80,
67 "is_tor": false,
68 "is_proxy": true,
69 "proxy_type": "VPN",
70 "proxy_provider": "",
71 "is_anonymous": true,
72 "is_known_attacker": true,
73 "is_spam": false,
74 "is_bot": false,
75 "is_cloud_provider": false,
76 "cloud_provider": ""
77 },
78 "abuse": {
79 "route": "8.8.8.0/24",
80 "country": "US",
81 "handle": "ABUSE5250-ARIN",
82 "name": "Abuse",
83 "organization": "Abuse",
84 "role": "abuse",
85 "kind": "group",
86 "address": "1600 Amphitheatre Parkway, Mountain View, CA, 94043, United States",
87 "emails": [
88 "network-abuse@google.com"
89 ],
90 "phone_numbers": [
91 "+1-650-253-0000"
92 ]
93 },
94 "time_zone": {
95 "name": "America/Los_Angeles",
96 "offset": -8,
97 "offset_with_dst": -7,
98 "current_time": "2025-04-22 04:56:55.430-0700",
99 "current_time_unix": 1745323015.43,
100 "is_dst": true,
101 "dst_savings": 1,
102 "dst_exists": true,
103 "dst_start": {
104 "utc_time": "2025-03-09 TIME 10",
105 "duration": "+1H",
106 "gap": true,
107 "date_time_after": "2025-03-09 TIME 03",
108 "date_time_before": "2025-03-09 TIME 02",
109 "overlap": false
110 },
111 "dst_end": {
112 "utc_time": "2025-11-02 TIME 09",
113 "duration": "-1H",
114 "gap": false,
115 "date_time_after": "2025-11-02 TIME 01",
116 "date_time_before": "2025-11-02 TIME 02",
117 "overlap": true
118 }
119 },
120 "user_agent": {
121 "user_agent_string": "User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_11_2) AppleWebKit/601.3.9 (KHTML, like Gecko) Version/9.0.2 Safari/601.3.9",
122 "name": "Safari",
123 "type": "Browser",
124 "version": "9.0.2",
125 "version_major": "9",
126 "device": {
127 "name": "Apple Macintosh",
128 "type": "Desktop",
129 "brand": "Apple",
130 "cpu": "Intel"
131 },
132 "engine": {
133 "name": "AppleWebKit",
134 "type": "Browser",
135 "version": "601.3.9",
136 "version_major": "601"
137 },
138 "operating_system": {
139 "name": "Mac OS",
140 "type": "Desktop",
141 "version": "10.11.2",
142 "version_major": "10.11",
143 "build": "??"
144 }
145 }
146 }Passing an IPv4, IPv6 Address or a domain
In order to find geolocation information about an IP address or a domain name, pass it as a query parameter ip like below. Note that apiKey is also need to pass as a query parameter for authorization. This endpoint is meant to be called from the server side.
Passing an IPv4
Here's an example to get the geolocation information for the IP address '8.8.8.8'.
curl -X GET 'https://api.ipgeolocation.io/v2/ipgeo?apiKey=API_KEY&ip=8.8.8.8'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 -X GET 'https://api.ipgeolocation.io/v2/ipgeo?apiKey=API_KEY'Bulk IP Geolocation Lookup API
This feature is available only on our paid API subscriptions (STANDARD or ADVANCED). 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 -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 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 '1.1.1.1' in Chinese language.
curl -X GET 'https://api.ipgeolocation.io/v2/ipgeo?apiKey=API_KEY&ip=1.1.1.1&lang=cn'Only the paid plan subscriptions (STANDARD or ADVANCED) 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 location Information Only
curl -X GET 'https://api.ipgeolocation.io/v2/ipgeo?apiKey=API_KEY&ip=1.1.1.1&fields=location'1{
2 "ip": "1.1.1.1",
3 "location": {
4 "continent_code": "OC",
5 "continent_name": "Oceania",
6 "country_code2": "AU",
7 "country_code3": "AUS",
8 "country_name": "Australia",
9 "country_name_official": "Commonwealth of Australia",
10 "country_capital": "Canberra",
11 "state_prov": "Queensland",
12 "state_code": "AU-QLD",
13 "district": "Brisbane",
14 "city": "South Brisbane",
15 "locality": "South Brisbane",
16 "accuracy_radius": "5",
17 "confidence": "High",
18 "zipcode": "4101",
19 "latitude": "-27.47306",
20 "longitude": "153.01421",
21 "is_eu": false,
22 "country_flag":
23 "https://ipgeolocation.io/static/flags/au_64.png",
24 "geoname_id": "10113228",
25 "country_emoji": "🇦🇺"
26 }
27}Get Country Name and Organization Only
curl -X GET 'https://api.ipgeolocation.io/v2/ipgeo?apiKey=API_KEY&ip=1.1.1.1&fields=location.country_name,network.asn.organization'1{
2 "ip": "1.1.1.1",
3 "location": {
4 "country_name": "Australia"
5 },
6 "network": {
7 "asn": {
8 "organization": "Cloudflare, Inc."
9 }
10 }
11}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 -X POST 'https://api.ipgeolocation.io/v2/ipgeo-bulk?apiKey=API_KEY&fields=currency' \
-H 'Content-Type: application/json' \
-d '{"ips":["1.0.1.0","8.8.8.8"]}'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]• Remove the Unnecessary Fields
Second, you can also filter the API response by excluding specific fields (except the IP address) that you don't need. To do this, pass the unwanted field names using the excludes query parameter, with each field represented as a dot-separated path. Here's an example showing how to exclude unnecessary fields:
Exclude Continent Code, Currency and, Network Objects
curl -X GET 'https://api.ipgeolocation.io/v2/ipgeo?apiKey=API_KEY&ip=8.8.8.8&excludes=location.continent_code,currency,network'1{
2 "ip": "8.8.8.8",
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": "California",
11 "state_code": "US-CA",
12 "district": "Santa Clara",
13 "city": "Mountain View",
14 "locality": "Mountain View",
15 "accuracy_radius": "5",
16 "confidence": "High",
17 "zipcode": "94043-1351",
18 "latitude": "37.42240",
19 "longitude": "-122.08421",
20 "is_eu": false,
21 "country_flag":
22 "https://ipgeolocation.io/static/flags/us_64.png",
23 "geoname_id": "6301403",
24 "country_emoji": "🇺🇸"
25 },
26 "country_metadata": {
27 "calling_code": "+1",
28 "tld": ".us",
29 "languages": [
30 "en-US",
31 "es-US",
32 "haw",
33 "fr"
34 ]
35 }
36}• Get the Location fields 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 -X GET 'https://api.ipgeolocation.io/v2/ipgeo?apiKey=API_KEY&ip=8.8.8.8&fields=location&excludes=location.continent_code,location.continent_name'1{
2 "ip": "8.8.8.8",
3 "location": {
4 "country_code2": "US",
5 "country_code3": "USA",
6 "country_name": "United States",
7 "country_name_official": "United States of America",
8 "country_capital": "Washington, D.C.",
9 "state_prov": "California",
10 "state_code": "US-CA",
11 "district": "Santa Clara",
12 "city": "Mountain View",
13 "locality": "Mountain View",
14 "accuracy_radius": "5",
15 "confidence": "High",
16 "zipcode": "94043-1351",
17 "latitude": "37.42240",
18 "longitude": "-122.08421",
19 "is_eu": false,
20 "country_flag":
21 "https://ipgeolocation.io/static/flags/us_64.png",
22 "geoname_id": "6301403",
23 "country_emoji": "🇺🇸"
24 }
25}You can customize the API response by using three query parameters:Â fields= , include= and excludes= . These let you request only the data you need, reducing payload size and improving performance.
When using these filters together, the following rules determine how they interact:
- To request specific fields from nested objects (e.g.,Â
security,abuse, etc.), useÂinclude=Â to name the object, andÂfields=Â to specify which fields you want. - If a field or object appears in bothÂ
fields=Â andÂexcludes=, the field will be included.Âfields=Â takes priority. - Similarly, if a field or object is listed in bothÂ
include=Â andÂexcludes=Â , theÂinclude=Â takes priority. - If both the object name and its specific fields are listed inÂ
fields=Â , the entire object will be included in the response.
IP-Security Information for an IP Address
IP Geolocation API also provides IP-Security information on Advanced API subscription, 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 -X GET 'https://api.ipgeolocation.io/v2/ipgeo?apiKey=API_KEY&ip=8.8.8.8&fields=location&include=security'1{
2 "ip": "8.8.8.8",
3 "location": {
4 "continent_code": "NA",
5 "continent_name": "North America",
6 "country_code2": "US",
7 "country_code3": "USA",
8 "country_name": "United States",
9 "country_name_official": "United States of America",
10 "country_capital": "Washington, D.C.",
11 "state_prov": "California",
12 "state_code": "US-CA",
13 "district": "Santa Clara",
14 "city": "Mountain View",
15 "locality": "Mountain View",
16 "accuracy_radius": "",
17 "zipcode": "94043-1351",
18 "latitude": "37.42240",
19 "longitude": "-122.08421",
20 "is_eu": false,
21 "country_flag": "https://ipgeolocation.io/static/flags/us_64.png",
22 "geoname_id": "6301403",
23 "country_emoji": "🇺🇸"
24 },
25 "security": {
26 "threat_score": 80,
27 "is_tor": false,
28 "is_proxy": true,
29 "proxy_type": "VPN",
30 "proxy_provider": "",
31 "is_anonymous": true,
32 "is_known_attacker": true,
33 "is_spam": false,
34 "is_bot": false,
35 "is_cloud_provider": false,
36 "cloud_provider": ""
37 }
38}Abuse Contact Information for an IP Address
IP Geolocation API can also provide abuse contact information of an IP address on Advanced API subscription, but doesn't respond it by default. To get abuse contact information along with the geolocation information, you must pass the include=abuse as a query parameter in the URL.
Here is an example of an IP Geolocation lookup that includes abuse contact information, along with the country and city associated with the IP address:
curl -X GET 'https://api.ipgeolocation.io/v2/ipgeo?apiKey=API_KEY&ip=1.2.3.4&fields=location.city,location.country_name&include=abuse'1{
2 "ip": "1.2.3.4",
3 "location": {
4 "city": "Brisbane",
5 "country_name": "Australia"
6 },
7 "abuse": {
8 "route": "1.2.3.0/24",
9 "country": "AU",
10 "handle": "IRT-APNICRANDNET-AU",
11 "name": "IRT-APNICRANDNET-AU",
12 "organization": "",
13 "role": "abuse",
14 "kind": "group",
15 "address": "PO Box 3646 South Brisbane, QLD 4101 Australia",
16 "emails": [
17 "helpdesk@apnic.net"
18 ],
19 "phone_numbers": [
20 "+61-7-3858-3188",
21 " +61-7-3858-3199"
22 ]
23 }
24}DMA Code for an IP Address
If you want to get DMA (Designated Market Area) code, which is specifically used in the US for marketing and regional targeting, you can get through the IP Geolocation API on Advanced API subscription. To get DMA code along with the geolocation information, you must pass the include=dma as a query parameter in the URL.
Here is an example of an IP Geolocation lookup that includes dma code, along with the location information associated with the IP address:
curl -X GET 'https://api.ipgeolocation.io/v2/ipgeo?apiKey=API_KEY&ip=8.8.8.8&fields=location&include=dma'1{
2 "ip": "8.8.8.8",
3 "location": {
4 "continent_code": "NA",
5 "continent_name": "North America",
6 "country_code2": "US",
7 "country_code3": "USA",
8 "country_name": "United States",
9 "country_name_official": "United States of America",
10 "country_capital": "Washington, D.C.",
11 "state_prov": "California",
12 "state_code": "US-CA",
13 "district": "Santa Clara",
14 "city": "Mountain View",
15 "locality": "Mountain View",
16 "accuracy_radius": "",
17 "dma_code": "807",
18 "zipcode": "94043-1351",
19 "latitude": "37.42240",
20 "longitude": "-122.08421",
21 "is_eu": false,
22 "country_flag":
23 "https://ipgeolocation.io/static/flags/us_64.png",
24 "geoname_id": "6301403",
25 "country_emoji": "🇺🇸"
26 }
27}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 -X GET 'https://api.ipgeolocation.io/v2/ipgeo?apiKey=API_KEY&ip=8.8.8.8&fields=location&include=liveHostname'1{
2 "ip": "8.8.8.8",
3 "hostname": "dns.google",
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": "California",
13 "state_code": "US-CA",
14 "district": "Santa Clara",
15 "city": "Mountain View",
16 "locality": "Mountain View",
17 "accuracy_radius": "5",
18 "confidence": "High",
19 "zipcode": "94043-1351",
20 "latitude": "37.42240",
21 "longitude": "-122.08421",
22 "is_eu": false,
23 "country_flag":
24 "https://ipgeolocation.io/static/flags/us_64.png",
25 "geoname_id": "6301403",
26 "country_emoji": "🇺🇸"
27 }
28} 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.
Time Zone Information for an IP Address
IP Geolocation API can also provide time zone information for an IP address on paid API plans (STANDARD and ADVANCED). However, this data is not included in the response by default. To get the time zone information along with the geolocation information, you must need to pass the include=time_zone as a query parameter in the URL.
Here is an example of an IP Geolocation lookup that includes time zone data, along with the country information associated with the IP address:
curl -X GET 'https://api.ipgeolocation.io/v2/ipgeo?apiKey=API_KEY&ip=8.8.8.8&fields=location.country_name,location.country_capital&include=time_zone'1{
2 "ip": "8.8.8.8",
3 "location": {
4 "country_capital": "Washington, D.C.",
5 "country_name": "United States"
6 },
7 "time_zone": {
8 "name": "America/Los_Angeles",
9 "offset": -8,
10 "offset_with_dst": -7,
11 "current_time": "2025-04-24 08:01:25.083-0700",
12 "current_time_unix": 1745506885.083,
13 "is_dst": true,
14 "dst_savings": 1,
15 "dst_exists": true,
16 "dst_start": {
17 "utc_time": "2025-03-09 TIME 10",
18 "duration": "+1H",
19 "gap": true,
20 "date_time_after": "2025-03-09 TIME 03",
21 "date_time_before": "2025-03-09 TIME 02",
22 "overlap": false
23 },
24 "dst_end": {
25 "utc_time": "2025-11-02 TIME 09",
26 "duration": "-1H",
27 "gap": false,
28 "date_time_after": "2025-11-02 TIME 01",
29 "date_time_before": "2025-11-02 TIME 02",
30 "overlap": true
31 }
32 }
33}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=user_agent 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 -X GET 'https://api.ipgeolocation.io/v2/ipgeo?apiKey=API_KEY&ip=8.8.8.8&fields=location&include=user_agent'1{
2 "ip": "8.8.8.8",
3 "location": {
4 "city": "Mountain View",
5 "country_code2": "US"
6 },
7 "user_agent": {
8 "user_agent_string": "PostmanRuntime/7.43.3",
9 "name": "PostmanRuntime",
10 "type": "Robot",
11 "version": "7.43.3",
12 "version_major": "7",
13 "device": {
14 "name": "Postman Runtime",
15 "type": "Robot",
16 "brand": "Postman",
17 "cpu": "Unknown"
18 },
19 "engine": {
20 "name": "PostmanRuntime",
21 "type": "Robot",
22 "version": "7.43.3",
23 "version_major": "7"
24 },
25 "operating_system": {
26 "name": "Cloud",
27 "type": "Cloud",
28 "version": "??",
29 "version_major": "??",
30 "build": "??"
31 }
32 }
33}To get hostname, DMA code, IP-Security information, Abuse contact Information, Time Zone Information and user-agent information together for an IP address and the device, you can pass include=hostname, dma, security, abuse, time_zone,user_agent as a query parameter in the URL.
What's New in /v2/ipgeo and /v2/ipgeo-bulk
Below are the key updates introduced in the /v2/ipgeo and /v2/ipgeo-bulk API endpoints compared to the previous /ipgeo and /ipgeo-bulk version:
- New fields have been introduced:
location.localityandlocation.accuracy_radiusprovide finer-grained location context.location.dma_codehas been added to support U.S. media market targeting (Designated Market Area).- The following fields under
network.asnoffer deeper insights into IP ownership and origin:asn_name,Âcountry,Âtype,Âdomain,date_allocated,allocation_status,num_of_ipv4_routes,Ânum_of_ipv6_routes, andÂrir. - Additional network company details are now available viaÂ
network.company.type andÂnetwork.company.domain of the concernedÂnetwork.company.name. security.proxy_providerandsecurity.cloud_provideroffer more transparency into potential security layers.- A new
abuseobject includes detailed abuse contact information for the IP, including:route,Âcountry,Âhandle,Âname,Âorganization,Ârole,kind,Âaddress, a list ofemails, andphone_numbers.
- Response structure has been improved for clarity and consistency:
- Location-related fields are now grouped under the
locationobject. - Country-level metadata such as
calling_code,tld, andlanguagesare now available under a dedicatedcountry_metadataobject. languagesis now returned as a list of strings instead of a single comma-separated string.- Network-related fields have been consolidated under the
networkobject:isp→network.company.nameorganization→network.asn.organizationasn→network.asn.as_numberconnection_type→network.connection_type
- Location-related fields are now grouped under the
- Field naming has been standardized for clarity or from camelCase to snake_case:
user_agent.userAgentString→user_agent.user_agent_stringuser_agent.versionMajor→user_agent.version_majoruser_agent.engine.versionMajor→user_agent.engine.version_majoruser_agent.operatingSystem.versionMajor→user_agent.operating_system.version_majortime_zone.dst_start.dateTimeAfter→time_zone.dst_start.date_time_aftertime_zone.dst_start.dateTimeBefore→time_zone.dst_start.date_time_beforetime_zone.dst_end.dateTimeAfter→time_zone.dst_end.date_time_aftertime_zone.dst_end.dateTimeBefore→time_zone.dst_end.date_time_beforecountry_tld→country_metadata.tld
- Deprecated fields:
- Fields that no longer return meaningful values —
user_agent.buildanduser_agent.engine.build— have been removed.
- Fields that no longer return meaningful values —
Reference to IPGeolocation API Response
Below, we provide separate tables for each JSON object in the response, listing all possible fields available across all plans. The fifth column indicates the minimum plan required to access each field.
Please note that field availability is cumulative: all fields available in the Free plan are also included in Standard and Advanced , and all Standard fields are also available in the Advanced plan.
• Standalone fields reference
| Field | Type | Description | Can be empty? | Availability |
|---|---|---|---|---|
| ip | string | IP address that is used to lookup geolocation information. | No | FREE |
| domain | string | Domain name that is used to lookup geolocation information. It is not returned if an IP address is used to query IP Geolocation API. | Yes | STANDARD |
| hostname | string | Hostname of the IP address used to query IP Geolocation API. | No | STANDARD |
• location json object reference
| Field | Type | Description | Can be empty? | Availability |
|---|---|---|---|---|
| continent_code | string | 2-letter code of the continent. | No | FREE |
| continent_name | string | Name of the continent. | No | FREE |
| country_code2 | string | Country code (ISO 3166-1 alpha-2) of the country. | No | FREE |
| country_code3 | string | Country code (ISO 3166-1 alpha-3) of the country. | No | FREE |
| country_name | string | Name of the country. | No | FREE |
| country_name_official | string | Official name (ISO 3166) of the country. | No | FREE |
| country_capital | string | Name of the country’s capital. | No | FREE |
| state_prov | string | Name of the state/province/region. | Yes | FREE |
| state_code | string | Code of the state/province/region. | Yes | FREE |
| district | string | Name of the district or county. | Yes | FREE |
| city | string | Name of the city. | Yes | FREE |
| locality | string | A more specific area in city or it can be same as city. | Yes | ADVANCED |
| accuracy_radius | string | Circular radius in Km, where the IP address location can be found. | Yes | ADVANCED |
| dma_code | string | Representing Designated Market Area (DMA) code specifically used in the United States for media marketing. | Yes | ADVANCED |
| zipcode | string | ZIP/Postal code of the place. | Yes | FREE |
| latitude | string | Latitude of the place. | No | FREE |
| longitude | string | Longitude of the place. | No | FREE |
| is_eu | boolean | Is the country belong to European Union? | No | FREE |
| country_flag | string | URL to get the country flag. | No | FREE |
| geoname_id | string | Geoname ID of the place from geonames.org | Yes | FREE |
| country_emoji | string | Emoji of the Country flag. | Yes | FREE |
• country_metadata json object reference
| Field | Type | Description | Can be empty? | Availability |
|---|---|---|---|---|
| calling_code | string | Calling code/Dialing code of the country. | No | FREE |
| tld | string | Top Level Domain Name (TLD) of the country, which is also called ccTLD. | No | FREE |
| languages | list of strings | List of the languages’ codes, spoken in the country. | No | FREE |
• currency json object reference
| Field | Type | Description | Can be empty? | Availability |
|---|---|---|---|---|
| code | string | Currency code (ISO 4217). | No | FREE |
| name | string | Currency name (ISO 4217). | No | FREE |
| symbol | string | Currency symbol. | No | FREE |
• network json object reference
| Field | Type | Description | Can be empty? | Availability |
|---|---|---|---|---|
| asn.as_number | string | Autonomous system number of the autonomous system, to which IP address belongs to. | Yes | STANDARD |
| asn.organization | string | Legal Full Name of AS organization holding the IP address. | Yes | STANDARD |
| asn.country | string | Name of the country, ASN is residing. | Yes | STANDARD |
| asn.asn_name | string | Name associated with the Autonomous System, usually representing organization. | Yes | ADVANCED |
| asn.type | string | Type of the ASN, whether ISP, Business, etc. | Yes | ADVANCED |
| asn.domain | string | Domain name associated with the ASN holding the IP address. | Yes | ADVANCED |
| asn.date_allocated | string | Last date, when the IP address assigned to the ASN. e.g., in format | Yes | ADVANCED |
| asn.allocation_status | string | Whether the IP address is currently assigned to the ASN or not. | Yes | ADVANCED |
| asn.num_of_ipv4_routes | string | Total number of IPv4 routes, held by the ASN. These Routes can be queried from our ASN API. | Yes | ADVANCED |
| asn.num_of_ipv6_routes | string | Total number of IPv6 routes, held by the ASN. These Routes can be queried from our ASN API. | Yes | ADVANCED |
| asn.rir | string | Name of the Regional Internet Registry (RIR) that allocated the AS number. | Yes | ADVANCED |
| company.name | string | Name of the company/ISP holding the IP address. | No | STANDARD |
| company.type | string | Type of the company whether it is an ISP, hosting provider or business, etc. | Yes | ADVANCED |
| company.domain | string | Official domain name used by the company. | Yes | ADVANCED |
| connection_type | string | Type of the connection, consuming the IP address. | Yes | ADVANCED |
• time_zone json object reference
| Field | Type | Description | Can be empty? | Availability |
|---|---|---|---|---|
| name | string | Name (ISO 8601) of the time zone. | No | STANDARD |
| offset | number | Time zone offset from UTC. | No | STANDARD |
| offset_with_dst | number | Time zone with DST offset from UTC. | No | STANDARD |
| current_time | string | Current time in | No | STANDARD |
| current_time_unix | float | Current time in seconds since 1970. | No | STANDARD |
| is_dst | boolean | Is the time zone in daylight savings? | No | STANDARD |
| dst_savings | number | Total daylight savings. | No | STANDARD |
| dst_exists | boolean | Indicates whether Daylight Saving Time (DST) is observed in the region. If | No | STANDARD |
| dst_start.utc_time | string | The date and time in UTC when DST begins. | No | STANDARD |
| dst_start.duration | string | The time change that occurs when DST starts. | No | STANDARD |
| dst_start.gap | boolean | Is there a gap when the clocks jump forward or not. | No | STANDARD |
| dst_start.date_time_after | string | The local date and time that immediately follows the start of DST. | No | STANDARD |
| dst_start.date_time_before | string | The local date and time immediately before DST begins. | No | STANDARD |
| dst_start.overlap | boolean | Whether there is an overlap of time due to clocks being set back when DST starts. | No | STANDARD |
| dst_end.utc_time | string | The date and time in UTC when DST ends. | No | STANDARD |
| dst_end.duration | string | The time change that occurs when DST ends. | No | STANDARD |
| dst_end.gap | boolean | Is there a gap when the clocks jump backward or not. | No | STANDARD |
| dst_end.date_time_after | string | The local date and time that immediately follows the ends of DST. | No | STANDARD |
| dst_end.date_time_before | string | The local date and time immediately before DST ends. | No | STANDARD |
| dst_end.overlap | boolean | Whether there is an overlap of time due to clocks being set back when DST ends. | No | STANDARD |
• user_agent json object reference
| Field | Type | Description | Can be empty? | Availability |
|---|---|---|---|---|
| user_agent_string | string | User-Agent string passed along with the query in the | No | STANDARD |
| name | string | User-Agent Name. | No | STANDARD |
| type | string | User-Agent Class. | No | STANDARD |
| version | string | User-Agent Version. | No | STANDARD |
| version_major | string | User-Agent Version Major. | No | STANDARD |
| device.name | string | Device Name. | No | STANDARD |
| device.type | string | Device Type. | No | STANDARD |
| device.brand | string | Device Brand. | No | STANDARD |
| device.cpu | string | Device CPU Model. | No | STANDARD |
| engine.name | string | Layout Engine Name. | No | STANDARD |
| engine.type | string | Layout Engine Class. | No | STANDARD |
| engine.version | string | Layout Engine Version. | No | STANDARD |
| engine.version_major | string | Layout Engine Version Major. | No | STANDARD |
| operating_system.name | string | Operating System Name. | No | STANDARD |
| operating_system.type | string | Operating System Class. | No | STANDARD |
| operating_system.version | string | Operating System Version. | No | STANDARD |
| operating_system.version_major | string | Operating System Version Major. | No | STANDARD |
| operating_system.build | string | Operating System Build. | No | STANDARD |
For all possible values of the User Agent type fields, please check here
• security json object reference
| Field | Type | Description | Can be empty? | Availability |
|---|---|---|---|---|
| threat_score | number | IP address’ threat score. It ranges from 0 to 100. 100 indicates highest threat and vice versa for lower score. | No | ADVANCED |
| is_tor | boolean | Indicates if the IP address is being consumed on a Tor endpoint. | No | ADVANCED |
| is_proxy | boolean | Indicates if the IP address belongs to a proxy network. | No | ADVANCED |
| proxy_type | string | Type of the proxy network if the IP address belongs to a proxy network. | Yes | ADVANCED |
| proxy_provider | string | Name of the proxy provider, if the IP address belongs to a proxy network. | Yes | ADVANCED |
| is_anonymous | boolean | Indicates if the IP address is being used anonymously. | No | ADVANCED |
| is_known_attacker | boolean | Indicates if the IP address is enlisted as an attacking IP address. | No | ADVANCED |
| is_spam | boolean | Indicates if the IP address is enlisted as a spam IP address. | No | ADVANCED |
| is_bot | boolean | Indicates if the IP address is enlisted as a bot IP address. | No | ADVANCED |
| is_cloud_provider | boolean | Indicates if the IP address belongs to a cloud provider (computing infrastructure providers). | No | ADVANCED |
| cloud_provider | string | Name of the Cloud Provider, if the IP address belongs to a cloud provider. | Yes | ADVANCED |
• abuse json object reference
| Field | Type | Description | Can be empty? | Availability |
|---|---|---|---|---|
| route | string | Network route associated with the IP address. | Yes | ADVANCED |
| country | string | Country where the responsible entity is located. | Yes | ADVANCED |
| handle | string | Abuse handle or ID found in WHOIS or RDAP records. | Yes | ADVANCED |
| name | string | Name of the abuse contact person or entity. | Yes | ADVANCED |
| organization | string | Organization responsible for the IP address. | Yes | ADVANCED |
| role | string | Role of the contact (e.g., | Yes | ADVANCED |
| kind | string | Type of contact: individual, team, or organization. | Yes | ADVANCED |
| address | string | Physical mailing address of the responsible entity. | Yes | ADVANCED |
| emails | list of strings | Email address(es) of the abuse contact. | Yes | ADVANCED |
| phone_numbers | list of strings | Phone number(s) in international format for the abuse contact. | Yes | ADVANCED |
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:
|
| 401 Unauthorized | It is returned for one of the following reasons:
|
| 403 Forbidden |
|
| 404 Not Found | It is returned for one of the following reasons:
|
| 405 Method Not Allowed |
|
| 413 Content Too Large |
|
| 415 Unsupported Media Type |
|
| 423 Locked |
|
| 429 Too Many Requests | It is returned for one of the following reasons:
|
| 499 Client Closed Request |
|
| 5XX Server Side Error |
|
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: