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

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`	string	Country where the IP block is registered.
`subdivision`	string	First-level subdivision (state, province, region).
`subdivision_iso_code`	string	ISO code for the subdivision.
`latitude` / `longitude`	string	Decimal coordinates (returned as strings).
`time_zone`	string	IANA time zone identifier.

Country metadata

Field	Type	Description
`currency`	string	ISO 4217 currency code for the country.
`gmt_offset`	integer	Standard UTC offset in seconds (excludes DST).
`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.
`ripe_country`	string	Country from the RIPE inetnum record (RIPE region IPs).
`netname`	string	Network name from the RIPE database.
`org` / `ripe_org_id`	string	Organisation name and RIPE organisation ID.
`network_status`	string	RIPE allocation/assignment status.
`usage_type`	string	How the address is used: `satellite`, `mobile`, `hosting`, `education`, `business`, or `residential`.
`connection_type`	string	`mobile` / `satellite` / `hosting` / `isp`.
`bgp_prefix` / `bgp_asn`	string / integer	Announced BGP prefix and origin AS (CAIDA RouteViews, IPv4). Omitted if not found.
`bgp_is_moas`	boolean	Prefix announced from multiple origin ASes (anycast/hijack signal).
`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	Listed on Spamhaus DROP/eDROP. `spam_list` present when true.
`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, Spamhaus DROP +50, bogon +40, VPN +30, Tor relay +30, cloud/datacentre +25/+20, crawler +15, anycast +10, BGP MOAS +5; mobile −10 and residential −5 as mitigations. Clamped to 0–100; a Tor-exit or Spamhaus-DROP hit floors it to 65.
`risk_level`	string	Band: `low` (0–29), `medium` (30–64), `high` (65–100).
`risk_factors`	array	The signal labels that contributed to the score (e.g. `["cloud_aws", "anycast"]`).

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 →