API Documentation

Detailed reference for /api with Bearer auth, error codes, and antifraud integration.

What's New In Current API Version

Endpoint

Request Parameters

Field Filter Rules

Authorization (Bearer)

Authorization: Bearer YOUR_API_KEY

API key in query string is not used. Send key only in Bearer header.

user_id for Antifraud

`user_id` is required because antifraud correlates activity by account/device identity over time. It can be internal user ID, hashed email, payment account ID, or anonymous cookie-based ID.

Cookie-based user_id (without PHP session)

// Browser JS example
function getOrCreateUserId() {
  const key = 'gid_uid';
  const found = document.cookie.split('; ').find(v => v.startsWith(key + '='));
  if (found) return decodeURIComponent(found.split('=')[1]);

  const uid = 'anon_' + crypto.randomUUID().replace(/-/g, '').slice(0, 16);
  document.cookie = `${key}=${encodeURIComponent(uid)}; Max-Age=31536000; Path=/; SameSite=Lax`;
  return uid;
}

Success Response (geo plan)

{
  "status": "ok",
  "error_code": 0,
  "http_status": 200,
  "ip": "8.8.8.8",
  "ua": "Mozilla/5.0 ...",
  "user_id": "usr_15293",
  "subscription_type": "geo",
  "geo": {
    "city": {"name": "Mountain View", "geoname_id": 5375480},
    "country": {"iso_code": "US", "name": "United States", "geoname_id": 6252001},
    "location": {"latitude": 37.4056, "longitude": -122.0775, "accuracy_radius": 1000},
    "timezone": "America/Los_Angeles",
    "postal": "94043",
    "country_enrichment": {
      "phone_code": "+1",
      "tld": ".us",
      "languages": [{"code":"en","name":"English"}],
      "currencies": [{"code":"USD","name":"United States dollar","symbol":"$"}],
      "rates": {
        "currency_code": "USD",
        "units_per_usd": 1,
        "usd_per_unit": 1,
        "crypto": {
          "BTC": {"units_per_coin": 97000, "coin_per_unit": 0.0000103, "usd_per_coin": 97000, "coin_per_usd": 0.0000103}
        }
      }
    },
    "geo_intelligence": {
      "is_eu": false,
      "is_schengen": false
    }
  }
}

Success Response (antifraud plan)

{
  "status": "ok",
  "error_code": 0,
  "http_status": 200,
  "subscription_type": "antifraud",
  "geo": {...},
  "asn": {"asn": 15169, "org": "Google LLC", "network_type": "ISP"},
  "ptr": "dns.google",
  "antifraud": {
    "risk_score": 42,
    "proxy_suspected": false,
    "confidence": 0.7,
    "signals": ["ASN:heuristic"],
    "behavior": {
      "acc_country_switch": 2,
      "dev_asn_switch": 3
    },
    "advanced_insights": {
      "distance_to_historical_user_centroid_km": 18.4,
      "distance_to_historical_user_centroid_note": "ok",
      "location_stability_score": 86,
      "impossible_travel": {
        "is_detected": false,
        "distance_km": 35.7,
        "elapsed_minutes": 52.3,
        "speed_kmh": 41.0,
        "note": "speed_within_plausible_range"
      },
      "business_hours_mismatch": {
        "current_hour_utc": 12,
        "historical_avg_hour_utc": 11.6,
        "hour_delta": 0.4,
        "is_mismatch": false
      },
      "country_risk_profile": {
        "country_iso2": "US",
        "fraud_pressure_score": 31,
        "chargeback_risk_bucket": "low",
        "sanctions_flag": false
      },
      "asn_reputation": {
        "asn": 15169,
        "risk_score": 9,
        "network_type": "ISP",
        "reputation_tier": "trusted"
      },
      "network_change_anomaly": {
        "primary_asn": 15169,
        "current_asn": 15169,
        "is_anomaly": false,
        "asn_variants_recent": 1
      },
      "geo_consistency_with_profile": {
        "primary_country": "US",
        "current_country": "US",
        "match": true,
        "confidence": 0.92
      },
      "travel_context": {
        "status": "normal",
        "summary": "Current request aligns with recent mobility pattern"
      },
      "ip_quality_index": 82,
      "region_precision_level": "city_level",
      "smart_action_hint": "allow",
      "source_signals": ["ASN:heuristic"]
    }
  }
}

Response Field Catalog (Paths)

Error Response Format

{
  "status": "error",
  "error_code": 1005,
  "http_status": 401,
  "message": "Invalid API key"
}

Numeric Error Codes

Examples (Bearer + user_id)

cURL

curl -G "https://geoip.space/api/" \
  --data-urlencode "ip=8.8.8.8" \
  --data-urlencode "user_id=anon_7f3a2c9a1e44b2d0" \
  --data-urlencode "fields=geo.country,geo.country_enrichment.tld,antifraud.risk_score" \
  --data-urlencode "crypto=BTC,ETH" \
  -H "Authorization: Bearer YOUR_API_KEY"

JavaScript (browser fetch)

const userId = getOrCreateUserId();
const url = new URL("https://geoip.space/api/");
url.searchParams.set("ip", "8.8.8.8");
url.searchParams.set("user_id", userId);
url.searchParams.set("fields", "geo.country,geo.country_enrichment.tld,antifraud.risk_score");
url.searchParams.set("crypto", "BTC,ETH");

const res = await fetch(url, {
  headers: { Authorization: "Bearer YOUR_API_KEY" }
});
const data = await res.json();
console.log(data.antifraud?.risk_score, data.antifraud?.advanced_insights?.smart_action_hint);

PHP (cURL)

$userId = $_COOKIE['gid_uid'] ?? ('anon_' . bin2hex(random_bytes(8)));
setcookie('gid_uid', $userId, time() + 31536000, '/');

$url = "https://geoip.space/api/?ip=8.8.8.8&user_id=" . urlencode($userId) . "&fields=geo.country,geo.country_enrichment.tld,antifraud.risk_score&crypto=BTC,ETH";
$ch = curl_init($url);
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ["Authorization: Bearer YOUR_API_KEY"]
]);
$response = curl_exec($ch);
curl_close($ch);

$data = json_decode($response, true);
$score = $data['antifraud']['risk_score'] ?? null;
$hint = $data['antifraud']['advanced_insights']['smart_action_hint'] ?? 'allow';

Python (requests)

import requests, uuid

user_id = "anon_" + uuid.uuid4().hex[:16]
r = requests.get(
    "https://geoip.space/api/",
    params={
        "ip": "8.8.8.8",
        "user_id": user_id,
        "fields": "geo.country,geo.country_enrichment.tld,antifraud.risk_score",
        "crypto": "BTC,ETH",
    },
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    timeout=10,
)
data = r.json()
print(data.get("geo", {}).get("country", {}).get("iso_code"))
print(data.get("antifraud", {}).get("risk_score"))
print(data.get("antifraud", {}).get("advanced_insights", {}).get("smart_action_hint"))

Java (HttpClient)

String userId = "anon_" + java.util.UUID.randomUUID().toString().replace("-", "").substring(0, 16);
String api = "https://geoip.space/api/?ip=8.8.8.8&user_id=" + userId + "&fields=geo.country,geo.country_enrichment.tld,antifraud.risk_score&crypto=BTC,ETH";

HttpRequest req = HttpRequest.newBuilder()
    .uri(URI.create(api))
    .header("Authorization", "Bearer YOUR_API_KEY")
    .GET()
    .build();

HttpResponse<String> res = HttpClient.newHttpClient()
    .send(req, HttpResponse.BodyHandlers.ofString());
System.out.println(res.body());

C++ (libcurl)

std::string userId = "anon_7f3a2c9a1e44b2d0";
std::string url = "https://geoip.space/api/?ip=8.8.8.8&user_id=" + userId + "&fields=geo.country,geo.country_enrichment.tld,antifraud.risk_score&crypto=BTC,ETH";

struct curl_slist* headers = NULL;
headers = curl_slist_append(headers, "Authorization: Bearer YOUR_API_KEY");

CURL* curl = curl_easy_init();
curl_easy_setopt(curl, CURLOPT_URL, url.c_str());
curl_easy_setopt(curl, CURLOPT_HTTPHEADER, headers);
curl_easy_setopt(curl, CURLOPT_WRITEFUNCTION, writeCallback);
curl_easy_perform(curl);

Kotlin (OkHttp)

val userId = "anon_" + java.util.UUID.randomUUID().toString().replace("-", "").take(16)
val url = "https://geoip.space/api/?ip=8.8.8.8&user_id=$userId&fields=geo.country,geo.country_enrichment.tld,antifraud.risk_score&crypto=BTC,ETH"

val request = Request.Builder()
    .url(url)
    .addHeader("Authorization", "Bearer YOUR_API_KEY")
    .get()
    .build()

val body = OkHttpClient().newCall(request).execute().body?.string()
println(body)

Response when antifraud field is requested without antifraud plan

{
  "status": "ok",
  "error_code": 0,
  "http_status": 200,
  "subscription_type": "geo",
  "geo": {
    "country": {"iso_code": "US", "name": "United States"},
    "country_enrichment": {"tld": ".us"}
  },
  "access": {
    "message": "Some requested fields are unavailable for your current subscription",
    "required_subscription": "antifraud",
    "missing_fields": ["antifraud.risk_score"],
    "available_fields": ["geo.country", "geo.country_enrichment.tld"]
  }
}