Response Schema

Complete Response Example

IPBot returns a single JSON object with the following structure:

{
  "ip": "8.8.8.8",
  "location": {
    "country": "United States",
    "country_code": "US",
    "region": "California",
    "city": "Mountain View",
    "postal": "94043",
    "latitude": 37.422,
    "longitude": -122.084,
    "timezone": "-07:00"
  },
  "network": {
    "asn": "AS15169",
    "org": "Google LLC",
    "radar": null
  },
  "security": {
    "risk_score": 75,
    "risk_reasons": ["ASN_RULE:datacenter_keywords", "THREAT_LIST:tor"],
    "usage_type": "DCH",
    "is_datacenter": true,
    "is_proxy": true,
    "threat_level": "High",
    "threat_lists": ["tor"]
  },
  "telemetry": {
    "user_agent": "curl/8.0",
    "is_browser": false
  },
  "meta": {
    "process_time_us": 450,
    "data_version": "2026-01-04",
    "engine": "IPBot/1.1"
  }
}

Root Fields

Field	Type	Description
ip	string	The queried IP address
location	object	Geographic location information
network	object	Network and ASN information
security	object	Risk assessment and threat intelligence
telemetry	object	Request metadata (user agent, etc)
meta	object	API response metadata

Location Object

Field	Type	Description
country	string	Full country name
country_code	string	ISO 3166-1 alpha-2 country code (e.g., “US”, “GB”, “JP”)
region	string	State, province, or region name
city	string	City name
postal	string	Postal/ZIP code
latitude	float	Approximate latitude (decimal degrees)
longitude	float	Approximate longitude (decimal degrees)
timezone	string	UTC offset in format +/-HH:MM

Location Example

{
  "location": {
    "country": "Germany",
    "country_code": "DE",
    "region": "Bavaria",
    "city": "Munich",
    "postal": "80331",
    "latitude": 48.1351,
    "longitude": 11.582,
    "timezone": "+01:00"
  }
}

Network Object

Field	Type	Description
asn	string	Autonomous System Number (e.g., “AS15169”)
org	string	Organization name associated with the ASN
radar	string or null	Usage classification from ipbot-radar: isp, datacenter, mobile, vpn, proxy, tor, or null

Network Object Notes

• network.radar is cache-first and may be null on cache miss
• Radar classifications are determined by analyzing AS name, organization, and known ranges
• When null, the IP has not been classified yet (cold cache)

Network Example

{
  "network": {
    "asn": "AS16509",
    "org": "Amazon.com, Inc.",
    "radar": "datacenter"
  }
}

Security Object

Field	Type	Description
risk_score	integer	Overall risk score from 0-100 (higher = more risky)
risk_reasons	array	List of reasons contributing to the risk score
usage_type	string	IP2Location usage classification (see table below)
is_datacenter	boolean	True if IP is from a known datacenter/ISP hosting range
is_proxy	boolean	True if IP matches known proxy/VPN services
threat_level	string	Human-readable threat level: Low, Medium, High
threat_lists	array	Names of threat lists this IP appears on

Risk Score Interpretation

Score Range	Risk Level	Recommended Action
0-20	Low	Allow
21-50	Low-Medium	Monitor
51-75	Medium-High	Additional verification recommended
76-100	High	Block or require strong authentication

Usage Types

Code	Description
ISP	Internet Service Provider
COM	Commercial
ORG	Organization
RES	Residential
GOV	Government
MIL	Military
EDU	Educational Institution
LIB	Library
CDN	Content Delivery Network
ISP	Fixed Line ISP
MOB	Mobile ISP
DCH	Data Center/Web Hosting/Transit
SES	Search Engine Spider
RSG	Reserved
IOT	IoT

Security Example (Low Risk)

{
  "security": {
    "risk_score": 10,
    "risk_reasons": [],
    "usage_type": "RES",
    "is_datacenter": false,
    "is_proxy": false,
    "threat_level": "Low",
    "threat_lists": []
  }
}

Security Example (High Risk)

{
  "security": {
    "risk_score": 85,
    "risk_reasons": [
      "ASN_RULE:datacenter_keywords",
      "THREAT_LIST:tor",
      "IP2LOCATION:proxy"
    ],
    "usage_type": "DCH",
    "is_datacenter": true,
    "is_proxy": true,
    "threat_level": "High",
    "threat_lists": ["tor", "proxies"]
  }
}

Risk Reason Codes

Risk reasons follow a SOURCE:detail format:

Prefix	Source
ASN_RULE	Organization name-based rules
THREAT_LIST	Custom threat intelligence
IP2LOCATION	IP2Location database flags
RADAR	ipbot-radar classification

Telemetry Object

Field	Type	Description
user_agent	string	The User-Agent header from the request
is_browser	boolean	True if the request appears to be from a browser

Telemetry Example

{
  "telemetry": {
    "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36",
    "is_browser": true
  }
}

Meta Object

Field	Type	Description
process_time_us	integer	Request processing time in microseconds
data_version	string	Database version identifier (YYYY-MM-DD)
engine	string	API engine version identifier

Meta Example

{
  "meta": {
    "process_time_us": 1250,
    "data_version": "2026-01-04",
    "engine": "IPBot/1.1"
  }
}

TypeScript Interface

For TypeScript users, here’s the interface definition:

interface IPBotResponse {
  ip: string;
  location: {
    country: string;
    country_code: string;
    region: string;
    city: string;
    postal: string;
    latitude: number;
    longitude: number;
    timezone: string;
  };
  network: {
    asn: string;
    org: string;
    radar: "isp" | "datacenter" | "mobile" | "vpn" | "proxy" | "tor" | null;
  };
  security: {
    risk_score: number;
    risk_reasons: string[];
    usage_type: string;
    is_datacenter: boolean;
    is_proxy: boolean;
    threat_level: "Low" | "Medium" | "High";
    threat_lists: string[];
  };
  telemetry: {
    user_agent: string;
    is_browser: boolean;
  };
  meta: {
    process_time_us: number;
    data_version: string;
    engine: string;
  };
}