Response format · ipscope Docs

Every lookup endpoint returns UTF-8 JSON (application/json; charset=utf-8). Top-level metadata fields (ip, ip_version, matched_network, dataset_version, updated_at) sit alongside nested objects for each intelligence block (geo, network, connection, security, security_extensions).

# A complete lookup response

A lookup on a plan with all 6 intelligence blocks enabled returns:

200 OK

{
  "ip": "198.51.100.7",
  "ip_version": 4,
  "matched_network": "198.51.100.0/24",
  "geo": {
    "country_code": "US",
    "declared_country_code": "US",
    "physical_country_code": "US",
    "is_virtual_location": false,
    "location_type": "physical",
    "confidence": 0.94,
    "subdivision": "Virginia",
    "city": "Ashburn",
    "postal_code": "20147",
    "latitude": 39.0438,
    "longitude": -77.4874,
    "accuracy_radius_km": 10,
    "timezone": "America/New_York"
  },
  "network": {
    "asn": 64501,
    "organization": "Example Cloud LLC"
  },
  "connection": {
    "connection_type": "hosting",
    "is_hosting": true,
    "is_residential": false,
    "is_mobile": false,
    "is_business": false
  },
  "security": {
    "is_vpn": true,
    "is_hosting": true,
    "is_tor_exit": false,
    "is_proxy": false,
    "anonymizer_type": "vpn",
    "confidence": 0.96,
    "reason_codes": [
      "vpn_handshake_confirmed",
      "datacenter_asn_range"
    ]
  },
  "security_extensions": {
    "abuse_velocity_score": 18,
    "is_known_scanner": false,
    "observation_recency_hours": 12,
    "anonymizer_reason": "vpn_handshake_confirmed",
    "threat_level": "medium",
    "abuse_velocity": "low",
    "confidence": 0.96
  },
  "dataset_version": "2026-10-27T00:00:00Z.crawl-1793088000000",
  "updated_at": "2026-10-27T00:00:00Z"
}

# Mapping intelligence blocks to JSON objects

Field family (`field_families`)	JSON object key	Included attributes
`geo_country`	`geo`	`country_code`, `declared_country_code`, `physical_country_code`, `is_virtual_location`, `location_type`, `confidence`
`geo_city`	`geo`	`subdivision`, `city`, `postal_code`, `latitude`, `longitude`, `accuracy_radius_km`, `timezone`
`network`	`network`	`asn`, `organization`
`connection`	`connection`	`connection_type`, `is_hosting`, `is_residential`, `is_mobile`, `is_business`
`anonymity`	`security`	`is_vpn`, `is_hosting`, `is_tor_exit`, `is_proxy`, `anonymizer_type`, `confidence`
`security_extensions`	`security_extensions`	`anonymizer_reason`, `threat_level`, `abuse_velocity`, `confidence`

# Nullability and unknown values

Unknown values are null, never empty strings: if an anycast prefix has no postal code, postal_code is null, never "" or "N/A".
Booleans are always true or false: is_vpn, is_tor_exit, is_proxy, is_hosting, and is_virtual_location are never null when their object is present.
Confidence scores are calibrated floats in [0.0, 1.0]: both geo.confidence and security.confidence quantify the agreement across RIR, BGP, RPKI, geofeed, and active measurement evidence.

# Response headers

Header	Example	Meaning
`X-Request-Id`	`req_01J8Z4K9X2`	Unique identifier for this request; include it when contacting support.
`X-RateLimit-Limit`	`500000`	Monthly lookup allowance for the active plan.
`X-RateLimit-Remaining`	`412890`	Remaining monthly lookups before prepaid wallet fallback or quota stop.
`X-RateLimit-Reset`	`1735689600`	Unix timestamp (UTC seconds) when the monthly counter resets.
`X-Dataset-Version`	`2026-10-27T00:00:00Z.crawl-1793088000000`	Active IP intelligence snapshot serving this lookup.

# Stability guarantee

Within /v1, existing fields are never renamed, removed, or given a different type. New optional fields may be added to an object in minor releases; configure your JSON deserializer to ignore unknown keys (all official IPScope SDKs do this automatically).