Docs

Quickstart

You'll make your first lookup in about two minutes. No credit card required.

1. Get an API key

Create a free account and copy your key from the dashboard. Free includes 1,000 lookups/day with every signal. A new key activates globally within about a minute, then works against the same api.geoq.io everywhere.

Get your free API key

2. Set it as an environment variable

export GEOQ_API_KEY="geoq_live_xxxxxxxxxxxx"

3. Make your first call

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

const res = await fetch(
  "https://api.geoq.io/v1/check?ip=8.8.8.8",
  { headers: { "x-api-key": process.env.GEOQ_API_KEY } }
);
const data = await res.json();
console.log(data.risk.score, data.risk.reasons);

import os, requests

r = requests.get(
    "https://api.geoq.io/v1/check",
    params={"ip": "8.8.8.8"},
    headers={"x-api-key": os.environ["GEOQ_API_KEY"]},
)
print(r.json()["risk"])

req, _ := http.NewRequest("GET",
    "https://api.geoq.io/v1/check?ip=8.8.8.8", nil)
req.Header.Set("x-api-key", os.Getenv("GEOQ_API_KEY"))
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

4. Read the response

You'll get JSON like this:

{
  "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"
}

5. Act on the risk score

The risk.score (0–100) and risk.level (low/medium/high) summarise every triggered signal. A common pattern:

if (data.risk.level === "high") {
  // step up: MFA, manual review, hold the order
} else if (data.risk.level === "medium") {
  // monitor / log
} else {
  // allow
}

Treat the score as one input. Don't make a sole-basis automated decision about a person — see the AUP.

Next

Read the full endpoint reference, the response schema, or grab an official SDK.