Overview

Credits are charged only when the request succeeds ( HTTP 200 ).

For every successful response, we include the X-Credits-Charged header. This header tells you exactly how many credits were deducted for that request, and it is the billing source of truth.

For bulk endpoints, credits are calculated like this: total credits = credits per lookup × number of valid IPs.

IPs that are private, bogon, or malformed are not counted as valid IPs, so they do not consume credits.

Credits Billing for IP Lookup API

The IP Geolocation API is available to both free and paid users. On the free plan, each successful request charges 1 credit. For paid plans, refer to the table below for exact billing details.

These rules apply to single lookup /v3/ipgeo and bulk lookup /v3/ipgeo-bulk .

Only Security and Abuse add extra credits. Modules such as user_agent , time_zone , dma_code , geo_accuracy , hostname , liveHostname , and hostnameFallbackLive do not add extra credits beyond base lookup on paid plans.

What You RequestHow to RequestCredits (Per Success)
IP lookup (default response)
/v3/ipgeo with ip or caller IP
1 credit
IP lookup + Everything except Security & Abuse
include=dma_code,geo_accuracy,hostname,user_agent
1 credit
IP lookup + Security
include=security
3 credits
IP lookup + Abuse
include=abuse
2 credits
IP lookup + Security + Abuse
include=security,abuse
4 credits
IP lookup + Everything
include=dma_code,geo_accuracy,hostname,user_agent,security,abuse or include=*
4 credits
Only Security (no base IP data)
include=security&fields=security
2 credits
Only Abuse (no base IP data)
include=abuse&fields=abuse
1 credit
Bulk lookup
/v3/ipgeo-bulk
Same rules per valid IP
Note

* Hostname modes supported in include are include=hostname , include=liveHostname , and include=hostnameFallbackLive .

To learn more about request parameters in IP Geolocation API and how to include, exclude, or filter them, please refer to the API documentation.

Credits Billing for Dedicated APIs

Use dedicated APIs when you need a focused dataset with a fixed per-request cost.

Each dedicated API below links to its own full documentation page with endpoint details, request parameters, and response schema. Some APIs also provide additional features and fields when used individually.

Dedicated APIPlanBase URLResponseCredits (Per Success)
IP Security APIPaid
/v3/security
Security-only response (VPN, proxy, threat signals)
2 credits
IP Abuse Contact APIPaid
/v3/abuse
Abuse contact details-only response
1 credit
ASN APIPaid
/v3/asn
ASN enrichment like routes, peers, upstreams, downstreams, WHOIS response
1 credit
Timezone API
PaidFree
/v3/timezone/v3/timezone/convert
Timezone lookup and time conversion (IP, timezone name, IATA, ICAO, coordinates)
1 credit
User Agent API
PaidFree
/v3/user-agent
User agent parsing-only response
1 credit
Astronomy API
PaidFree
/v3/astronomy/v3/astronomy/timeSeries
Sun/moon data such as sunrise, sunset, moonrise, moonset, azimuth, and altitude
1 credit
Note
Please note that the base URLs listed in the table above are base to https://api.ipgeolocation.io

Response Examples (IP Geolocation API)

All examples in this section use the unified /v3/ipgeo endpoint and show how response shape and credits change based on your requested modules.

If you only need one module, use the dedicated API links listed in the Credits Billing for Dedicated APIs table above.

Free plan default response

Default IP Geolocation API response for free plan subscribers.

Credits Charged1
Request
curl -i 'https://api.ipgeolocation.io/v3/ipgeo?apiKey=API_KEY&ip=165.227.0.0'
Response
1{
2  "ip": "165.227.0.0",
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 County",
14    "city": "Santa Clara",
15    "zipcode": "95051",
16    "latitude": "37.35983",
17    "longitude": "-121.98144",
18    "is_eu": false,
19    "country_flag": "https://ipgeolocation.io/static/flags/us_64.png",
20    "geoname_id": "5346804",
21    "country_emoji": "🇺🇸"
22  },
23  "country_metadata": {
24    "calling_code": "+1",
25    "tld": ".us",
26    "languages": [
27      "en-US",
28      "es-US",
29      "haw",
30      "fr"
31    ]
32  },
33  "currency": {
34    "code": "USD",
35    "name": "US Dollar",
36    "symbol": "$"
37  },
38  "asn": {
39    "as_number": "AS14061",
40    "organization": "DigitalOcean, LLC",
41    "country": "US"
42  },
43  "time_zone": {
44    "name": "America/Los_Angeles",
45    "offset": -8,
46    "offset_with_dst": -8,
47    "current_time": "2026-02-09 09:54:51.206-0800",
48    "current_time_unix": 1770659691.206,
49    "current_tz_abbreviation": "PST",
50    "current_tz_full_name": "Pacific Standard Time",
51    "standard_tz_abbreviation": "PST",
52    "standard_tz_full_name": "Pacific Standard Time",
53    "is_dst": false,
54    "dst_savings": 0,
55    "dst_exists": true,
56    "dst_tz_abbreviation": "PDT",
57    "dst_tz_full_name": "Pacific Daylight Time",
58    "dst_start": {
59      "utc_time": "2026-03-08 TIME 10",
60      "duration": "+1H",
61      "gap": true,
62      "date_time_after": "2026-03-08 TIME 03",
63      "date_time_before": "2026-03-08 TIME 02",
64      "overlap": false
65    },
66    "dst_end": {
67      "utc_time": "2026-11-01 TIME 09",
68      "duration": "-1H",
69      "gap": false,
70      "date_time_after": "2026-11-01 TIME 01",
71      "date_time_before": "2026-11-01 TIME 02",
72      "overlap": true
73    }
74  }
75}

Paid plan default response

Full default response on paid plan without include parameter.

Credits Charged1
Request
curl -i 'https://api.ipgeolocation.io/v3/ipgeo?apiKey=API_KEY&ip=165.227.0.0'
Response
1{
2  "ip": "165.227.0.0",
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 County",
14    "city": "Santa Clara",
15    "zipcode": "95051",
16    "latitude": "37.35983",
17    "longitude": "-121.98144",
18    "is_eu": false,
19    "country_flag": "https://ipgeolocation.io/static/flags/us_64.png",
20    "geoname_id": "5346804",
21    "country_emoji": "🇺🇸"
22  },
23  "country_metadata": {
24    "calling_code": "+1",
25    "tld": ".us",
26    "languages": [
27      "en-US",
28      "es-US",
29      "haw",
30      "fr"
31    ]
32  },
33  "network": {
34    "connection_type": "",
35    "route": "165.227.0.0/20",
36    "is_anycast": false
37  },
38  "currency": {
39    "code": "USD",
40    "name": "US Dollar",
41    "symbol": "$"
42  },
43  "asn": {
44    "as_number": "AS14061",
45    "organization": "DigitalOcean, LLC",
46    "country": "US",
47    "type": "HOSTING",
48    "domain": "digitalocean.com",
49    "date_allocated": "2025-03-04T00:00",
50    "rir": "ARIN"
51  },
52  "company": {
53    "name": "DigitalOcean, LLC",
54    "type": "Hosting",
55    "domain": "digitalocean.com"
56  },
57  "time_zone": {
58    "name": "America/Los_Angeles",
59    "offset": -8,
60    "offset_with_dst": -8,
61    "current_time": "2026-02-09 09:54:59.340-0800",
62    "current_time_unix": 1770659699.34,
63    "current_tz_abbreviation": "PST",
64    "current_tz_full_name": "Pacific Standard Time",
65    "standard_tz_abbreviation": "PST",
66    "standard_tz_full_name": "Pacific Standard Time",
67    "is_dst": false,
68    "dst_savings": 0,
69    "dst_exists": true,
70    "dst_tz_abbreviation": "PDT",
71    "dst_tz_full_name": "Pacific Daylight Time",
72    "dst_start": {
73      "utc_time": "2026-03-08 TIME 10",
74      "duration": "+1H",
75      "gap": true,
76      "date_time_after": "2026-03-08 TIME 03",
77      "date_time_before": "2026-03-08 TIME 02",
78      "overlap": false
79    },
80    "dst_end": {
81      "utc_time": "2026-11-01 TIME 09",
82      "duration": "-1H",
83      "gap": false,
84      "date_time_after": "2026-11-01 TIME 01",
85      "date_time_before": "2026-11-01 TIME 02",
86      "overlap": true
87    }
88  }
89}

Paid response with all non billable modules

Includes dma_code, user_agent, hostname*, and geo_accuracy. No extra charge beyond base lookup.

Credits Charged1
Request
curl -i 'https://api.ipgeolocation.io/v3/ipgeo?apiKey=API_KEY&ip=165.227.0.0&include=dma_code,geo_accuracy,hostname,user_agent'
# * Hostname modes: include=hostname | include=liveHostname | include=hostnameFallbackLive
Response
1{
2  "ip": "165.227.0.0",
3  "hostname": "165.227.0.0",
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 County",
15    "city": "Santa Clara",
16    "zipcode": "95051",
17    "latitude": "37.35983",
18    "longitude": "-121.98144",
19    "is_eu": false,
20    "country_flag": "https://ipgeolocation.io/static/flags/us_64.png",
21    "geoname_id": "5346804",
22    "country_emoji": "🇺🇸",
23    "locality": "Santa Clara",
24    "accuracy_radius": "7.361",
25    "confidence": "medium",
26    "dma_code": "807"
27  },
28  "country_metadata": {
29    "calling_code": "+1",
30    "tld": ".us",
31    "languages": [
32      "en-US",
33      "es-US",
34      "haw",
35      "fr"
36    ]
37  },
38  "network": {
39    "connection_type": "",
40    "route": "165.227.0.0/20",
41    "is_anycast": false
42  },
43  "currency": {
44    "code": "USD",
45    "name": "US Dollar",
46    "symbol": "$"
47  },
48  "asn": {
49    "as_number": "AS14061",
50    "organization": "DigitalOcean, LLC",
51    "country": "US",
52    "type": "HOSTING",
53    "domain": "digitalocean.com",
54    "date_allocated": "2025-03-04T00:00",
55    "rir": "ARIN"
56  },
57  "company": {
58    "name": "DigitalOcean, LLC",
59    "type": "Hosting",
60    "domain": "digitalocean.com"
61  },
62  "time_zone": {
63    "name": "America/Los_Angeles",
64    "offset": -8,
65    "offset_with_dst": -8,
66    "current_time": "2026-02-09 09:58:31.426-0800",
67    "current_time_unix": 1770659911.426,
68    "current_tz_abbreviation": "PST",
69    "current_tz_full_name": "Pacific Standard Time",
70    "standard_tz_abbreviation": "PST",
71    "standard_tz_full_name": "Pacific Standard Time",
72    "is_dst": false,
73    "dst_savings": 0,
74    "dst_exists": true,
75    "dst_tz_abbreviation": "PDT",
76    "dst_tz_full_name": "Pacific Daylight Time",
77    "dst_start": {
78      "utc_time": "2026-03-08 TIME 10",
79      "duration": "+1H",
80      "gap": true,
81      "date_time_after": "2026-03-08 TIME 03",
82      "date_time_before": "2026-03-08 TIME 02",
83      "overlap": false
84    },
85    "dst_end": {
86      "utc_time": "2026-11-01 TIME 09",
87      "duration": "-1H",
88      "gap": false,
89      "date_time_after": "2026-11-01 TIME 01",
90      "date_time_before": "2026-11-01 TIME 02",
91      "overlap": true
92    }
93  },
94  "user_agent": {
95    "user_agent_string": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/143.0.0.0 Safari/537.36",
96    "name": "Chrome",
97    "type": "Browser",
98    "version": "143",
99    "version_major": "143",
100    "device": {
101      "name": "Linux Desktop",
102      "type": "Desktop",
103      "brand": "Unknown",
104      "cpu": "Intel x86_64"
105    },
106    "engine": {
107      "name": "Blink",
108      "type": "Browser",
109      "version": "143",
110      "version_major": "143"
111    },
112    "operating_system": {
113      "name": "Linux",
114      "type": "Desktop",
115      "version": "??",
116      "version_major": "??",
117      "build": "??"
118    }
119  }
120}

Paid response with Security & Abuse

Includes billable Security and Abuse modules on top of paid default fields.

Credits Charged4
Request
curl -i 'https://api.ipgeolocation.io/v3/ipgeo?apiKey=API_KEY&ip=165.227.0.0&include=security,abuse'
Response
1{
2  "ip": "165.227.0.0",
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 County",
14    "city": "Santa Clara",
15    "zipcode": "95051",
16    "latitude": "37.35983",
17    "longitude": "-121.98144",
18    "is_eu": false,
19    "country_flag": "https://ipgeolocation.io/static/flags/us_64.png",
20    "geoname_id": "5346804",
21    "country_emoji": "🇺🇸"
22  },
23  "country_metadata": {
24    "calling_code": "+1",
25    "tld": ".us",
26    "languages": [
27      "en-US",
28      "es-US",
29      "haw",
30      "fr"
31    ]
32  },
33  "network": {
34    "connection_type": "",
35    "route": "165.227.0.0/20",
36    "is_anycast": false
37  },
38  "currency": {
39    "code": "USD",
40    "name": "US Dollar",
41    "symbol": "$"
42  },
43  "asn": {
44    "as_number": "AS14061",
45    "organization": "DigitalOcean, LLC",
46    "country": "US",
47    "type": "HOSTING",
48    "domain": "digitalocean.com",
49    "date_allocated": "2025-03-04T00:00",
50    "rir": "ARIN"
51  },
52  "company": {
53    "name": "DigitalOcean, LLC",
54    "type": "Hosting",
55    "domain": "digitalocean.com"
56  },
57  "security": {
58    "threat_score": 5,
59    "is_tor": false,
60    "is_proxy": false,
61    "proxy_provider_names": [],
62    "proxy_confidence_score": 0,
63    "proxy_last_seen": "",
64    "is_residential_proxy": false,
65    "is_vpn": false,
66    "vpn_provider_names": [],
67    "vpn_confidence_score": 0,
68    "vpn_last_seen": "",
69    "is_relay": false,
70    "relay_provider_name": "",
71    "is_anonymous": false,
72    "is_known_attacker": false,
73    "is_bot": false,
74    "is_spam": false,
75    "is_cloud_provider": true,
76    "cloud_provider_name": "DigitalOcean, LLC"
77  },
78  "abuse": {
79    "route": "165.227.0.0/16",
80    "country": "",
81    "name": "DigitalOcean Abuse",
82    "organization": "DigitalOcean Abuse",
83    "kind": "group",
84    "address": "105 Edgeview Drive, Suite 425\\nBroomfield\\nCO\\n80021\\nUnited States",
85    "emails": [
86      "abuse@digitalocean.com"
87    ],
88    "phone_numbers": [
89      "+1-646-827-4366"
90    ]
91  },
92  "time_zone": {
93    "name": "America/Los_Angeles",
94    "offset": -8,
95    "offset_with_dst": -8,
96    "current_time": "2026-02-09 10:00:14.678-0800",
97    "current_time_unix": 1770660014.678,
98    "current_tz_abbreviation": "PST",
99    "current_tz_full_name": "Pacific Standard Time",
100    "standard_tz_abbreviation": "PST",
101    "standard_tz_full_name": "Pacific Standard Time",
102    "is_dst": false,
103    "dst_savings": 0,
104    "dst_exists": true,
105    "dst_tz_abbreviation": "PDT",
106    "dst_tz_full_name": "Pacific Daylight Time",
107    "dst_start": {
108      "utc_time": "2026-03-08 TIME 10",
109      "duration": "+1H",
110      "gap": true,
111      "date_time_after": "2026-03-08 TIME 03",
112      "date_time_before": "2026-03-08 TIME 02",
113      "overlap": false
114    },
115    "dst_end": {
116      "utc_time": "2026-11-01 TIME 09",
117      "duration": "-1H",
118      "gap": false,
119      "date_time_after": "2026-11-01 TIME 01",
120      "date_time_before": "2026-11-01 TIME 02",
121      "overlap": true
122    }
123  }
124}

Paid response with all fields

You can include everything explicitly or use include=*.

Credits Charged4
Request
# Option 1
curl -i 'https://api.ipgeolocation.io/v3/ipgeo?apiKey=API_KEY&ip=165.227.0.0&include=dma_code,geo_accuracy,hostname,user_agent,security,abuse'

# Option 2
curl -i 'https://api.ipgeolocation.io/v3/ipgeo?apiKey=API_KEY&ip=165.227.0.0&include=*'

# * Hostname modes: include=hostname | include=liveHostname | include=hostnameFallbackLive
Response
1{
2  "ip": "165.227.0.0",
3  "hostname": "165.227.0.0",
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 County",
15    "city": "Santa Clara",
16    "zipcode": "95051",
17    "latitude": "37.35983",
18    "longitude": "-121.98144",
19    "is_eu": false,
20    "country_flag": "https://ipgeolocation.io/static/flags/us_64.png",
21    "geoname_id": "5346804",
22    "country_emoji": "🇺🇸",
23    "locality": "Santa Clara",
24    "accuracy_radius": "7.361",
25    "confidence": "medium",
26    "dma_code": "807"
27  },
28  "country_metadata": {
29    "calling_code": "+1",
30    "tld": ".us",
31    "languages": [
32      "en-US",
33      "es-US",
34      "haw",
35      "fr"
36    ]
37  },
38  "network": {
39    "connection_type": "",
40    "route": "165.227.0.0/20",
41    "is_anycast": false
42  },
43  "currency": {
44    "code": "USD",
45    "name": "US Dollar",
46    "symbol": "$"
47  },
48  "asn": {
49    "as_number": "AS14061",
50    "organization": "DigitalOcean, LLC",
51    "country": "US",
52    "type": "HOSTING",
53    "domain": "digitalocean.com",
54    "date_allocated": "2025-03-04T00:00",
55    "rir": "ARIN"
56  },
57  "company": {
58    "name": "DigitalOcean, LLC",
59    "type": "Hosting",
60    "domain": "digitalocean.com"
61  },
62  "security": {
63    "threat_score": 5,
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": true,
81    "cloud_provider_name": "DigitalOcean, LLC"
82  },
83  "abuse": {
84    "route": "165.227.0.0/16",
85    "country": "",
86    "name": "DigitalOcean Abuse",
87    "organization": "DigitalOcean Abuse",
88    "kind": "group",
89    "address": "105 Edgeview Drive, Suite 425\\nBroomfield\\nCO\\n80021\\nUnited States",
90    "emails": [
91      "abuse@digitalocean.com"
92    ],
93    "phone_numbers": [
94      "+1-646-827-4366"
95    ]
96  },
97  "time_zone": {
98    "name": "America/Los_Angeles",
99    "offset": -8,
100    "offset_with_dst": -8,
101    "current_time": "2026-02-09 10:02:36.982-0800",
102    "current_time_unix": 1770660156.982,
103    "current_tz_abbreviation": "PST",
104    "current_tz_full_name": "Pacific Standard Time",
105    "standard_tz_abbreviation": "PST",
106    "standard_tz_full_name": "Pacific Standard Time",
107    "is_dst": false,
108    "dst_savings": 0,
109    "dst_exists": true,
110    "dst_tz_abbreviation": "PDT",
111    "dst_tz_full_name": "Pacific Daylight Time",
112    "dst_start": {
113      "utc_time": "2026-03-08 TIME 10",
114      "duration": "+1H",
115      "gap": true,
116      "date_time_after": "2026-03-08 TIME 03",
117      "date_time_before": "2026-03-08 TIME 02",
118      "overlap": false
119    },
120    "dst_end": {
121      "utc_time": "2026-11-01 TIME 09",
122      "duration": "-1H",
123      "gap": false,
124      "date_time_after": "2026-11-01 TIME 01",
125      "date_time_before": "2026-11-01 TIME 02",
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",
131    "name": "Chrome",
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}
Important

For exact billing on any request, always check the returned response header X-Credits-Charged .

Subscribe Our Newsletter

Get the latest in geolocation tech, straight to your inbox.