API reference

Endpoints, response formats and HTTP errors for single-IP lookups.

Endpoints

Base URLhttps://api.ipquery.ioNo API key

Caller’s IP

GET/Default: text/plain

Returns the address making the request. A browser fetch identifies the browser connection; a server-side fetch identifies the server.

Request

curl --fail --silent --show-error --max-time 5 \
  "https://api.ipquery.io/?format=json"

Single IP

GET/:ipDefault: application/json

Put one IPv4 or IPv6 address in the path. The result describes that address, regardless of the caller’s connection.

Request

curl --fail --silent --show-error --max-time 5 \
  "https://api.ipquery.io/1.1.1.1"

curl --fail --silent --show-error --max-time 5 \
  "https://api.ipquery.io/2606:4700:4700::1111"

Use HTTPS. Add ?format=json when your application needs a structured own-IP result.

Response formats

Set the format query value to choose the response representation.

JSON: ?format=jsonapplication/json
XML: ?format=xmlapplication/xml
YAML: ?format=yamlapplication/x-yaml
Text: ?format=texttext/plain

Text returns the address only. JSON, XML and YAML return the structured lookup.

Errors and bulk lookups

Check the HTTP status before reading a successful lookup. Error bodies follow a recognized format query; an omitted or unsupported format returns plain text.

Invalid address

HTTP 404

Check the address syntax. The path accepts one IPv4 or IPv6 address.

Request

curl -i "https://api.ipquery.io/not-an-ip?format=json"

HTTP 404

HTTP/1.1 404 Not Found
Content-Type: application/json

{"error":"IP address not-an-ip not found"}

Unsupported format

HTTP 400

Use json, xml, yaml or text. CSV is not an API response format.

Request

curl -i "https://api.ipquery.io/1.1.1.1?format=csv"

HTTP 400

HTTP/1.1 400 Bad Request
Content-Type: text/plain

Invalid format

Bulk lookup disabled

HTTP 400

Use the own-IP endpoint for a visitor, or request a single address. Retrying the same bulk request will not enable it.

Request

curl -i "https://api.ipquery.io/1.1.1.1,8.8.8.8?format=json"

HTTP 400

HTTP/1.1 400 Bad Request
Content-Type: application/json

{"error":"Bulk lookups are disabled due to abuse. For your own IP, embed fetch(\"https://api.ipquery.io/?format=json\") in your app, or use a single-IP lookup at https://api.ipquery.io/<ip>."}

Handle a failed request

Browser GET requests support cross-origin access. A network failure rejects fetch; an HTTP error still resolves to a response. Check response.ok before parsing JSON.

Check the HTTP status

const response = await fetch(
  "https://api.ipquery.io/1.1.1.1?format=json",
  { signal: AbortSignal.timeout(5000) }
);
if (!response.ok) {
  const message = await response.text();
  throw new Error("IPQuery " + response.status + ": " + message);
}
const data = await response.json();
console.log(data.ip);

Connection errors and server failures

A timeout or 5xx response is not an IP record. Keep an explicit unavailable state and use bounded retries. An upstream error body may be text or HTML, so do not assume every response contains JSON.

Missing source strings can be empty. A false flag is a non-match, not a safety verdict. Read the field definitions

Actual response

1.1.1.1

Live single-IP response

{
  "ip": "1.1.1.1",
  "isp": {
    "asn": "AS13335",
    "org": "Cloudflare, Inc.",
    "isp": "Cloudflare, Inc."
  },
  "location": {
    "country": "Australia",
    "country_code": "AU",
    "city": "Brisbane",
    "state": "Queensland",
    "zipcode": "",
    "latitude": -27.474848400186662,
    "longitude": 153.00996200912815,
    "timezone": "Australia/Brisbane",
    "localtime": "2026-11-02T19:06:21"
  },
  "risk": {
    "is_mobile": false,
    "is_vpn": false,
    "is_tor": false,
    "is_proxy": false,
    "is_datacenter": true,
    "risk_score": 20
  }
}