API Credits Usage
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.
Bulk endpoints are charged the same way as the matching single lookup, once for every entry that returns data: total credits = credits per single lookup × number of IPs (or user agent strings) that return data.
Entries that come back as a message object instead of data, such as private, bogon or malformed IPs, 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 Request | How to Request | Credits Charged (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 creditsBase IP lookup costs 1 credit. Adding Security costs +2 credits. Total 3 credits per valid IP. |
| Live detection (default response) | (without include param) | 3 creditsLive detection only. Total 3 credits per call. |
| Live detection + IP Security | include=security | 5 creditsLive detection costs 3 credits. Adding Security costs +2 credits. Total 5 credits per call. |
| Live detection + Location/ASN/Company | include=location,asn,company | 4 creditsLive detection costs 3 credits. The location, asn and company objects share a single +1 credit, whether you request one of them or all three. Total 4 credits per call. |
| Live detection + everything | include=all | 6 creditsLive detection with every object included. Total 6 credits per call. |
| IP lookup + Abuse | include=abuse | 2 creditsBase IP lookup costs 1 credit. Adding Abuse costs +1 credit. Total 2 credits per valid IP. |
| IP lookup + Security + Abuse | include=security,abuse | 4 creditsBase IP lookup costs 1 credit. Adding Security costs +2 credits and Abuse costs +1 credit. Total 4 credits per valid IP. |
| IP lookup + Everything | include=dma_code,geo_accuracy,hostname,user_agent,security,abuse or include=* | 4 creditsBase IP lookup costs 1 credit. Everything else stays 1 credit unless you include Security (+2) or Abuse (+1). Since this includes both, total is 4 credits per valid IP. |
| Only Security (no base IP data) | include=security&fields=security | 2 creditsThis returns Security only (no base IP lookup data). It costs 2 credits per valid IP. |
| Only Abuse (no base IP data) | include=abuse&fields=abuse | 1 credit |
| Security + Abuse (no base IP data) | include=security,abuse&fields=security,abuse | 3 creditsAdding Security costs +2 credits and Abuse costs +1 credit. Total 3 credits per valid IP. |
| Bulk lookup | /v3/ipgeo-bulk | Same rules per valid IP |
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 API | PlanAvailability | Base URLBase URL(s) | ResponseReturned Data | Credits (Per Success)Credits Charged (Per Success) |
|---|---|---|---|---|
| IP Security API | Paid | /v3/security/v3/security-bulk | Security-only response (VPN, proxy, threat signals) | 2 credits |
| Real-Time Proxy & VPN Detection | Paid | session-analysis.js(CDN) | Live VPN/proxy detection | 3 credits |
| Real-Time Proxy & VPN Detection + IP Security | Paid | session-analysis.js(CDN) | Live VPN/proxy detection plus known IP reputation | 5 credits |
| IP Abuse Contact API | Paid | /v3/abuse/v3/abuse-bulk | Abuse contact details-only response | 1 credit |
| ASN API | Paid | /v3/asn | ASN enrichment like routes, peers, upstreams, downstreams, WHOIS response | 1 credit |
| Time Zone API | Paid or Free | /v3/timezone/v3/timezone/convert | Time zone lookup and time conversion (IP, time zone name, IATA, ICAO, coordinates) | 1 credit |
| User Agent API | Paid or Free | GET /v3/user-agent | 1 credit to parse the request's User-Agent header | 1 credit |
| User Agent API | Paid | POST /v3/user-agent | 1 credit to parse one supplied string | 1 credit |
| User Agent API | Paid | POST /v3/user-agent-bulk | 1 credit per parsed string, up to 50,000 strings per request | 1 credit |
| Astronomy API | Paid or Free | /v3/astronomy/v3/astronomy/timeSeries | Sun/moon data such as sunrise, sunset, moonrise, moonset, azimuth, and altitude | 1 credit |
Surcharges And Overage Billing
Paid plans keep serving requests after the API credits for a billing cycle run out, because overage is on by default on all paid plans. That extra usage is billed as surcharge credits, sold in fixed blocks at the rate listed for the plan, and it never goes past the plan's maximum surcharge amount limit. You can turn overage off anytime with the Allow Surcharge Usage toggle on your dashboard. The API responds with 429 Too Many Requests when credits run out with overage off, or when the surcharge limit is reached. The Developer plan has no surcharge, so it stays capped at its daily credits.
| Plan | Billing Cycle | Price | API Credits | Extra API Keys | Surcharge Credits | Max Surcharge Amount Limit |
|---|---|---|---|---|---|---|
Developer | Free | $0 | 1,000 per day | 0 | 0 | $0 |
Starter | Monthly | $19 | 150K | 1 | 25K per $5 | $500 |
| Yearly | $190 | 1.8M | ||||
Plus | Monthly | $49 | 500K | 2 | 40K per $5 | $500 |
| Yearly | $490 | 6M | ||||
Pro | Monthly | $79 | 1M | 2 | 50K per $5 | $1,000 |
| Yearly | $790 | 12M | ||||
Business | Monthly | $129 | 2M | 3 | 65K per $5 | $1,000 |
| Yearly | $1,290 | 24M | ||||
Premium | Monthly | $249 | 5M | 3 | 85K per $5 | $1,000 |
| Yearly | $2,490 | 60M |
Surcharge Pricing
$5/Surcharge Credits shown in the table for each plan.
Extra API Keys
Starter: 1 Extra key
Plus / Pro: 2 Extra keys
Business / Premium: 3 Extra keys
Surcharge Credit Limit:
Starter / Plus: Up to $500
Pro / Business / Premium: Up to $1,000
Prices and credit allowances above follow the live plan data. For the full plan comparison and yearly discounts, see the Pricing page.
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.
curl -i 'https://api.ipgeolocation.io/v3/ipgeo?apiKey=API_KEY&ip=165.227.0.0'{
"ip": "165.227.0.0",
"location": {
"continent_code": "NA",
"continent_name": "North America",
"country_code2": "US",
"country_code3": "USA",
"country_name": "United States",
"country_name_official": "United States of America",
"country_capital": "Washington, D.C.",
"state_prov": "California",
"state_code": "US-CA",
"district": "Santa Clara County",
"city": "Santa Clara",
"zipcode": "95051",
"latitude": "37.35983",
"longitude": "-121.98144",
"is_eu": false,
"country_flag": "https://ipgeolocation.io/static/flags/us_64.png",
"geoname_id": "5346804",
"country_emoji": "🇺🇸"
},
"country_metadata": {
"calling_code": "+1",
"tld": ".us",
"languages": [
"en-US",
"es-US",
"haw",
"fr"
]
},
"currency": {
"code": "USD",
"name": "US Dollar",
"symbol": "$"
},
"asn": {
"as_number": "AS14061",
"organization": "DigitalOcean, LLC",
"country": "US"
},
"time_zone": {
"name": "America/Los_Angeles",
"offset": -8,
"offset_with_dst": -8,
"current_time": "2026-02-09 09:54:51.206-0800",
"current_time_unix": 1770659691.206,
"current_tz_abbreviation": "PST",
"current_tz_full_name": "Pacific Standard Time",
"standard_tz_abbreviation": "PST",
"standard_tz_full_name": "Pacific Standard Time",
"is_dst": false,
"dst_savings": 0,
"dst_exists": true,
"dst_tz_abbreviation": "PDT",
"dst_tz_full_name": "Pacific Daylight Time",
"dst_start": {
"utc_time": "2026-03-08 TIME 10:00",
"duration": "+1.00H",
"gap": true,
"date_time_after": "2026-03-08 TIME 03:00",
"date_time_before": "2026-03-08 TIME 02:00",
"overlap": false
},
"dst_end": {
"utc_time": "2026-11-01 TIME 09:00",
"duration": "-1.00H",
"gap": false,
"date_time_after": "2026-11-01 TIME 01:00",
"date_time_before": "2026-11-01 TIME 02:00",
"overlap": true
}
}
}Paid Plan Default Response
Full default response on paid plan without include parameter.
curl -i 'https://api.ipgeolocation.io/v3/ipgeo?apiKey=API_KEY&ip=165.227.0.0'{
"ip": "165.227.0.0",
"location": {
"continent_code": "NA",
"continent_name": "North America",
"country_code2": "US",
"country_code3": "USA",
"country_name": "United States",
"country_name_official": "United States of America",
"country_capital": "Washington, D.C.",
"state_prov": "California",
"state_code": "US-CA",
"district": "Santa Clara County",
"city": "Santa Clara",
"zipcode": "95051",
"latitude": "37.35983",
"longitude": "-121.98144",
"is_eu": false,
"country_flag": "https://ipgeolocation.io/static/flags/us_64.png",
"geoname_id": "5346804",
"country_emoji": "🇺🇸"
},
"country_metadata": {
"calling_code": "+1",
"tld": ".us",
"languages": [
"en-US",
"es-US",
"haw",
"fr"
]
},
"network": {
"connection_type": "",
"route": "165.227.0.0/20",
"is_anycast": false
},
"currency": {
"code": "USD",
"name": "US Dollar",
"symbol": "$"
},
"asn": {
"as_number": "AS14061",
"organization": "DigitalOcean, LLC",
"country": "US",
"type": "HOSTING",
"domain": "digitalocean.com",
"date_allocated": "2025-03-04",
"rir": "ARIN"
},
"company": {
"name": "DigitalOcean, LLC",
"type": "HOSTING",
"domain": "digitalocean.com"
},
"time_zone": {
"name": "America/Los_Angeles",
"offset": -8,
"offset_with_dst": -8,
"current_time": "2026-02-09 09:54:59.340-0800",
"current_time_unix": 1770659699.34,
"current_tz_abbreviation": "PST",
"current_tz_full_name": "Pacific Standard Time",
"standard_tz_abbreviation": "PST",
"standard_tz_full_name": "Pacific Standard Time",
"is_dst": false,
"dst_savings": 0,
"dst_exists": true,
"dst_tz_abbreviation": "PDT",
"dst_tz_full_name": "Pacific Daylight Time",
"dst_start": {
"utc_time": "2026-03-08 TIME 10:00",
"duration": "+1.00H",
"gap": true,
"date_time_after": "2026-03-08 TIME 03:00",
"date_time_before": "2026-03-08 TIME 02:00",
"overlap": false
},
"dst_end": {
"utc_time": "2026-11-01 TIME 09:00",
"duration": "-1.00H",
"gap": false,
"date_time_after": "2026-11-01 TIME 01:00",
"date_time_before": "2026-11-01 TIME 02:00",
"overlap": true
}
}
}Paid Plan Response with All Non-Billable Modules
Includes dma_code, user_agent, hostname*, and geo_accuracy. No extra charge beyond base lookup.
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{
"ip": "165.227.0.0",
"hostname": "165.227.0.0",
"location": {
"continent_code": "NA",
"continent_name": "North America",
"country_code2": "US",
"country_code3": "USA",
"country_name": "United States",
"country_name_official": "United States of America",
"country_capital": "Washington, D.C.",
"state_prov": "California",
"state_code": "US-CA",
"district": "Santa Clara County",
"city": "Santa Clara",
"locality": "Santa Clara",
"accuracy_radius": "7.361",
"confidence": "medium",
"dma_code": "807",
"zipcode": "95051",
"latitude": "37.35983",
"longitude": "-121.98144",
"is_eu": false,
"country_flag": "https://ipgeolocation.io/static/flags/us_64.png",
"geoname_id": "5346804",
"country_emoji": "🇺🇸"
},
"country_metadata": {
"calling_code": "+1",
"tld": ".us",
"languages": [
"en-US",
"es-US",
"haw",
"fr"
]
},
"network": {
"connection_type": "",
"route": "165.227.0.0/20",
"is_anycast": false
},
"currency": {
"code": "USD",
"name": "US Dollar",
"symbol": "$"
},
"asn": {
"as_number": "AS14061",
"organization": "DigitalOcean, LLC",
"country": "US",
"type": "HOSTING",
"domain": "digitalocean.com",
"date_allocated": "2025-03-04",
"rir": "ARIN"
},
"company": {
"name": "DigitalOcean, LLC",
"type": "HOSTING",
"domain": "digitalocean.com"
},
"time_zone": {
"name": "America/Los_Angeles",
"offset": -8,
"offset_with_dst": -8,
"current_time": "2026-02-09 09:58:31.426-0800",
"current_time_unix": 1770659911.426,
"current_tz_abbreviation": "PST",
"current_tz_full_name": "Pacific Standard Time",
"standard_tz_abbreviation": "PST",
"standard_tz_full_name": "Pacific Standard Time",
"is_dst": false,
"dst_savings": 0,
"dst_exists": true,
"dst_tz_abbreviation": "PDT",
"dst_tz_full_name": "Pacific Daylight Time",
"dst_start": {
"utc_time": "2026-03-08 TIME 10:00",
"duration": "+1.00H",
"gap": true,
"date_time_after": "2026-03-08 TIME 03:00",
"date_time_before": "2026-03-08 TIME 02:00",
"overlap": false
},
"dst_end": {
"utc_time": "2026-11-01 TIME 09:00",
"duration": "-1.00H",
"gap": false,
"date_time_after": "2026-11-01 TIME 01:00",
"date_time_before": "2026-11-01 TIME 02:00",
"overlap": true
}
},
"user_agent": {
"user_agent_string": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/143.0.0.0 Safari/537.36",
"name": "Chrome",
"type": "Browser",
"version": "143",
"version_major": "143",
"device": {
"name": "Linux Desktop",
"type": "Desktop",
"brand": "Unknown",
"cpu": "Intel x86_64"
},
"engine": {
"name": "Blink",
"type": "Browser",
"version": "143",
"version_major": "143"
},
"operating_system": {
"name": "Linux",
"type": "Desktop",
"version": "??",
"version_major": "??",
"build": "??"
}
}
}Paid Plan Response with Security & Abuse
Includes billable Security and Abuse modules on top of paid default fields.
curl -i 'https://api.ipgeolocation.io/v3/ipgeo?apiKey=API_KEY&ip=165.227.0.0&include=security,abuse'{
"ip": "165.227.0.0",
"location": {
"continent_code": "NA",
"continent_name": "North America",
"country_code2": "US",
"country_code3": "USA",
"country_name": "United States",
"country_name_official": "United States of America",
"country_capital": "Washington, D.C.",
"state_prov": "California",
"state_code": "US-CA",
"district": "Santa Clara County",
"city": "Santa Clara",
"zipcode": "95051",
"latitude": "37.35983",
"longitude": "-121.98144",
"is_eu": false,
"country_flag": "https://ipgeolocation.io/static/flags/us_64.png",
"geoname_id": "5346804",
"country_emoji": "🇺🇸"
},
"country_metadata": {
"calling_code": "+1",
"tld": ".us",
"languages": [
"en-US",
"es-US",
"haw",
"fr"
]
},
"network": {
"connection_type": "",
"route": "165.227.0.0/20",
"is_anycast": false
},
"currency": {
"code": "USD",
"name": "US Dollar",
"symbol": "$"
},
"asn": {
"as_number": "AS14061",
"organization": "DigitalOcean, LLC",
"country": "US",
"type": "HOSTING",
"domain": "digitalocean.com",
"date_allocated": "2025-03-04",
"rir": "ARIN"
},
"company": {
"name": "DigitalOcean, LLC",
"type": "HOSTING",
"domain": "digitalocean.com"
},
"security": {
"threat_score": 5,
"is_tor": false,
"is_proxy": false,
"proxy_provider_names": [],
"proxy_confidence_score": 0,
"proxy_last_seen": "",
"proxy_days_seen_30d": 0,
"proxy_days_seen_7d": 0,
"proxy_provider_count_30d": 0,
"is_residential_proxy": false,
"is_vpn": false,
"vpn_provider_names": [],
"vpn_confidence_score": 0,
"vpn_last_seen": "",
"is_relay": false,
"relay_provider_name": "",
"is_anonymous": false,
"is_known_attacker": false,
"is_bot": false,
"is_spam": false,
"is_cloud_provider": true,
"cloud_provider_name": "DigitalOcean, LLC"
},
"abuse": {
"route": "165.227.0.0/16",
"country": "",
"name": "DigitalOcean Abuse",
"organization": "DigitalOcean Abuse",
"kind": "group",
"address": "105 Edgeview Drive, Suite 425, Broomfield, CO, 80021, United States",
"emails": [
"abuse@digitalocean.com"
],
"phone_numbers": [
"+1-646-827-4366"
]
},
"time_zone": {
"name": "America/Los_Angeles",
"offset": -8,
"offset_with_dst": -8,
"current_time": "2026-02-09 10:00:14.678-0800",
"current_time_unix": 1770660014.678,
"current_tz_abbreviation": "PST",
"current_tz_full_name": "Pacific Standard Time",
"standard_tz_abbreviation": "PST",
"standard_tz_full_name": "Pacific Standard Time",
"is_dst": false,
"dst_savings": 0,
"dst_exists": true,
"dst_tz_abbreviation": "PDT",
"dst_tz_full_name": "Pacific Daylight Time",
"dst_start": {
"utc_time": "2026-03-08 TIME 10:00",
"duration": "+1.00H",
"gap": true,
"date_time_after": "2026-03-08 TIME 03:00",
"date_time_before": "2026-03-08 TIME 02:00",
"overlap": false
},
"dst_end": {
"utc_time": "2026-11-01 TIME 09:00",
"duration": "-1.00H",
"gap": false,
"date_time_after": "2026-11-01 TIME 01:00",
"date_time_before": "2026-11-01 TIME 02:00",
"overlap": true
}
}
}Paid Plan Response with All Fields
You can include everything explicitly or use include=*.
# 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{
"ip": "165.227.0.0",
"hostname": "165.227.0.0",
"location": {
"continent_code": "NA",
"continent_name": "North America",
"country_code2": "US",
"country_code3": "USA",
"country_name": "United States",
"country_name_official": "United States of America",
"country_capital": "Washington, D.C.",
"state_prov": "California",
"state_code": "US-CA",
"district": "Santa Clara County",
"city": "Santa Clara",
"locality": "Santa Clara",
"accuracy_radius": "7.361",
"confidence": "medium",
"dma_code": "807",
"zipcode": "95051",
"latitude": "37.35983",
"longitude": "-121.98144",
"is_eu": false,
"country_flag": "https://ipgeolocation.io/static/flags/us_64.png",
"geoname_id": "5346804",
"country_emoji": "🇺🇸"
},
"country_metadata": {
"calling_code": "+1",
"tld": ".us",
"languages": [
"en-US",
"es-US",
"haw",
"fr"
]
},
"network": {
"connection_type": "",
"route": "165.227.0.0/20",
"is_anycast": false
},
"currency": {
"code": "USD",
"name": "US Dollar",
"symbol": "$"
},
"asn": {
"as_number": "AS14061",
"organization": "DigitalOcean, LLC",
"country": "US",
"type": "HOSTING",
"domain": "digitalocean.com",
"date_allocated": "2025-03-04",
"rir": "ARIN"
},
"company": {
"name": "DigitalOcean, LLC",
"type": "HOSTING",
"domain": "digitalocean.com"
},
"security": {
"threat_score": 5,
"is_tor": false,
"is_proxy": false,
"proxy_provider_names": [],
"proxy_confidence_score": 0,
"proxy_last_seen": "",
"proxy_days_seen_30d": 0,
"proxy_days_seen_7d": 0,
"proxy_provider_count_30d": 0,
"is_residential_proxy": false,
"is_vpn": false,
"vpn_provider_names": [],
"vpn_confidence_score": 0,
"vpn_last_seen": "",
"is_relay": false,
"relay_provider_name": "",
"is_anonymous": false,
"is_known_attacker": false,
"is_bot": false,
"is_spam": false,
"is_cloud_provider": true,
"cloud_provider_name": "DigitalOcean, LLC"
},
"abuse": {
"route": "165.227.0.0/16",
"country": "",
"name": "DigitalOcean Abuse",
"organization": "DigitalOcean Abuse",
"kind": "group",
"address": "105 Edgeview Drive, Suite 425, Broomfield, CO, 80021, United States",
"emails": [
"abuse@digitalocean.com"
],
"phone_numbers": [
"+1-646-827-4366"
]
},
"time_zone": {
"name": "America/Los_Angeles",
"offset": -8,
"offset_with_dst": -8,
"current_time": "2026-02-09 10:02:36.982-0800",
"current_time_unix": 1770660156.982,
"current_tz_abbreviation": "PST",
"current_tz_full_name": "Pacific Standard Time",
"standard_tz_abbreviation": "PST",
"standard_tz_full_name": "Pacific Standard Time",
"is_dst": false,
"dst_savings": 0,
"dst_exists": true,
"dst_tz_abbreviation": "PDT",
"dst_tz_full_name": "Pacific Daylight Time",
"dst_start": {
"utc_time": "2026-03-08 TIME 10:00",
"duration": "+1.00H",
"gap": true,
"date_time_after": "2026-03-08 TIME 03:00",
"date_time_before": "2026-03-08 TIME 02:00",
"overlap": false
},
"dst_end": {
"utc_time": "2026-11-01 TIME 09:00",
"duration": "-1.00H",
"gap": false,
"date_time_after": "2026-11-01 TIME 01:00",
"date_time_before": "2026-11-01 TIME 02:00",
"overlap": true
}
},
"user_agent": {
"user_agent_string": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/143.0.0.0 Safari/537.36",
"name": "Chrome",
"type": "Browser",
"version": "143",
"version_major": "143",
"device": {
"name": "Linux Desktop",
"type": "Desktop",
"brand": "Unknown",
"cpu": "Intel x86_64"
},
"engine": {
"name": "Blink",
"type": "Browser",
"version": "143",
"version_major": "143"
},
"operating_system": {
"name": "Linux",
"type": "Desktop",
"version": "??",
"version_major": "??",
"build": "??"
}
}
}