IP Geolocation API

Overview

IP Geolocation API provides real-time and accurate geolocation, asn, company, network, time zone, 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 -X GET 'https://api.ipgeolocation.io/v3/ipgeo?apiKey=API_KEY&ip=91.128.103.196'

Response

1{
2  "ip": "91.128.103.196",
3  "location": {
4    "continent_code": "EU",
5    "continent_name": "Europe",
6    "country_code2": "SE",
7    "country_code3": "SWE",
8    "country_name": "Sweden",
9    "country_name_official": "Kingdom of Sweden",
10    "country_capital": "Stockholm",
11    "state_prov": "Stockholms län",
12    "state_code": "SE-AB",
13    "district": "Stockholm",
14    "city": "Stockholm",
15    "zipcode": "164 40",
16    "latitude": "59.40510",
17    "longitude": "17.95510",
18    "is_eu": true,
19    "country_flag": "https://ipgeolocation.io/static/flags/se_64.png",
20    "geoname_id": "9972319",
21    "country_emoji": "🇸🇪"
22  },
23  "country_metadata": {
24    "calling_code": "+46",
25    "tld": ".se",
26    "languages": [
27      "sv-SE",
28      "se",
29      "sma",
30      "fi-SE"
31    ]
32  },
33  "currency": {
34    "code": "SEK",
35    "name": "Swedish Krona",
36    "symbol": "kr"
37  },
38  "asn": {
39    "as_number": "AS1257",
40    "organization": "Tele2 Sverige AB",
41    "country": "SE"
42  },
43  "time_zone": {
44    "name": "Europe/Stockholm",
45    "offset": 1,
46    "offset_with_dst": 1,
47    "current_time": "2026-02-12 18:36:54.401+0100",
48    "current_time_unix": 1770917814.401,
49    "current_tz_abbreviation": "CET",
50    "current_tz_full_name": "Central European Standard Time",
51    "standard_tz_abbreviation": "CET",
52    "standard_tz_full_name": "Central European Standard Time",
53    "is_dst": false,
54    "dst_savings": 0,
55    "dst_exists": true,
56    "dst_tz_abbreviation": "CEST",
57    "dst_tz_full_name": "Central European Summer Time",
58    "dst_start": {
59      "utc_time": "2026-03-29 TIME 01:00",
60      "duration": "+1.00H",
61      "gap": true,
62      "date_time_after": "2026-03-29 TIME 03:00",
63      "date_time_before": "2026-03-29 TIME 02:00",
64      "overlap": false
65    },
66    "dst_end": {
67      "utc_time": "2026-10-25 TIME 01:00",
68      "duration": "-1.00H",
69      "gap": false,
70      "date_time_after": "2026-10-25 TIME 02:00",
71      "date_time_before": "2026-10-25 TIME 03:00",
72      "overlap": true
73    }
74  }
75}

II. IPv6 Example

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

Note

The response remains the same as queried with an 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 -X GET 'https://api.ipgeolocation.io/v3/ipgeo?apiKey=API_KEY'

Note

The response remains the same as when you provide an ip in the request. The difference is that ip will be the requesting client’s public IP.

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 -X GET 'https://api.ipgeolocation.io/v3/ipgeo?apiKey=API_KEY&ip=91.128.103.196'

Response

1{
2  "ip": "91.128.103.196",
3  "location": {
4    "continent_code": "EU",
5    "continent_name": "Europe",
6    "country_code2": "SE",
7    "country_code3": "SWE",
8    "country_name": "Sweden",
9    "country_name_official": "Kingdom of Sweden",
10    "country_capital": "Stockholm",
11    "state_prov": "Stockholms län",
12    "state_code": "SE-AB",
13    "district": "Stockholm",
14    "city": "Stockholm",
15    "zipcode": "164 40",
16    "latitude": "59.40510",
17    "longitude": "17.95510",
18    "is_eu": true,
19    "country_flag": "https://ipgeolocation.io/static/flags/se_64.png",
20    "geoname_id": "9972319",
21    "country_emoji": "🇸🇪"
22  },
23  "country_metadata": {
24    "calling_code": "+46",
25    "tld": ".se",
26    "languages": [
27      "sv-SE",
28      "se",
29      "sma",
30      "fi-SE"
31    ]
32  },
33  "network": {
34    "connection_type": "",
35    "route": "91.128.0.0/14",
36    "is_anycast": false
37  },
38  "currency": {
39    "code": "SEK",
40    "name": "Swedish Krona",
41    "symbol": "kr"
42  },
43  "asn": {
44    "as_number": "AS1257",
45    "organization": "Tele2 Sverige AB",
46    "country": "SE",
47    "type": "ISP",
48    "domain": "tele2.com",
49    "date_allocated": "2024-12-13",
50    "rir": "RIPE"
51  },
52  "company": {
53    "name": "Tele2 Sverige AB",
54    "type": "ISP",
55    "domain": "tele2.com"
56  },
57  "time_zone": {
58    "name": "Europe/Stockholm",
59    "offset": 1,
60    "offset_with_dst": 1,
61    "current_time": "2026-02-12 18:40:32.083+0100",
62    "current_time_unix": 1770918032.083,
63    "current_tz_abbreviation": "CET",
64    "current_tz_full_name": "Central European Standard Time",
65    "standard_tz_abbreviation": "CET",
66    "standard_tz_full_name": "Central European Standard Time",
67    "is_dst": false,
68    "dst_savings": 0,
69    "dst_exists": true,
70    "dst_tz_abbreviation": "CEST",
71    "dst_tz_full_name": "Central European Summer Time",
72    "dst_start": {
73      "utc_time": "2026-03-29 TIME 01:00",
74      "duration": "+1.00H",
75      "gap": true,
76      "date_time_after": "2026-03-29 TIME 03:00",
77      "date_time_before": "2026-03-29 TIME 02:00",
78      "overlap": false
79    },
80    "dst_end": {
81      "utc_time": "2026-10-25 TIME 01:00",
82      "duration": "-1.00H",
83      "gap": false,
84      "date_time_after": "2026-10-25 TIME 02:00",
85      "date_time_before": "2026-10-25 TIME 03:00",
86      "overlap": true
87    }
88  }
89}

II. IPv6 Example

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

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 -X GET 'https://api.ipgeolocation.io/v3/ipgeo?apiKey=API_KEY'

Note

The response remains the same as when you provide an ip in the request. The difference is that ip will be the requesting client’s public IP.

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

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.

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 '91.128.103.196' in Chinese language.

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

Note

Only paid plan subscriptions can receive responses in languages other than English. Free/Developer plan subscriptions return responses in English only. If a language other than English is specified in the lang parameter while using a Free/Developer plan API key, the request will result in a 401 (Unauthorized) response.

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 -X GET 'https://api.ipgeolocation.io/v3/ipgeo?apiKey=API_KEY&ip=91.128.103.196&include=geo_accuracy'

Response

1{
2  "ip": "91.128.103.196",
3  "location": {
4    "continent_code": "EU",
5    "continent_name": "Europe",
6    "country_code2": "SE",
7    "country_code3": "SWE",
8    "country_name": "Sweden",
9    "country_name_official": "Kingdom of Sweden",
10    "country_capital": "Stockholm",
11    "state_prov": "Stockholms län",
12    "state_code": "SE-AB",
13    "district": "Stockholm",
14    "city": "Stockholm",
15    "locality": "Stockholm",
16    "accuracy_radius": "4.395",
17    "confidence": "high",
18    "zipcode": "164 40",
19    "latitude": "59.40510",
20    "longitude": "17.95510",
21    "is_eu": true,
22    "country_flag": "https://ipgeolocation.io/static/flags/se_64.png",
23    "geoname_id": "9972319",
24    "country_emoji": "🇸🇪"
25  },
26  "country_metadata": {
27    "...": "...",
28  },
29  "network": {
30    "...": "..."
31  },
32  "currency": {
33    "...": "..."
34  },
35  "asn": {
36    "...": "..."
37  },
38  "company": {
39    "...": "..."
40  },
41  "time_zone": {
42    "...": "..."
43  }
44}

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

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 -X GET 'https://api.ipgeolocation.io/v3/ipgeo?apiKey=API_KEY&ip=91.128.103.196&include=user_agent'

Response

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

B. With a User-Agent header

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

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

Response

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

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 :

Checks the local IP-to-hostname database first. If not found then performs a live hostname lookup.

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

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

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 through 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 through 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 through 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 include 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 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 -X GET 'https://api.ipgeolocation.io/v3/ipgeo?apiKey=API_KEY&ip=2.56.188.34&include=security'

Response

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

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 -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 include 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 -X GET 'https://api.ipgeolocation.io/v3/ipgeo?apiKey=API_KEY&ip=91.128.103.196&include=abuse'

Response

1{
2  "ip": "91.128.103.196",
3  "location": {
4   "...": "..."
5  },
6  "abuse": {
7    "route": "91.128.0.0/14",
8    "country": "SE",
9    "name": "Swipnet Staff",
10    "organization": "",
11    "kind": "group",
12    "address": "Tele2 AB/Swedish IP Network IP Registry Torshamnsgatan 17 164 40 Kista SWEDEN",
13    "emails": [
14      "abuse@tele2.com"
15    ],
16    "phone_numbers": [
17      "+46 8 5626 42 10"
18    ]
19  },
20  "country_metadata": {
21    "...": "..."
22  },
23  "network": {
24    "...": "..."
25  },
26  "currency": {
27    "...": "..."
28  },
29  "asn": {
30    "...": "..."
31  },
32  "company": {
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 credit in total (not 1 + 1).

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

Response

1{
2  "ip": "91.128.103.196",
3  "abuse": {
4    "route": "91.128.0.0/14",
5    "country": "SE",
6    "name": "Swipnet Staff",
7    "organization": "",
8    "kind": "group",
9    "address": "Tele2 AB/Swedish IP Network IP Registry Torshamnsgatan 17 164 40 Kista SWEDEN",
10    "emails": [
11      "abuse@tele2.com"
12    ],
13    "phone_numbers": [
14      "+46 8 5626 42 10"
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 -X GET 'https://api.ipgeolocation.io/v3/ipgeo?apiKey=API_KEY&ip=91.128.103.196&include=security,abuse,user_agent,dma_code,geo_accuracy,hostname'

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

Response

1{
2  "ip": "91.128.103.196",
3  "hostname": "91.128.103.196",
4  "location": {
5    "continent_code": "EU",
6    "continent_name": "Europe",
7    "country_code2": "SE",
8    "country_code3": "SWE",
9    "country_name": "Sweden",
10    "country_name_official": "Kingdom of Sweden",
11    "country_capital": "Stockholm",
12    "state_prov": "Stockholms län",
13    "state_code": "SE-AB",
14    "district": "Stockholm",
15    "city": "Stockholm",
16    "locality": "Stockholm",
17    "accuracy_radius": "4.395",
18    "confidence": "high",
19    "dma_code": "",
20    "zipcode": "164 40",
21    "latitude": "59.40510",
22    "longitude": "17.95510",
23    "is_eu": true,
24    "country_flag": "https://ipgeolocation.io/static/flags/se_64.png",
25    "geoname_id": "9972319",
26    "country_emoji": "🇸🇪"
27  },
28  "country_metadata": {
29    "calling_code": "+46",
30    "tld": ".se",
31    "languages": [
32      "sv-SE",
33      "se",
34      "sma",
35      "fi-SE"
36    ]
37  },
38  "network": {
39    "connection_type": "",
40    "route": "91.128.0.0/14",
41    "is_anycast": false
42  },
43  "currency": {
44    "code": "SEK",
45    "name": "Swedish Krona",
46    "symbol": "kr"
47  },
48  "asn": {
49    "as_number": "AS1257",
50    "organization": "Tele2 Sverige AB",
51    "country": "SE",
52    "type": "ISP",
53    "domain": "tele2.com",
54    "date_allocated": "2024-12-13",
55    "rir": "RIPE"
56  },
57  "company": {
58    "name": "Tele2 Sverige AB",
59    "type": "ISP",
60    "domain": "tele2.com"
61  },
62  "security": {
63    "threat_score": 0,
64    "is_tor": false,
65    "is_proxy": false,
66    "proxy_provider_names": [],
67    "proxy_confidence_score": 0,
68    "proxy_last_seen": "",
69    "is_residential_proxy": false,
70    "is_vpn": false,
71    "vpn_provider_names": [],
72    "vpn_confidence_score": 0,
73    "vpn_last_seen": "",
74    "is_relay": false,
75    "relay_provider_name": "",
76    "is_anonymous": false,
77    "is_known_attacker": false,
78    "is_bot": false,
79    "is_spam": false,
80    "is_cloud_provider": false,
81    "cloud_provider_name": ""
82  },
83  "abuse": {
84    "route": "91.128.0.0/14",
85    "country": "SE",
86    "name": "Swipnet Staff",
87    "organization": "",
88    "kind": "group",
89    "address": "Tele2 AB/Swedish IP Network, IP Registry, Torshamnsgatan 17 164 40 Kista SWEDEN",
90    "emails": [
91      "abuse@tele2.com"
92    ],
93    "phone_numbers": [
94      "+46 8 5626 42 10"
95    ]
96  },
97  "time_zone": {
98    "name": "Europe/Stockholm",
99    "offset": 1,
100    "offset_with_dst": 1,
101    "current_time": "2026-02-13 09:19:24.410+0100",
102    "current_time_unix": 1770970764.41,
103    "current_tz_abbreviation": "CET",
104    "current_tz_full_name": "Central European Standard Time",
105    "standard_tz_abbreviation": "CET",
106    "standard_tz_full_name": "Central European Standard Time",
107    "is_dst": false,
108    "dst_savings": 0,
109    "dst_exists": true,
110    "dst_tz_abbreviation": "CEST",
111    "dst_tz_full_name": "Central European Summer Time",
112    "dst_start": {
113      "utc_time": "2026-03-29 TIME 01:00",
114      "duration": "+1.00H",
115      "gap": true,
116      "date_time_after": "2026-03-29 TIME 03:00",
117      "date_time_before": "2026-03-29 TIME 02:00",
118      "overlap": false
119    },
120    "dst_end": {
121      "utc_time": "2026-10-25 TIME 01:00",
122      "duration": "-1.00H",
123      "gap": false,
124      "date_time_after": "2026-10-25 TIME 02:00",
125      "date_time_before": "2026-10-25 TIME 03:00",
126      "overlap": true
127    }
128  },
129  "user_agent": {
130    "user_agent_string": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/143.0.0.0 Safari/537.36 Edg/143.0.0.0",
131    "name": "Edge",
132    "type": "Browser",
133    "version": "143",
134    "version_major": "143",
135    "device": {
136      "name": "Linux Desktop",
137      "type": "Desktop",
138      "brand": "Unknown",
139      "cpu": "Intel x86_64"
140    },
141    "engine": {
142      "name": "Blink",
143      "type": "Browser",
144      "version": "143",
145      "version_major": "143"
146    },
147    "operating_system": {
148      "name": "Linux",
149      "type": "Desktop",
150      "version": "??",
151      "version_major": "??",
152      "build": "??"
153    }
154  }
155}

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.

On Free/Developer plan, using include=* returns the same default response as a request without include=* . No additional modules are included.

Important

Credits: This request costs 4 API credits total: 1 for the base lookup and free additional data (everything except security and abuse), 2 for 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 of the request. Here are a few examples to get only the required fields:

I. Get Location Information Only

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

Response

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

II. Get country name and ASN organization only

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

Response

1{
2  "ip": "91.128.103.196",
3  "location": {
4    "country_name": "Sweden"
5  },
6  "asn": {
7    "organization": "Tele2 Sverige AB"
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 -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": "2.56.188.34",
3  "location": {
4    "city": "Dallas"
5  },
6  "security": {
7    "threat_score": 80,
8    "is_vpn": true
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 parameter separated by a comma, the full object will be returned.
e.g., fields=security,security.threat_score
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 -X GET 'https://api.ipgeolocation.io/v3/ipgeo?apiKey=API_KEY&ip=91.128.103.196&excludes=location.continent_code,currency,company.type'

Response

1{
2  "ip": "91.128.103.196",
3  "location": {
4    "continent_name": "Europe",
5    "country_code2": "SE",
6    "country_code3": "SWE",
7    "country_name": "Sweden",
8    "country_name_official": "Kingdom of Sweden",
9    "country_capital": "Stockholm",
10    "state_prov": "Stockholms län",
11    "state_code": "SE-AB",
12    "district": "Stockholm",
13    "city": "Stockholm",
14    "zipcode": "164 40",
15    "latitude": "59.40510",
16    "longitude": "17.95510",
17    "is_eu": true,
18    "country_flag": "https://ipgeolocation.io/static/flags/se_64.png",
19    "geoname_id": "9972319",
20    "country_emoji": "🇸🇪"
21  },
22  "country_metadata": {
23    "calling_code": "+46",
24    "tld": ".se",
25    "languages": [
26      "sv-SE",
27      "se",
28      "sma",
29      "fi-SE"
30    ]
31  },
32  "network": {
33    "connection_type": "",
34    "route": "91.128.0.0/14",
35    "is_anycast": false
36  },
37  "asn": {
38    "as_number": "AS1257",
39    "organization": "Tele2 Sverige AB",
40    "country": "SE",
41    "type": "ISP",
42    "domain": "tele2.com",
43    "date_allocated": "2024-12-13",
44    "rir": "RIPE"
45  },
46  "company": {
47    "name": "Tele2 Sverige AB",
48    "domain": "tele2.com"
49  },
50  "time_zone": {
51    "name": "Europe/Stockholm",
52    "offset": 1,
53    "offset_with_dst": 1,
54    "current_time": "2026-02-13 10:16:01.920+0100",
55    "current_time_unix": 1770974161.92,
56    "current_tz_abbreviation": "CET",
57    "current_tz_full_name": "Central European Standard Time",
58    "standard_tz_abbreviation": "CET",
59    "standard_tz_full_name": "Central European Standard Time",
60    "is_dst": false,
61    "dst_savings": 0,
62    "dst_exists": true,
63    "dst_tz_abbreviation": "CEST",
64    "dst_tz_full_name": "Central European Summer Time",
65    "dst_start": {
66      "utc_time": "2026-03-29 TIME 01:00",
67      "duration": "+1.00H",
68      "gap": true,
69      "date_time_after": "2026-03-29 TIME 03:00",
70      "date_time_before": "2026-03-29 TIME 02:00",
71      "overlap": false
72    },
73    "dst_end": {
74      "utc_time": "2026-10-25 TIME 01:00",
75      "duration": "-1.00H",
76      "gap": false,
77      "date_time_after": "2026-10-25 TIME 02:00",
78      "date_time_before": "2026-10-25 TIME 03:00",
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 -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": "91.128.103.196",
3  "location": {
4    "country_code2": "SE",
5    "country_code3": "SWE",
6    "country_name": "Sweden",
7    "country_name_official": "Kingdom of Sweden",
8    "country_capital": "Stockholm",
9    "state_prov": "Stockholms län",
10    "state_code": "SE-AB",
11    "district": "Stockholm",
12    "city": "Stockholm",
13    "zipcode": "164 40",
14    "latitude": "59.40510",
15    "longitude": "17.95510",
16    "is_eu": true,
17    "country_flag": "https://ipgeolocation.io/static/flags/se_64.png",
18    "geoname_id": "9972319",
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.

Bulk lookup supports the same query parameters as the single lookup ( include , excludes , fields , lang , and output ).

Important

For bulk lookups, the requests count and quota billing are calculated per valid IP address or domain name submitted, using the same credit rules as single lookups (base 1 credit, +2 for Security, +1 for Abuse); bogon, private, and malformed IPs are not counted, and the exact charge is returned in the X-Credits-Charged response header.
The X-Successful-Record response header is also returned which shows how many IP addresses in the request returned valid data with an HTTP 200 status; invalid entries are excluded from this count.

1. Bulk lookup request

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

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

Response

1[
2    {
3      "ip": "91.128.103.196",
4      "location": {
5          "continent_code": "EU",
6          "continent_name": "Europe",
7          "country_code2": "SE",
8          "country_code3": "SWE",
9          "country_name": "Sweden",
10          "country_name_official": "Kingdom of Sweden",
11          "country_capital": "Stockholm",
12          "state_prov": "Stockholms län",
13          "state_code": "SE-AB",
14          "district": "Stockholm",
15          "city": "Stockholm",
16          "zipcode": "164 40",
17          "latitude": "59.40510",
18          "longitude": "17.95510",
19          "is_eu": true,
20          "country_flag": "https://ipgeolocation.io/static/flags/se_64.png",
21          "geoname_id": "9972319",
22          "country_emoji": "🇸🇪"
23      },
24      "country_metadata": {
25          "calling_code": "+46",
26          "tld": ".se",
27          "languages": [
28              "sv-SE",
29              "se",
30              "sma",
31              "fi-SE"
32          ]
33      },
34      "network": {
35          "connection_type": "",
36          "route": "91.128.0.0/14",
37          "is_anycast": false
38      },
39      "currency": {
40          "code": "SEK",
41          "name": "Swedish Krona",
42          "symbol": "kr"
43      },
44      "asn": {
45          "as_number": "AS1257",
46          "organization": "Tele2 Sverige AB",
47          "country": "SE",
48          "type": "ISP",
49          "domain": "tele2.com",
50          "date_allocated": "2024-12-13",
51          "rir": "RIPE"
52      },
53      "company": {
54          "name": "Tele2 Sverige AB",
55          "type": "ISP",
56          "domain": "tele2.com"
57      },
58      "time_zone": {
59        "name": "Europe/Stockholm",
60        "offset": 1,
61        "offset_with_dst": 1,
62        "current_time": "2026-02-13 10:44:22.701+0100",
63        "current_time_unix": 1770975862.701,
64        "current_tz_abbreviation": "CET",
65        "current_tz_full_name": "Central European Standard Time",
66        "standard_tz_abbreviation": "CET",
67        "standard_tz_full_name": "Central European Standard Time",
68        "is_dst": false,
69        "dst_savings": 0,
70        "dst_exists": true,
71        "dst_tz_abbreviation": "CEST",
72        "dst_tz_full_name": "Central European Summer Time",
73        "dst_start": {
74            "utc_time": "2026-03-29 TIME 01:00",
75            "duration": "+1.00H",
76            "gap": true,
77            "date_time_after": "2026-03-29 TIME 03:00",
78            "date_time_before": "2026-03-29 TIME 02:00",
79            "overlap": false
80        },
81        "dst_end": {
82            "utc_time": "2026-10-25 TIME 01:00",
83            "duration": "-1.00H",
84            "gap": false,
85            "date_time_after": "2026-10-25 TIME 02:00",
86            "date_time_before": "2026-10-25 TIME 03:00",
87            "overlap": true
88        }
89      }
90    },
91    {
92      "ip": "91.128.103.198",
93      "location": {
94          "continent_code": "EU",
95          "continent_name": "Europe",
96          "country_code2": "SE",
97          "country_code3": "SWE",
98          "country_name": "Sweden",
99          "country_name_official": "Kingdom of Sweden",
100          "country_capital": "Stockholm",
101          "state_prov": "Stockholms län",
102          "state_code": "SE-AB",
103          "district": "Stockholm",
104          "city": "Stockholm",
105          "zipcode": "164 40",
106          "latitude": "59.40510",
107          "longitude": "17.95510",
108          "is_eu": true,
109          "country_flag": "https://ipgeolocation.io/static/flags/se_64.png",
110          "geoname_id": "9972319",
111          "country_emoji": "🇸🇪"
112      },
113      "country_metadata": {
114          "calling_code": "+46",
115          "tld": ".se",
116          "languages": [
117              "sv-SE",
118              "se",
119              "sma",
120              "fi-SE"
121          ]
122      },
123      "network": {
124          "connection_type": "",
125          "route": "91.128.0.0/14",
126          "is_anycast": false
127      },
128      "currency": {
129          "code": "SEK",
130          "name": "Swedish Krona",
131          "symbol": "kr"
132      },
133      "asn": {
134          "as_number": "AS1257",
135          "organization": "Tele2 Sverige AB",
136          "country": "SE",
137          "type": "ISP",
138          "domain": "tele2.com",
139          "date_allocated": "2024-12-13",
140          "rir": "RIPE"
141      },
142      "company": {
143          "name": "Tele2 Sverige AB",
144          "type": "ISP",
145          "domain": "tele2.com"
146      },
147      "time_zone": {
148        "name": "Europe/Stockholm",
149        "offset": 1,
150        "offset_with_dst": 1,
151        "current_time": "2026-02-13 10:44:22.701+0100",
152        "current_time_unix": 1770975862.701,
153        "current_tz_abbreviation": "CET",
154        "current_tz_full_name": "Central European Standard Time",
155        "standard_tz_abbreviation": "CET",
156        "standard_tz_full_name": "Central European Standard Time",
157        "is_dst": false,
158        "dst_savings": 0,
159        "dst_exists": true,
160        "dst_tz_abbreviation": "CEST",
161        "dst_tz_full_name": "Central European Summer Time",
162        "dst_start": {
163            "utc_time": "2026-03-29 TIME 01:00",
164            "duration": "+1.00H",
165            "gap": true,
166            "date_time_after": "2026-03-29 TIME 03:00",
167            "date_time_before": "2026-03-29 TIME 02:00",
168            "overlap": false
169        },
170        "dst_end": {
171            "utc_time": "2026-10-25 TIME 01:00",
172            "duration": "-1.00H",
173            "gap": false,
174            "date_time_after": "2026-10-25 TIME 02:00",
175            "date_time_before": "2026-10-25 TIME 03:00",
176            "overlap": true
177        }
178      }
179    },
180    {
181      "ip": "91.128.103.194",
182      "location": {
183          "continent_code": "EU",
184          "continent_name": "Europe",
185          "country_code2": "SE",
186          "country_code3": "SWE",
187          "country_name": "Sweden",
188          "country_name_official": "Kingdom of Sweden",
189          "country_capital": "Stockholm",
190          "state_prov": "Stockholms län",
191          "state_code": "SE-AB",
192          "district": "Stockholm",
193          "city": "Stockholm",
194          "zipcode": "164 40",
195          "latitude": "59.40510",
196          "longitude": "17.95510",
197          "is_eu": true,
198          "country_flag": "https://ipgeolocation.io/static/flags/se_64.png",
199          "geoname_id": "9972319",
200          "country_emoji": "🇸🇪"
201      },
202      "country_metadata": {
203          "calling_code": "+46",
204          "tld": ".se",
205          "languages": [
206              "sv-SE",
207              "se",
208              "sma",
209              "fi-SE"
210          ]
211      },
212      "network": {
213          "connection_type": "",
214          "route": "91.128.0.0/14",
215          "is_anycast": false
216      },
217      "currency": {
218          "code": "SEK",
219          "name": "Swedish Krona",
220          "symbol": "kr"
221      },
222      "asn": {
223          "as_number": "AS1257",
224          "organization": "Tele2 Sverige AB",
225          "country": "SE",
226          "type": "ISP",
227          "domain": "tele2.com",
228          "date_allocated": "2024-12-13",
229          "rir": "RIPE"
230      },
231      "company": {
232          "name": "Tele2 Sverige AB",
233          "type": "ISP",
234          "domain": "tele2.com"
235      },
236      "time_zone": {
237        "name": "Europe/Stockholm",
238        "offset": 1,
239        "offset_with_dst": 1,
240        "current_time": "2026-02-13 10:44:22.701+0100",
241        "current_time_unix": 1770975862.701,
242        "current_tz_abbreviation": "CET",
243        "current_tz_full_name": "Central European Standard Time",
244        "standard_tz_abbreviation": "CET",
245        "standard_tz_full_name": "Central European Standard Time",
246        "is_dst": false,
247        "dst_savings": 0,
248        "dst_exists": true,
249        "dst_tz_abbreviation": "CEST",
250        "dst_tz_full_name": "Central European Summer Time",
251        "dst_start": {
252            "utc_time": "2026-03-29 TIME 01:00",
253            "duration": "+1.00H",
254            "gap": true,
255            "date_time_after": "2026-03-29 TIME 03:00",
256            "date_time_before": "2026-03-29 TIME 02:00",
257            "overlap": false
258        },
259        "dst_end": {
260            "utc_time": "2026-10-25 TIME 01:00",
261            "duration": "-1.00H",
262            "gap": false,
263            "date_time_after": "2026-10-25 TIME 02:00",
264            "date_time_before": "2026-10-25 TIME 03:00",
265            "overlap": true
266        }
267      }
268    }
269]

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
Select only the required objects and fields: fields=location.city,currency,security
Exclude threat_score from security : excludes=security.threat_score

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

Response

1[
2    {
3      "ip": "2.56.188.34",
4      "location": {
5          "city": "Dallas"
6      },
7      "currency": {
8          "code": "USD",
9          "name": "US Dollar",
10          "symbol": "$"
11      },
12      "security": {
13          "is_tor": false,
14          "is_proxy": true,
15          "proxy_provider_names": [
16              "Zyte Proxy"
17          ],
18          "proxy_confidence_score": 90,
19          "proxy_last_seen": "2025-12-12",
20          "is_residential_proxy": true,
21          "is_vpn": true,
22          "vpn_provider_names": [
23              "Nord VPN"
24          ],
25          "vpn_confidence_score": 90,
26          "vpn_last_seen": "2026-01-19",
27          "is_relay": false,
28          "relay_provider_name": "",
29          "is_anonymous": true,
30          "is_known_attacker": true,
31          "is_bot": false,
32          "is_spam": false,
33          "is_cloud_provider": true,
34          "cloud_provider_name": "Packethub S.A."
35      }
36    },
37    {
38      "ip": "91.128.103.196",
39      "location": {
40          "city": "Stockholm"
41      },
42      "currency": {
43          "code": "SEK",
44          "name": "Swedish Krona",
45          "symbol": "kr"
46      },
47      "security": {
48          "is_tor": false,
49          "is_proxy": false,
50          "proxy_provider_names": [],
51          "proxy_confidence_score": 0,
52          "proxy_last_seen": "",
53          "is_residential_proxy": false,
54          "is_vpn": false,
55          "vpn_provider_names": [],
56          "vpn_confidence_score": 0,
57          "vpn_last_seen": "",
58          "is_relay": false,
59          "relay_provider_name": "",
60          "is_anonymous": false,
61          "is_known_attacker": false,
62          "is_bot": false,
63          "is_spam": false,
64          "is_cloud_provider": false,
65          "cloud_provider_name": ""
66      }
67    },
68    {
69      "ip": "107.161.145.198",
70      "location": {
71          "city": "Philadelphia"
72      },
73      "currency": {
74          "code": "USD",
75          "name": "US Dollar",
76          "symbol": "$"
77      },
78      "security": {
79          "is_tor": false,
80          "is_proxy": false,
81          "proxy_provider_names": [],
82          "proxy_confidence_score": 0,
83          "proxy_last_seen": "",
84          "is_residential_proxy": false,
85          "is_vpn": false,
86          "vpn_provider_names": [],
87          "vpn_confidence_score": 0,
88          "vpn_last_seen": "",
89          "is_relay": false,
90          "relay_provider_name": "",
91          "is_anonymous": false,
92          "is_known_attacker": true,
93          "is_bot": false,
94          "is_spam": false,
95          "is_cloud_provider": true,
96          "cloud_provider_name": "LightWave Networks"
97      }
98    }
99]

3. Bulk Lookup Response for Invalid IPs

In a bulk request, each IP address is processed independently.

If an IP address is invalid (non-public, non-routable, or malformed), the API returns an object containing only a descriptive message field for that entry along with the valid public IP address responses.

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

Response

1[
2    {
3      "message": "'10.0.0.0' is a bogon IP address."
4    },
5    {
6      "ip": "91.128.103.196",
7      "location": {
8        "continent_code": "EU",
9        "continent_name": "Europe",
10        "country_code2": "SE",
11        "country_code3": "SWE",
12        "country_name": "Sweden",
13        "country_name_official": "Kingdom of Sweden",
14        "country_capital": "Stockholm",
15        "state_prov": "Stockholms län",
16        "state_code": "SE-AB",
17        "district": "Stockholm",
18        "city": "Stockholm",
19        "zipcode": "164 40",
20        "latitude": "59.40510",
21        "longitude": "17.95510",
22        "is_eu": true,
23        "country_flag": "https://ipgeolocation.io/static/flags/se_64.png",
24        "geoname_id": "9972319",
25        "country_emoji": "🇸🇪"
26      },
27      "country_metadata": {
28        "calling_code": "+46",
29        "tld": ".se",
30        "languages": [
31          "sv-SE",
32          "se",
33          "sma",
34          "fi-SE"
35        ]
36      },
37      "network": {
38        "connection_type": "",
39        "route": "91.128.0.0/14",
40        "is_anycast": false
41      },
42      "currency": {
43        "code": "SEK",
44        "name": "Swedish Krona",
45        "symbol": "kr"
46      },
47      "asn": {
48        "as_number": "AS1257",
49        "organization": "Tele2 Sverige AB",
50        "country": "SE",
51        "type": "ISP",
52        "domain": "tele2.com",
53        "date_allocated": "2024-12-13",
54        "rir": "RIPE"
55      },
56      "company": {
57        "name": "Tele2 Sverige AB",
58        "type": "ISP",
59        "domain": "tele2.com"
60      },
61      "time_zone": {
62        "name": "Europe/Stockholm",
63        "offset": 1,
64        "offset_with_dst": 1,
65        "current_time": "2026-02-24 18:57:36.111+0100",
66        "current_time_unix": 1771955856.111,
67        "current_tz_abbreviation": "CET",
68        "current_tz_full_name": "Central European Standard Time",
69        "standard_tz_abbreviation": "CET",
70        "standard_tz_full_name": "Central European Standard Time",
71        "is_dst": false,
72        "dst_savings": 0,
73        "dst_exists": true,
74        "dst_tz_abbreviation": "CEST",
75        "dst_tz_full_name": "Central European Summer Time",
76        "dst_start": {
77          "utc_time": "2026-03-29 TIME 01:00",
78          "duration": "+1.00H",
79          "gap": true,
80          "date_time_after": "2026-03-29 TIME 03:00",
81          "date_time_before": "2026-03-29 TIME 02:00",
82          "overlap": false
83        },
84        "dst_end": {
85          "utc_time": "2026-10-25 TIME 01:00",
86          "duration": "-1.00H",
87          "gap": false,
88          "date_time_after": "2026-10-25 TIME 02:00",
89          "date_time_before": "2026-10-25 TIME 03:00",
90          "overlap": true
91        }
92      }
93    },
94    {
95      "ip": "107.161.145.198",
96      "location": {
97        "continent_code": "NA",
98        "continent_name": "North America",
99        "country_code2": "US",
100        "country_code3": "USA",
101        "country_name": "United States",
102        "country_name_official": "United States of America",
103        "country_capital": "Washington, D.C.",
104        "state_prov": "Pennsylvania",
105        "state_code": "US-PA",
106        "district": "Philadelphia County",
107        "city": "Philadelphia",
108        "zipcode": "19102",
109        "latitude": "39.95258",
110        "longitude": "-75.16522",
111        "is_eu": false,
112        "country_flag": "https://ipgeolocation.io/static/flags/us_64.png",
113        "geoname_id": "9849057",
114        "country_emoji": "🇺🇸"
115      },
116      "country_metadata": {
117        "calling_code": "+1",
118        "tld": ".us",
119        "languages": [
120          "en-US",
121          "es-US",
122          "haw",
123          "fr"
124        ]
125      },
126      "network": {
127        "connection_type": "",
128        "route": "107.161.144.0/23",
129        "is_anycast": false
130      },
131      "currency": {
132        "code": "USD",
133        "name": "US Dollar",
134        "symbol": "$"
135      },
136      "asn": {
137        "as_number": "AS12167",
138        "organization": "LightWave Networks",
139        "country": "US",
140        "type": "HOSTING",
141        "domain": "lightwavenetworks.com",
142        "date_allocated": "2024-11-14",
143        "rir": "ARIN"
144      },
145      "company": {
146        "name": "LightWave Networks",
147        "type": "HOSTING",
148        "domain": "lightwavenetworks.com"
149      },
150      "time_zone": {
151        "name": "America/New_York",
152        "offset": -5,
153        "offset_with_dst": -5,
154        "current_time": "2026-02-24 12:57:36.111-0500",
155        "current_time_unix": 1771955856.111,
156        "current_tz_abbreviation": "EST",
157        "current_tz_full_name": "Eastern Standard Time",
158        "standard_tz_abbreviation": "EST",
159        "standard_tz_full_name": "Eastern Standard Time",
160        "is_dst": false,
161        "dst_savings": 0,
162        "dst_exists": true,
163        "dst_tz_abbreviation": "EDT",
164        "dst_tz_full_name": "Eastern Daylight Time",
165        "dst_start": {
166          "utc_time": "2026-03-08 TIME 07:00",
167          "duration": "+1.00H",
168          "gap": true,
169          "date_time_after": "2026-03-08 TIME 03:00",
170          "date_time_before": "2026-03-08 TIME 02:00",
171          "overlap": false
172        },
173        "dst_end": {
174          "utc_time": "2026-11-01 TIME 06:00",
175          "duration": "-1.00H",
176          "gap": false,
177          "date_time_after": "2026-11-01 TIME 01:00",
178          "date_time_before": "2026-11-01 TIME 02:00",
179          "overlap": true
180        }
181      }
182    }
183]

Note

The X-Successful-Record response header indicates how many IP addresses in the request returned valid data with a 200 status. Invalid entries are not included in this count.

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": "91.128.103.196",
3  "location": {
4    "continent_code": "EU",
5    "continent_name": "Europe",
6    "country_code2": "SE",
7    "country_code3": "SWE",
8    "country_name": "Sweden",
9    "country_name_official": "Kingdom of Sweden",
10    "country_capital": "Stockholm",
11    "state_prov": "Stockholms län",
12    "state_code": "SE-AB",
13    "district": "Stockholm",
14    "city": "Stockholm",
15    "zipcode": "164 40",
16    "latitude": "59.40510",
17    "longitude": "17.95510",
18    "is_eu": true,
19    "country_flag": "https://ipgeolocation.io/static/flags/se_64.png",
20    "geoname_id": "9972319",
21    "country_emoji": "🇸🇪"
22  },
23  "country_metadata": {
24    "calling_code": "+46",
25    "tld": ".se",
26    "languages": [
27      "sv-SE",
28      "se",
29      "sma",
30      "fi-SE"
31    ]
32  },
33  "currency": {
34    "code": "SEK",
35    "name": "Swedish Krona",
36    "symbol": "kr"
37  },
38  "asn": {
39    "as_number": "AS1257",
40    "organization": "Tele2 Sverige AB",
41    "country": "SE"
42  },
43  "time_zone": {
44    "name": "Europe/Stockholm",
45    "offset": 1,
46    "offset_with_dst": 1,
47    "current_time": "2026-02-13 10:54:15.252+0100",
48    "current_time_unix": 1770976455.252,
49    "current_tz_abbreviation": "CET",
50    "current_tz_full_name": "Central European Standard Time",
51    "standard_tz_abbreviation": "CET",
52    "standard_tz_full_name": "Central European Standard Time",
53    "is_dst": false,
54    "dst_savings": 0,
55    "dst_exists": true,
56    "dst_tz_abbreviation": "CEST",
57    "dst_tz_full_name": "Central European Summer Time",
58    "dst_start": {
59      "utc_time": "2026-03-29 TIME 01:00",
60      "duration": "+1.00H",
61      "gap": true,
62      "date_time_after": "2026-03-29 TIME 03:00",
63      "date_time_before": "2026-03-29 TIME 02:00",
64      "overlap": false
65    },
66    "dst_end": {
67      "utc_time": "2026-10-25 TIME 01:00",
68      "duration": "-1.00H",
69      "gap": false,
70      "date_time_after": "2026-10-25 TIME 02:00",
71      "date_time_before": "2026-10-25 TIME 03:00",
72      "overlap": true
73    }
74  }
75}

II. Paid Plan

Response

1{
2  "ip": "91.128.103.196",
3  "hostname": "91.128.103.196",
4  "location": {
5    "continent_code": "EU",
6    "continent_name": "Europe",
7    "country_code2": "SE",
8    "country_code3": "SWE",
9    "country_name": "Sweden",
10    "country_name_official": "Kingdom of Sweden",
11    "country_capital": "Stockholm",
12    "state_prov": "Stockholms län",
13    "state_code": "SE-AB",
14    "district": "Stockholm",
15    "city": "Stockholm",
16    "locality": "Stockholm",
17    "accuracy_radius": "12.251",
18    "confidence": "high",
19    "dma_code": "",
20    "zipcode": "164 40",
21    "latitude": "59.40510",
22    "longitude": "17.95510",
23    "is_eu": true,
24    "country_flag": "https://ipgeolocation.io/static/flags/se_64.png",
25    "geoname_id": "9972319",
26    "country_emoji": "🇸🇪"
27  },
28  "country_metadata": {
29    "calling_code": "+46",
30    "tld": ".se",
31    "languages": [
32      "sv-SE",
33      "se",
34      "sma",
35      "fi-SE"
36    ]
37  },
38  "network": {
39    "connection_type": "",
40    "route": "91.128.0.0/14",
41    "is_anycast": false
42  },
43  "currency": {
44    "code": "SEK",
45    "name": "Swedish Krona",
46    "symbol": "kr"
47  },
48  "asn": {
49    "as_number": "AS1257",
50    "organization": "Tele2 Sverige AB",
51    "country": "SE",
52    "type": "ISP",
53    "domain": "tele2.com",
54    "date_allocated": "2024-12-13",
55    "rir": "RIPE"
56  },
57  "company": {
58    "name": "Tele2 Sverige AB",
59    "type": "ISP",
60    "domain": "tele2.com"
61  },
62  "security": {
63    "threat_score": 0,
64    "is_tor": false,
65    "is_proxy": false,
66    "proxy_provider_names": [],
67    "proxy_confidence_score": 0,
68    "proxy_last_seen": "",
69    "is_residential_proxy": false,
70    "is_vpn": false,
71    "vpn_provider_names": [],
72    "vpn_confidence_score": 0,
73    "vpn_last_seen": "",
74    "is_relay": false,
75    "relay_provider_name": "",
76    "is_anonymous": false,
77    "is_known_attacker": false,
78    "is_bot": false,
79    "is_spam": false,
80    "is_cloud_provider": false,
81    "cloud_provider_name": ""
82  },
83  "abuse": {
84    "route": "91.128.0.0/14",
85    "country": "SE",
86    "name": "Swipnet Staff",
87    "organization": "",
88    "kind": "group",
89    "address": "Tele2 AB/Swedish IP Network, IP Registry, Torshamnsgatan 17 164 40 Kista SWEDEN",
90    "emails": [
91      "abuse@tele2.com"
92    ],
93    "phone_numbers": [
94      "+46 8 5626 42 10"
95    ]
96  },
97  "time_zone": {
98    "name": "Europe/Stockholm",
99    "offset": 1,
100    "offset_with_dst": 1,
101    "current_time": "2026-02-13 10:55:01.983+0100",
102    "current_time_unix": 1770976501.983,
103    "current_tz_abbreviation": "CET",
104    "current_tz_full_name": "Central European Standard Time",
105    "standard_tz_abbreviation": "CET",
106    "standard_tz_full_name": "Central European Standard Time",
107    "is_dst": false,
108    "dst_savings": 0,
109    "dst_exists": true,
110    "dst_tz_abbreviation": "CEST",
111    "dst_tz_full_name": "Central European Summer Time",
112    "dst_start": {
113      "utc_time": "2026-03-29 TIME 01:00",
114      "duration": "+1.00H",
115      "gap": true,
116      "date_time_after": "2026-03-29 TIME 03:00",
117      "date_time_before": "2026-03-29 TIME 02:00",
118      "overlap": false
119    },
120    "dst_end": {
121      "utc_time": "2026-10-25 TIME 01:00",
122      "duration": "-1.00H",
123      "gap": false,
124      "date_time_after": "2026-10-25 TIME 02:00",
125      "date_time_before": "2026-10-25 TIME 03:00",
126      "overlap": true
127    }
128  },
129  "user_agent": {
130    "user_agent_string": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/143.0.0.0 Safari/537.36 Edg/143.0.0.0",
131    "name": "Edge",
132    "type": "Browser",
133    "version": "143",
134    "version_major": "143",
135    "device": {
136      "name": "Linux Desktop",
137      "type": "Desktop",
138      "brand": "Unknown",
139      "cpu": "Intel x86_64"
140    },
141    "engine": {
142      "name": "Blink",
143      "type": "Browser",
144      "version": "143",
145      "version_major": "143"
146    },
147    "operating_system": {
148      "name": "Linux",
149      "type": "Desktop",
150      "version": "??",
151      "version_major": "??",
152      "build": "??"
153    }
154  }
155}

Reference to IPGeolocation API Response

1. Standalone fields reference

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

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "Standalone fields reference",
  "description": "Schema for Standalone fields reference",
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "ip": {
      "type": "string",
      "description": "The IP address used for the lookup (IPv4 or IPv6).",
      "availability": "FREE",
      "can-be-empty": false
    },
    "domain": {
      "type": "string",
      "description": "The input domain, returned only for domain-based lookups.",
      "availability": "PAID",
      "can-be-empty": false
    },
    "hostname": {
      "type": "string",
      "description": "Reverse DNS hostname (PTR) for the input IP; returns the input IP if not resolvable.",
      "availability": "PAID",
      "can-be-empty": false
    }
  }
}

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