---
name: ip-lookup
description: Look up IP geolocation, ASN ownership, and network threat intelligence (VPN, datacenter, bogon) for any IPv4 or IPv6 address using the theipapi.com REST API.
---

# IP Lookup (theipapi.com)

Use this skill to resolve an IP address or Autonomous System Number (ASN) to
geolocation, network ownership, and threat-intelligence data through the
theipapi.com REST API.

## When to use

- A user gives you an IP address and asks where it is, who owns it, or whether
  it is a VPN / datacenter / reserved (bogon) address.
- You need the ASN, network operator, or routing prefix for an IP.
- You need registration and organization details for an ASN.
- You need to enrich many IP addresses at once (up to 100 per request).

## Authentication

Every request requires an API key passed as the `api_key` query parameter:

    ?api_key=YOUR_API_KEY

Get a key by signing up at https://theipapi.com/signup and confirming your
email. The free plan allows 1,000 requests per day.

Read the key from the `THEIPAPI_API_KEY` environment variable. If it is not
set, ask the user to set it. Never ask the user to paste the key into chat, and
never print, log, or commit it.

## Endpoints

### 1. IP geolocation

    GET https://api.theipapi.com/v1/ip/{ip}?api_key=YOUR_API_KEY

```
curl "https://api.theipapi.com/v1/ip/8.8.8.8?api_key=${THEIPAPI_API_KEY}"
```

Returns `location` (city, country, country_code, latitude, longitude, region,
timezone), `asn` (asn, asn_description, org_name, network, rir, created,
updated), `company` (name, address, network, route), and the boolean threat
flags `is_bogon`, `is_datacenter`, `is_vpn`. Supports IPv4 and IPv6. A bogon IP
returns only `ip` and `is_bogon`.

### 2. ASN lookup

    GET https://api.theipapi.com/v1/asn/{asn}?api_key=YOUR_API_KEY

```
curl "https://api.theipapi.com/v1/asn/15169?api_key=${THEIPAPI_API_KEY}"
```

Returns registration and organization details for the Autonomous System Number.

### 3. Batch IP geolocation

    POST https://api.theipapi.com/v1/ip/batch?api_key=YOUR_API_KEY

```
curl -X POST "https://api.theipapi.com/v1/ip/batch?api_key=${THEIPAPI_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"ips": ["8.8.8.8", "1.1.1.1"]}'
```

Look up up to 100 IPs in one request. The response contains a `results` object
keyed by IP address, with each value matching the single-IP response shape. It
also includes `status`, `total_ips`, and `response_time_ms` at the top level.
Duplicate IPs are deduplicated and counted once. The quota check is
all-or-nothing: if there is not enough quota for every unique IP, the whole
batch is rejected with HTTP 429. Individual IP failures return per-IP errors
while other IPs succeed.

## Response shape

Successful responses wrap the payload:

```json
{
  "status": "OK",
  "body": { "ip": "8.8.8.8", "location": { ... }, "asn": { ... }, "...": "..." },
  "response_time_ms": 10
}
```

Most errors return an HTTP error status and a JSON body:

```json
{ "status": "Error", "error": "Invalid API Key" }
```

A single-IP lookup with no matching record can return HTTP `200` with
`"status": "Error"`, so always check the JSON `status` field before using
`body`.

Status codes: `200` success or a single-IP lookup with no matching record,
`400` bad request (invalid ASN/JSON, too many IPs, or an invalid IP in a batch),
`401` missing or invalid API key, `404` ASN not found, `405` method not allowed,
`429` rate limit exceeded, `500` server error.

## Rate limits

The free plan is 1,000 requests/day (resets daily). Paid plans start at
$19/month for 600,000 requests/month. Each unique IP in a batch counts as one
request. On quota exhaustion the API returns HTTP 429.

## Links

- Documentation: https://theipapi.com/documentation
- Pricing: https://theipapi.com/pricing
- AI-crawler summary: https://theipapi.com/llms.txt
- API catalog (RFC 9727): https://theipapi.com/.well-known/api-catalog