Docs

The /v1/check endpoint

GeoQ exposes a single endpoint. Everything — signals, geo, network and risk — comes back from one call.

GET https://api.geoq.io/v1/check

Query parameters

Parameter	Type	Required	Description
`ip`	string	No	IPv4 or IPv6 address to check. If omitted, GeoQ checks the caller's own source IP.
`format`	string	No	Set `?format=ipinfo` for an IPinfo-compatible response shape so an existing IPinfo client keeps parsing. See migration mode.

Headers

Header	Value
`x-api-key`	`<api_key>` — required (see auth).
`Accept`	`application/json` (default).

Examples

Check a specific IP:

$ curl "https://api.geoq.io/v1/check?ip=8.8.8.8" \
    -H "x-api-key: $GEOQ_API_KEY"

Check the caller's own IP (self-lookup):

$ curl "https://api.geoq.io/v1/check" \
    -H "x-api-key: $GEOQ_API_KEY"

An IPv6 address:

$ curl "https://api.geoq.io/v1/check?ip=2606:4700:4700::1111" \
    -H "x-api-key: $GEOQ_API_KEY"

IPv6 is fully supported: the datacenter, tor and verified_bot signals now cover IPv6 as well as IPv4, and geo/ASN always have.

Checking many IPs? POST /v1/check/batch looks up to 100 in one call — see the batch endpoint.

Response

A 200 OK returns the full payload. Each successful response also carries an evidence object describing how directly each signal is observed (authoritative / inferred / beta) — see the response schema for every field.

{
  "ip": "8.8.8.8",
  "version": 4,
  "geo": {
    "country": "United States",
    "country_code": "US",
    "region": "California",
    "city": "Mountain View",
    "latitude": 37.4,
    "longitude": -122.1,
    "timezone": "America/Los_Angeles"
  },
  "network": {
    "asn": 15169,
    "as_org": "Google LLC",
    "is_announced": true,
    "is_bogon": false,
    "rpki": "valid",
    "allocation_date": "2000-03-30",
    "allocation_age_days": 9566,
    "registration_country": "US"
  },
  "signals": {
    "connection_type": "datacenter",
    "datacenter_provider": "gcp",
    "relay_provider": null,
    "is_relay": false,
    "is_tor": false,
    "is_vpn": false,
    "is_proxy": false,
    "is_public_resolver": true,
    "is_drop_listed": false,
    "recent_abuse": false,
    "is_verified_bot": false,
    "verified_bot_name": null
  },
  "evidence": {
    "connection_type": "authoritative",
    "tor": "authoritative",
    "vpn": "inferred",
    "proxy": "beta",
    "verified_bot": "authoritative",
    "relay": "authoritative",
    "routing": "authoritative",
    "allocation": "authoritative",
    "drop_listed": "authoritative",
    "recent_abuse": "beta",
    "public_resolver": "authoritative"
  },
  "risk": {
    "score": 20,
    "level": "low",
    "reasons": [
      "connection_type:datacenter",
      "benign_network_kind"
    ]
  },
  "attribution": "https://geoq.io/attributions"
}

Status codes

Code	Meaning
`200`	Success — payload returned.
`400`	Invalid IP or malformed request.
`401`	Missing or invalid API key.
`429`	Daily quota / rate limit exceeded — see rate limits.
`5xx`	Server error — retry with backoff.

Full error format on the errors page.