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'

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 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_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,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 100 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.

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.

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.

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.