API reference

Look up an address with a GET request. Sections we know nothing about are left out of the body rather than returned empty, so check for a key before reading into it.

curl 'https://ip-api.dev/api?q=8.8.8.8&pretty=1&key=YOUR_KEY'

The v1 routes always return JSON and share the existing authentication and daily quota rules. Send your key as Authorization: Bearer, or use the legacy key query parameter. The web host also permits keyless reduced IP lookups; the accelerator host requires a key.

OpenAPI 3.1 contract · Full response JSON Schema · Error JSON Schema

Missing sections are omitted; unresolved fields within known sections are null. Clients should ignore additional fields. Additive fields are compatible within v1; removing a field or changing its type, meaning, or null behavior requires a new URL version. Any deprecation will be announced here with Deprecation and Sunset response headers before retirement. No endpoints are deprecated in this release, and the unversioned routes retain their existing behavior.

All v1 endpoints require an API key and stop at the daily per-key plan allowance. Legacy web routes retain their prepaid credit behavior. GET /v1/me reports the key ID, current plan, and quota scope, used, limit, remaining, UTC day, and reset epoch. It remains available at quota exhaustion and does not charge quota. Successful and 429 responses expose RateLimit-Limit, RateLimit-Remaining, and RateLimit-Reset (seconds until midnight UTC), plus X-RateLimit equivalents whose reset uses Unix epoch seconds. A 429 also returns Retry-After. Limits apply per key, matching the current metering.

Account metadata identifies its metering source and normal delay: database snapshots can lag resident requests by the 20-second flush; resident snapshots can lag externally metered requests by the 60-second reconciliation interval. New keys, revocations and plan changes normally reach the resident server within a 60-second poll plus a bounded 10-second read. If refreshes fail, resident keys expire after 120 seconds and requests fail closed. The web server checks keys directly in the database. Missing, malformed, unknown and revoked v1 keys return 401; valid exhausted keys return 429 on lookups. Query keys take precedence over Bearer tokens, and the Bearer scheme is case-insensitive.

Responses use Cache-Control: no-store, including self-IP results. Lite has a reserved schema in the contract and will be available in a later release; it is not an active endpoint.

GET https://ip-api.dev/api

Request the canonical /api endpoint and select its representation with the HTTP Accept header. If setting headers is inconvenient, use format; it takes precedence over Accept. With neither, the response is JSON. The format-specific paths remain convenient fixed aliases.

CSV, text and HTML flatten nested fields into dotted keys such as location.country, and arrays are joined with "; ", since an entry such as a phone number may hold spaces. TOON preserves the JSON structure and primitive types; uniform bulk arrays use its compact tabular form.

curl 'https://ip-api.dev/api?q=8.8.8.8'   -H 'Accept: text/toon'

curl 'https://ip-api.dev/api?q=8.8.8.8&format=toon'

ip,is_bogon,is_datacenter,is_anycast,is_tor,is_proxy,is_vpn,is_relay,is_anonymous,is_abuser,is_mobile,is_satellite,is_crawler,organization.name,asn.number,asn.name,location.country_code,location.latitude,location.longitude,elapsed_ms
8.8.8.8,false,true,false,false,false,false,false,false,false,false,false,false,Google LLC,15169,Google LLC,US,,,60.643

ip: 8.8.8.8
network:
  cidr: 8.8.8.0/24
  rir: arin
asn:
  number: 15169
  name: Google LLC
services: []
location:
  country_code: US
  precision: region
is_vpn: false
elapsed_ms: 1.234

Pass your key as the key query parameter. There is no header-based authentication.

• No key: 100 requests per UTC day, answered with the reduced response body described below. IPv4 callers are counted per address. IPv6 callers are counted per prefix, because a single subscriber holds many addresses: 100 per /64, 200 per /56, and 300 per /48.
• Free key: 1,000 requests per day and the full response body.
• Paid plans raise the monthly allowance — see pricing.
• The counter resets at 00:00 UTC. Going over returns 429.

POST to the same path with a JSON body to look up between 1 and 1,000 addresses at once. Bulk requires a key, always returns the full response body, and answers with an array in the order you sent.

curl -X POST 'https://ip-api.dev/api?key=YOUR_KEY&pretty=1' \
  -H 'Content-Type: application/json' \
  -d '{"ips": ["1.1.1.1", "8.8.8.8", "9.9.9.9"]}'

[
  { "ip": "1.1.1.1", "network": { "rir": "apnic", ... }, "asn": { ... }, "elapsed_ms": 61.2 },
  { "ip": "8.8.8.8", "network": { "rir": "arin", ... }, "asn": { ... }, "elapsed_ms": 58.9 },
  { "ip": "not-an-ip", "error": "Invalid IP Address or AS Number", "elapsed_ms": 0.01 }
]

Entries that are not valid addresses come back as an object with an error field instead of failing the whole request. AS numbers are not accepted in bulk bodies. Quota is charged up front for valid IP entries, including entries that fail or time out; invalid entries are free. Duplicate IPs count separately. Bodies are limited to 128 KiB (413 when exceeded) and each entry to 64 characters. You may also send one address per line with Content-Type: text/plain. Body reads have a 30-second timeout (408). Lookup processing has a separate 30-second deadline; unfinished entries return an error alongside completed results.

These are the fields in the full response body, returned when you send a key.

Top level

asn — routing

Omitted when no BGP route covers the address.

network — registry assignment

The most-specific whois network, or the broad RIR allocation as a fallback. Omitted only when neither is known.

connection — ISP and line

Omitted when nothing is known about the operator or the line.

organization — registered operator

Omitted when the registry network names no organization or domain.

abuse_contact

Omitted when the registry publishes no abuse email.

datacenter — hosting

Omitted when the address is not in a published cloud range and its AS is not classified as hosting.

anonymous — privacy classification

The full response always includes this object. Keyless responses include the aggregate is_anonymous and is_relay flags. Hosting alone does not imply anonymity. Existing top-level flags and services retain their meanings, including is_proxy for platform relays.

Matching service rows are ranked by confidence (enumerated, interpolated, assumed), then prefix specificity and presence of a provider name. Ties use source then provider name in ascending order. Tor takes precedence for anonymous.provider_name without suppressing the selected service flags.

VPN and Tor CSV downloads append the same privacy fields for each evidence row. They omit hosting status, which requires hosting and ASN data. When combining overlapping rows, apply the same service precedence and retain independent Tor evidence.

services — VPN, proxy and platform egress

One stable array covers all relay services. The kind enum distinguishes commercial VPNs, scanned proxies and platform egress such as iCloud Private Relay or Cloudflare WARP.

location — geolocation

Omitted when we cannot determine a country for the address.

Requests without a key get a strict subset of the same canonical structure. Field names and nesting never change between plans.

Pass an AS number as q to get the organization and every prefix the AS announces. The response shape is different from an address lookup.

{
  "asn": {
    "number": 13335,
    "name": "Cloudflare, Inc.",
    "domain": "cloudflare.com",
    "country_code": "US",
    "route": "1.0.0.0/24",
    "rir": "arin",
    "active": true
  },
  "prefixes": {
    "ipv4": ["1.0.0.0/24", "1.1.1.0/24", "..."],
    "ipv6": ["2400:cb00::/32", "..."]
  },
  "elapsed_ms": 412.8
}

prefixes.ipv4 and prefixes.ipv6 hold the announcements. An AS we know nothing about returns a 400.

Errors use the selected response format and always carry error and elapsed_ms. A negotiation error has no selected representation, so its explanatory body is JSON.

• Every response carries Access-Control-Allow-Origin: *, so you can call the API straight from a browser.
• OPTIONS preflight is answered with 200 and allows GET, POST, OPTIONS.
• Responses are sent with Cache-Control: no-store. Cache on your side if you need to.
• Negotiated /api responses include Vary: Accept, so compliant caches keep representations separate.

const response = await fetch(
  'https://ip-api.dev/api?q=8.8.8.8&key=YOUR_KEY',
)
const data = await response.json()

console.log(data.location?.country, data.asn?.name)
if (data.is_vpn || data.is_tor || data.is_abuser) {
  console.log('flagged:', data.ip)
}

import requests

response = requests.get(
    "https://ip-api.dev/api",
    params={"q": "8.8.8.8", "key": "YOUR_KEY"},
    timeout=10,
)
response.raise_for_status()
data = response.json()

print(data["asn"]["name"], data["location"]["country"])

Ready to go? Get a free key or browse the IP range explorer.