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.

2. Set it as an environment variable

export GEOQ_API_KEY="geoq_live_xxxxxxxxxxxx"

3. Make your first call

cURL JavaScript Python Go

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

const res = await fetch(
  "https://api.geoq.io/v1/check?ip=8.8.8.8",
  { headers: { Authorization: `Bearer ${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={"Authorization": f"Bearer {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("Authorization", "Bearer "+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"
  },
  "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"
}

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.

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