IP API - Chapybara

The IP API provides comprehensive IP address intelligence including geolocation, ISP information, security threat detection, proxy/VPN identification, and network details.

Authentication

All API requests require authentication. Include your API key in the request header:

X-API-Key: your_api_key_here

Production Endpoint

GET /api/v1/ip/{ip}

Parameters

Parameter	Type	Required	Description
`ip`	string	Yes	The IP address to analyze (IPv4 or IPv6).

Response Field Descriptions

The API returns a JSON object with the following structure:

Field	Type	Description
`ip`	string	The IP address that was analyzed.
`hostnames`	array	An array of hostnames resolved from a reverse DNS lookup.
`location`	object	Detailed geolocation information for the IP address.
`network`	object	Information about the network, ASN, and ISP.
`time_zone`	string	The IANA time zone name for the location (e.g., `America/Los_Angeles`).
`security`	object	Security analysis, including proxy, VPN, and threat detection.
`ads`	object	Advertising category information based on network type.
`metadata`	object	Information about the API request and data freshness.

`network.usage_type`

Describes the primary use of the network. Possible values:

Data Center: Hosted in a data center (e.g., AWS, Google Cloud).
Mobile: A mobile carrier network.
ISP: A residential or business Internet Service Provider.

`security.threat_level`

A summary of the security risk. Possible values:

high: Known malicious activity or Tor exit node.
medium: Known VPN or anonymizing service.
low: Public proxy or other potential risks.
none: No known threats detected.

Example Response

{
  "ip": "8.8.8.8",
  "hostnames": ["dns.google"],
  "location": {
    "continent": {"name": "North America", "code": "NA", "hemisphere": ["north", "west"]},
    "country": {"name": "United States", "code": "US", "capital": "Washington, D.C.", "..."},
    "region": {"name": "California", "code": "CA"},
    "city": {"name": "Mountain View"},
    "latitude": 37.4223,
    "longitude": -122.085,
    "accuracy_radius": 10
  },
  "network": {
    "asn": "15169",
    "organization": "GOOGLE",
    "isp": "Google LLC",
    "usage_type": "Data Center",
    "net_speed": "T1",
    "mobile": {"is_mobile": false, "mcc": null, "mnc": null, "brand": null},
    "registration_date": "2000-03-30T00:00:00.000Z"
  },
  "time_zone": "America/Los_Angeles",
  "security": {
    "is_proxy": false,
    "proxy_type": null,
    "is_tor": false,
    "is_vpn": false,
    "is_datacenter": true,
    "is_spammer": false,
    "threat_level": "none"
  },
  "ads": {
    "category_code": "IAB19-18",
    "category_name": "Internet Technology"
  },
  "metadata": {
    "data_freshness": {"last_update_check": "2025-08-16T20:35:36.365Z"},
    "timestamp": "2025-08-16T20:36:23.695Z",
    "response_time_ms": 323,
    "request_id": "req_1755376583087_8678fd87"
  }
}

Examples

cURL (IPv4)

curl -X GET "https://api.chapyapi.com/api/v1/ip/8.8.8.8" \
  -H "X-API-Key: your_api_key_here"

JavaScript (IPv6)

const response = await fetch('https://api.chapyapi.com/api/v1/ip/2001:4860:4860::8888', {
  headers: {
    'X-API-Key': 'your_api_key_here'
  }
});
const data = await response.json();
console.log(data);

Python

import requests

url = "https://api.chapyapi.com/api/v1/ip/8.8.8.8"
headers = {"X-API-Key": "your_api_key_here"}

response = requests.get(url, headers=headers)
data = response.json()
print(data)

Error Handling

The API uses standard HTTP status codes and returns error details in JSON format.

Status Code	Error Code	Description
400	`VALIDATION_ERROR`	Invalid IP address format.
401	`MISSING_API_KEY`	API key not provided.
401	`INVALID_API_KEY`	API key is invalid, inactive, or expired.
402	`QUOTA_EXCEEDED`	Your daily IP request quota has been reached.
403	`ENDPOINT_FORBIDDEN`	Your API key is not permitted to access this endpoint.
429	`RATE_LIMIT_EXCEEDED`	Too many requests. Check `X-RateLimit-Reset` header.
503	`SERVICE_INITIALIZING`	The service is starting up. Please try again shortly.
503	`SERVICE_ERROR`	A downstream service (e.g., geolocation DB) failed.

Error Response Example

{
  "error": "Invalid IP address format",
  "code": "VALIDATION_ERROR",
  "requestId": "req_1755376583087_8678fd87"
}