Look up an address from the browser with a publishable key

The browser counterpart of POST /api/v1/ip, for localising a page or screening a form on the client without exposing a secret key. It is authenticated by a publishable pk_ key in the body plus the browser's Origin header, which must match one of the domains the key is locked to. A missing Origin is rejected on purpose: servers use a secret key. Leave ip out to look up the visitor's own address, which is the usual case.

The lookup bills the key's owner under the normal rules and answers { "success", "data" } with no meta block, so page visitors never see the owner's balance. Because the key sits in page source, give it a daily credit cap in the dashboard: once the cap is spent the endpoint answers 429 KEY_SPEND_CAP_REACHED until the next day. Free answers (reserved ranges, cache hits) never count toward the cap. A key that carries a Cloudflare Turnstile pair requires a confirmed turnstile_token and answers 403 TURNSTILE_FAILED without one, before any credit is spent.

Throttled at 20 requests per minute per IP.

curl -X POST https://spaw.co/api/v1/ip/public \
  -H "Origin: https://www.example.com" \
  -H "Content-Type: application/json" \
  -d '{
  "key": "pk_live_…"
}'

const response = await fetch('https://spaw.co/api/v1/ip/public', {
  method: 'POST',
  headers: {
    'Origin': 'https://www.example.com',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "key": "pk_live_…"
  }),
});
const result = await response.json();

import requests

response = requests.post(
    'https://spaw.co/api/v1/ip/public',
    headers={'Origin': 'https://www.example.com'},
    json={
        'key': 'pk_live_…'
    },
)
result = response.json()

$ch = curl_init('https://spaw.co/api/v1/ip/public');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_HTTPHEADER => ['Origin: https://www.example.com', 'Content-Type: application/json'],
    CURLOPT_POSTFIELDS => json_encode([
        'key' => 'pk_live_…'
    ]),
]);
$result = json_decode(curl_exec($ch), true);

{
    "success": true,
    "data": {
        "ip": "203.0.113.9",
        "version": 4,
        "reason": null,
        "country": "DE",
        "country_name": "Germany",
        "is_eu": true,
        "city": "Berlin",
        "timezone": "Europe/Berlin",
        "currency": "EUR",
        "is_anonymous": false,
        "risk_score": 0,
        "risk_level": "low"
    }
}

{
    "success": false,
    "error": {
        "code": "INVALID_PUBLISHABLE_KEY",
        "message": "That publishable key does not exist or was revoked.",
        "request_id": "req_01m1kgdm4xngzmbmff68g94w0c"
    }
}

{
    "success": false,
    "error": {
        "code": "INSUFFICIENT_CREDITS",
        "message": "Your credit balance is empty.",
        "request_id": "req_01m1kgdm4xngzmbmff68g94w0c"
    }
}

{
    "success": false,
    "error": {
        "code": "ORIGIN_NOT_ALLOWED",
        "message": "This publishable key cannot be used from this origin.",
        "request_id": "req_01m1kgdm4xngzmbmff68g94w0c"
    }
}

{
    "success": false,
    "error": {
        "code": "VALIDATION_FAILED",
        "message": "The email field is required.",
        "errors": {
            "email": [
                "The email field is required."
            ]
        },
        "request_id": "req_01m1kgdm4xngzmbmff68g94w0c"
    }
}

{
    "success": false,
    "error": {
        "code": "KEY_SPEND_CAP_REACHED",
        "message": "This publishable key has reached its daily credit cap. The counter resets each day.",
        "request_id": "req_01m1kgdm4xngzmbmff68g94w0c"
    }
}