API reference

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

FieldTypeDescription
query_ip_addressstringThe IP address that was queried.
query_languagestringLanguage code used for place-name localisation.
citystringCity associated with the IP.
continentstringContinent name.
countrystringFull country name.
country_iso_codestringISO 3166-1 alpha-2 country code.
registered_country / registered_country_iso_codestringCountry the IP block is registered to, from the regional internet registries' delegated statistics. May differ from the geolocated country.
registrystringRegistry that delegated the block: afrinic, apnic, arin, lacnic or ripe.
subdivisionstringFirst-level subdivision (state, province, region).
subdivision_iso_codestringISO 3166-2 subdivision code. United States and United Kingdom addresses only.
latitude / longitudestringApproximate decimal coordinates of the city (returned as strings).
time_zonestringIANA time zone identifier for the city.

Country metadata

FieldTypeDescription
currencystringISO 4217 currency code for the country.
gmt_offsetintegerStandard (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_memberbooleanTrue if the country is an EU member state.
gdpr_requiredbooleanTrue when the visitor's country falls under GDPR.
languagesarrayLanguages for the country (code, name, native_name).

Network & ASN

FieldTypeDescription
asnstringAutonomous System Number ("ASxxxx").
asn_namestringName of the ASN operator.
asn_countrystringCountry registered to the ASN.
asn_typestringType of network operator: isp, hosting, business, education, government or mobile. IPv4 and IPv6.
org_domainstringBasic and above. Website domain of the network operator, when known. Optional — not every deployment returns it.
carrier_namestringBasic and above. Mobile carrier, when is_mobile is true and the carrier is known.
mobile_country_code / mobile_network_codestringBasic and above. The carrier's MCC and MNC, when known.
usage_typestringHow the address is used: satellite, mobile, hosting, education, business, or residential.
connection_typestringmobile / satellite / hosting / isp.
hostnamestringReverse-DNS (PTR) hostname. Present only when the request passes reverse=true.

Threat & classification flags

FieldTypeDescription
is_vpnbooleanIP is in a known VPN provider range.
is_proxybooleanTrue if is_vpn or is_tor_exit_node is true. proxy_type present when true.
is_tor_exit_node / is_tor_full_nodebooleanKnown Tor exit node / relay.
is_spam / is_spam_dropbooleanInside a netblock on the DROP list of hijacked/criminal netblocks (IPv4). spam_list present when true.
is_abuserbooleanOn a threat list we track: a known botnet command-and-control server, or the DROP list.
threat_sources / threat_last_seenarray / stringAdvanced and above. Which threat lists matched (feodo_tracker, drop_list) and when the address was last seen active.
is_cloudbooleanPublished cloud provider range. cloud_provider present when true.
is_datacenterbooleanDatacentre/hosting address (true when usage_type is hosting).
is_mobile / is_satellitebooleanMobile carrier / satellite ISP. connection_type present when true.
is_anycast / is_multicastbooleanAnycast address / multicast range.
is_crawlerbooleanIP or User-Agent matches a known crawler. crawler_name present when true.
is_bogonbooleanUnroutable/martian range (RFC 1122 / 6890, IPv4). bogon_type present when true.
simplemapsobjectNearest 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.

FieldTypeDescription
risk_scoreinteger0–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_levelstringBand: low (0–29), medium (30–64), high (65–100).
risk_factorsarrayAdvanced 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.

RuleDefault
tor, abuserblock
vpn, residential_proxy, datacenter, bot, disposable_emailchallenge
privacy_relayallow
risk_block_at / risk_challenge_at85 / 60
allow_countries / block_countriesempty (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 }

Next: errors, usage & quotas →