Response fields
A successful query returns a JSON array with one object per IP. Fields are present only when they could be resolved for the address; pass fields to return only the values your workflow needs. Geolocation is DB-IP IP to City Lite (CC BY 4.0) — credit “IP Geolocation by DB-IP” if you display it publicly.
Geolocation
| Field | Type | Description |
|---|---|---|
query_ip_address | string | The IP address that was queried. |
query_language | string | Language code used for place-name localisation. |
city | string | City associated with the IP. |
continent | string | Continent name. |
country | string | Full country name. |
country_iso_code | string | ISO 3166-1 alpha-2 country code. |
registered_country / registered_country_iso_code | string | Country the IP block is registered to, from the regional internet registries' delegated statistics. May differ from the geolocated country. |
registry | string | Registry that delegated the block: afrinic, apnic, arin, lacnic or ripe. |
subdivision | string | First-level subdivision (state, province, region). |
subdivision_iso_code | string | ISO 3166-2 subdivision code. United States and United Kingdom addresses only. |
latitude / longitude | string | Approximate decimal coordinates of the city (returned as strings). |
time_zone | string | IANA time zone identifier for the city. |
Country metadata
| Field | Type | Description |
|---|---|---|
currency | string | ISO 4217 currency code for the country. |
gmt_offset | integer | Standard (non-DST) UTC offset in seconds, evaluated at response generation using the host's IANA tzdata for time_zone. Not the seasonal wall-clock offset; omitted if zone data is unavailable. |
is_eu_member | boolean | True if the country is an EU member state. |
gdpr_required | boolean | True when the visitor's country falls under GDPR. |
languages | array | Languages for the country (code, name, native_name). |
Network & ASN
| Field | Type | Description |
|---|---|---|
asn | string | Autonomous System Number ("ASxxxx"). |
asn_name | string | Name of the ASN operator. |
asn_country | string | Country registered to the ASN. |
asn_type | string | Type of network operator: isp, hosting, business, education, government or mobile. IPv4 and IPv6. |
org_domain | string | Basic and above. Website domain of the network operator, when known. Optional — not every deployment returns it. |
carrier_name | string | Basic and above. Mobile carrier, when is_mobile is true and the carrier is known. |
mobile_country_code / mobile_network_code | string | Basic and above. The carrier's MCC and MNC, when known. |
usage_type | string | How the address is used: satellite, mobile, hosting, education, business, or residential. |
connection_type | string | mobile / satellite / hosting / isp. |
hostname | string | Reverse-DNS (PTR) hostname. Present only when the request passes reverse=true. |
Threat & classification flags
| Field | Type | Description |
|---|---|---|
is_vpn | boolean | IP is in a known VPN provider range. |
is_proxy | boolean | True if is_vpn or is_tor_exit_node is true. proxy_type present when true. |
is_tor_exit_node / is_tor_full_node | boolean | Known Tor exit node / relay. |
is_spam / is_spam_drop | boolean | Inside a netblock on the DROP list of hijacked/criminal netblocks (IPv4). spam_list present when true. |
is_abuser | boolean | On a threat list we track: a known botnet command-and-control server, or the DROP list. |
threat_sources / threat_last_seen | array / string | Advanced and above. Which threat lists matched (feodo_tracker, drop_list) and when the address was last seen active. |
is_cloud | boolean | Published cloud provider range. cloud_provider present when true. |
is_datacenter | boolean | Datacentre/hosting address (true when usage_type is hosting). |
is_mobile / is_satellite | boolean | Mobile carrier / satellite ISP. connection_type present when true. |
is_anycast / is_multicast | boolean | Anycast address / multicast range. |
is_crawler | boolean | IP or User-Agent matches a known crawler. crawler_name present when true. |
is_bogon | boolean | Unroutable/martian range (RFC 1122 / 6890, IPv4). bogon_type present when true. |
simplemaps | object | Nearest populated place (city, admin_name, country, iso2, iso3, capital, population). |
Risk score
Every result carries a packaged fraud/abuse score derived transparently from the flags above — a single number to gate on instead of hand-rolling your own rule set.
| Field | Type | Description |
|---|---|---|
risk_score | integer | 0–100. Additive rubric: Tor exit +55, DROP list +50 (drop_list), botnet C2 server +50 (botnet_c2), residential proxy (confidence ≥ 70) +45, bogon +40, VPN +30, Tor relay +30, cloud/datacentre +25/+20, crawler +15, anycast +10; mobile −10 and residential −5 as mitigations. Clamped to 0–100; a Tor-exit, DROP-list or botnet-C2 hit floors it to 65. Privacy relays are capped at 20 unless independently known-bad. |
risk_level | string | Band: low (0–29), medium (30–64), high (65–100). |
risk_factors | array | Advanced and above. The signal labels that contributed to the score (e.g. ["cloud_aws", "anycast"] or ["drop_list"]). |
Other endpoints
Every response, on every endpoint, carries an X-IpQuery-Data-Version header: the date of the oldest core dataset (geolocation, ASN, registry) currently loaded.
GET /api/asn/{asn}
Profile of an autonomous system. Pass 15169 or AS15169. One request unit; every plan.
{ "asn": 15169, "name": "GOOGLE", "country": "US", "registry": "arin",
"allocated": "2000-03-30", "type": "hosting", "is_hosting": true, "is_announced": true,
"prefix_count_v4": 1000, "prefix_count_v6": 120,
"prefixes_v4": ["8.8.8.0/24", "…"], "prefixes_v6": ["2001:4860::/32", "…"],
"prefixes_truncated": true, "request_id": "…" }
Each prefix list is capped at 1,000 entries; prefixes_truncated is true when a list was capped. Errors: 400 invalid_asn, 404 not_found.
GET /api/prefix?cidr=
The announced prefix that covers a CIDR (or a single IP), IPv4 or IPv6. One request unit; every plan.
{ "query": "8.8.8.0/24", "prefix": "8.8.8.0/24", "range": "8.8.8.0 - 8.8.8.255",
"asn": 15169, "asn_name": "GOOGLE", "country": "US", "registry": "arin",
"asn_type": "hosting", "is_cloud": true, "cloud_provider": "GCP",
"is_hosting_range": true, "is_anycast": true, "is_bogon": false, "request_id": "…" }
Errors: 400 invalid_prefix, 404 not_found (not announced on the public internet).
POST /api/assess
A decision endpoint for signup, checkout and login. Advanced and Business plans, and every account's first 15 days; one request unit. Send a JSON body with ip (defaults to the caller), and optionally user_agent, email (only the domain is checked against a disposable-email list; never stored) and rules.
| Rule | Default |
|---|---|
tor, abuser | block |
vpn, residential_proxy, datacenter, bot, disposable_email | challenge |
privacy_relay | allow |
risk_block_at / risk_challenge_at | 85 / 60 |
allow_countries / block_countries | empty (all countries allowed) |
Each rule takes allow, challenge or block. Omitted rules fall back to the rules saved on the key, then to the defaults. The strongest outcome wins (block > challenge > allow).
{ "decision": "challenge", "reasons": ["vpn", "risk_score"], "risk_score": 62,
"risk_level": "medium", "ip": "203.0.113.7", "country_iso_code": "GB", "asn": 9009,
"vpn_name": "NordVPN", "is_tor_exit_node": false, "is_vpn": true,
"is_residential_proxy": false, "is_privacy_relay": false, "is_datacenter": true,
"is_abuser": false, "is_bot": false, "email_disposable": false, "request_id": "…" }
Errors: 403 plan_required on Free and Basic keys, 400 invalid_request_body / invalid_ip, 413 for bodies over 16 KiB.
GET /api/meta
The datasets behind the API — source, licence, refresh cadence and last update — plus api_version and data_version. No API key needed and not metered.
Registration data (whois=true)
Reserved. whois=true currently answers 403 feature_unavailable.
Record-Only responses
When a key has the Record-Only (statsOnly) option enabled, the response is an acknowledgement instead of the result array:
{ "code": 200, "msg": "Recorded statistics successfully.", "request_count": 1 }