IP lookup API documentation

Endpoints accept GET requests and return JSON. Example addresses demonstrate the request format; actual results come from the response.

GET /api/check/lookup

curl 'https://ipcheak.com/api/check/lookup?ip=8.8.8.8'

The optional ip parameter accepts one public IPv4 or IPv6 address. Omitting it resolves the caller’s public exit. A server-side call observes your server, not the end user’s browser. Private and reserved addresses and repeated ip parameters are rejected.

Field	Meaning
`ip, ipVersion, source`	Queried address, IP version (4 or 6), and how the address was obtained.
`requestId, observedAt`	Request identifier and ISO 8601 observation time.
`network`	asn, name, domain, type, prefix, registeredCountry, and asnHistory. Some fields may be null.
`geo`	Country, region, city, time zone, and approximate coordinates; unavailable coordinates are null.
`signals`	proxy, vpn, tor, hosting, and residentialProxy, each using low / medium / high / unknown.
`confidence, providers`	Overall evidence confidence plus each source’s status, observation time, and fields.
`risk_score, risk_level, riskAnalysis`	Risk score (nullable), band, and component evidence. These are not anonymity or safety guarantees.

GET /api/v1/ip/self

curl 'https://ipcheak.com/api/v1/ip/self'

Returns a compact view of the caller’s exit: requestId, observedAt, ip, version, network, geo, signals, confidence, and providers. This endpoint uses version and omits the full lookup endpoint’s riskAnalysis.

Call from your server

const response = await fetch(
  'https://ipcheak.com/api/check/lookup?ip=8.8.8.8'
)
if (response.status === 429 || response.status === 503) {
  const seconds = response.headers.get('Retry-After')
  throw new Error(`Retry after ${seconds || '30'} seconds`)
}
if (!response.ok) throw new Error(`HTTP ${response.status}`)
const result = await response.json()
console.log(result.ip, result.network.asn, result.signals.vpn)

Neither endpoint enables cross-origin browser access. Handle non-2xx responses, timeouts, missing fields, and upstream rate limits. Do not convert unknown to false.

Rate limits and quotas

By default, a caller shares 10 requests per 60 seconds and 100 per 24 hours across expensive endpoints, including lookup, self, and expensive scan/diagnostic steps. All API routes also share caller limits of 120 per minute and 2,000 per day. IPv6 addresses are grouped by /64; changing the queried IP does not reset the quota. Windows start with the first request. Deployment settings may change these defaults.

Queries also have site-wide budgets and concurrency caps. Any exhausted quota returns 429; capacity or quota-backend failures return 503. Wait the seconds specified in Retry-After; do not retry immediately or in parallel. On successful responses, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset describe the caller’s minute window, not remaining site-wide capacity. Cache hits count toward caller quotas but do not spend another upstream lookup unit.

Errors and signal semantics

400 — Repeated ip parameter; only one address is accepted.
422 — Invalid or non-public address, or no usable public exit could be resolved.
413 — Request body exceeds 16 KiB.
429 — Rate or quota exceeded; wait for Retry-After.
503 — Service busy or quota backend unavailable; wait for Retry-After.
5xx — Request processing failed; use bounded retries.

high indicates a positive source flag; medium indicates conflicting sources; low means available sources did not flag the address; unknown means no usable signal. An HTTP 200 response can still contain timed-out, rate-limited, or unavailable sources. Inspect providers[].status.