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.

Headers

Header	Value
`Authorization`	`Bearer <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 "Authorization: Bearer $GEOQ_API_KEY"

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

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

An IPv6 address:

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

Response

A 200 OK returns the full payload. 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"
  },
  "signals": {
    "is_datacenter": true,
    "datacenter_provider": "gcp",
    "is_tor": false,
    "is_vpn": false,
    "is_proxy": false,
    "is_bot": false
  },
  "risk": {
    "score": 35,
    "level": "medium",
    "reasons": [
      "is_datacenter"
    ]
  },
  "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.