IP intelligence

Risk score

The score is arithmetic over the flags in the same response, capped at 100. Recompute it, or ignore it and branch on the booleans. Two rules apply: the datacenter weight is skipped when is_relay or is_crawler is true, because relay egress and verified crawlers sit on infrastructure by design, and is_vpn answers false on relay egress unless a VPN provider’s own list names the address, because Apple’s first-party declaration outranks the aggregate list that also carries those ranges.

Worked examples, as the API answers them:

risk_signals spells the sum out so nobody re-implements it. For the relay example above it reads:

"risk_signals": [
  { "signal": "datacenter", "weight": 0,  "dataset": "datacenter-ranges" },
  { "signal": "relay",      "weight": 10, "dataset": "relay-ranges" }
],
"risk_score": 10,
"risk_level": "low"

Residential proxies are not detectable with open data and are not claimed. When that signal ships it will be a separately labelled field, never folded into these weights.

Self and browser lookups

The same lookup is available three ways from a server. POST /api/v1/ip takes the address in the body, GET /api/v1/ip/{ip} takes it in the path, and GET /api/v1/ip/me answers for the address the call came from, as seen through the proxy in front of the service. Options ride in the body or the query string.

$ curl https://spaw.co/api/v1/ip/me \
    -H "Authorization: Bearer sk_live_…"

$ curl "https://spaw.co/api/v1/ip/2001:4860:4860::8888?privacy=1" \
    -H "Authorization: Bearer sk_live_…"

From a page, use a publishable key against POST /api/v1/ip/public. Create the key on the API keys page and list the domains it may run from; the endpoint checks the browser’s Origin header against that list. Leave ip out and the visitor’s own address is looked up, which is the usual case for choosing a language, a currency, or a consent banner on first paint:

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

if (data.is_eu) showConsentBanner();
if (data.currency) setDefaultCurrency(data.currency);
if (data.is_anonymous) requireEmailConfirmation();

Lookups bill the key’s owner and the response carries no meta block, so visitors never see the balance. Because the key sits in page source, give it a daily credit cap; once spent, the endpoint answers 429 KEY_SPEND_CAP_REACHED until the next day, and free answers never count toward it. A key that carries a Cloudflare Turnstile pair requires a confirmed turnstile_token with every lookup. The endpoint is throttled at 20 requests a minute per visitor.

Batch and bulk

POST /api/v1/ip/batch looks up as many as 1,000 addresses in one call, in input order, under the single-lookup billing rules. Repeats inside the list are looked up once. If the balance runs out mid-list, the paid partial results come back with meta.stopped_reason: "insufficient_credits"; only a batch whose first lookup is refused answers the typed 402. A batch counts as one request against the rate limit.

$ curl https://spaw.co/api/v1/ip/batch \
    -H "Authorization: Bearer sk_live_…" \
    -H "Content-Type: application/json" \
    -d '{"ips": ["8.8.8.8", "103.124.165.2", "192.168.1.1"]}'

For log files and exports, a bulk run queues up to 100,000 addresses with POST /api/v1/ip/bulk or from the IP intelligence page in the dashboard. Poll GET /api/v1/ip/bulk/{jobId} for progress and the running low, medium and high counts, then download the CSV from GET /api/v1/ip/bulk/{jobId}/results: one row per input address, in input order, with these columns:

ip, version, reason, network, continent, country, country_name, is_eu, is_eea, privacy_regime, region, city, latitude, longitude, location_source, location_confidence, timezone, currency, calling_code, asn, org, asn_type, registry, registry_country, allocated_at, is_datacenter, hosting_provider, is_crawler, crawler, crawler_kind, is_blocklisted, blocklist, is_tor, is_vpn, is_relay, privacy_service, is_anonymous, risk_score, risk_level, credits_used

Cancelling stops a queued job on the spot and a running one at its next checkpoint; rows already answered stay billed and downloadable. With a webhook_url, the finish is POSTed there as bulk_ip_job.finished, signed in X-Spaw-Signature with the HMAC-SHA256 of the raw body keyed with the secret creation returns once. Send an Idempotency-Key header to make creation safe to retry: the same key with the same request replays the job with Idempotent-Replayed: true, the same key with a different request answers 409 IDEMPOTENCY_KEY_REUSED.

IP endpoints have their own rate limit of 50 requests per second per key, separate from the 5 per second that applies to the email endpoints.

Outcome feedback

A lookup can only say what the feeds know. What you learn afterwards, a confirmed fraudulent order, a scraper, a bot that got through, a chargeback, can be sent back so your own later lookups of that address carry it: POST /api/v1/ip/feedback takes up to 1,000 items of an address and an outcome, abuse, fraud, bot or chargeback, with an optional occurred_at. It is free and never logged as a lookup.

$ curl https://spaw.co/api/v1/ip/feedback \
    -H "Authorization: Bearer sk_live_…" \
    -H "Content-Type: application/json" \
    -d '{"items": [{"ip": "203.0.113.9", "outcome": "fraud"}]}'

Any report you made about an address inside the last 30 days adds reported_abuse (+60, dataset abuse-feedback) to your own lookups of it. Once three or more accounts report the same address inside 30 days, everyone's lookups of it carry reported_abuse_widely (+40); only the number of reporting accounts is ever read, never who reported or what. Neither signal turns a null score into a number: an address no feed evaluated stays unscored.

Reports are the one thing the IP product stores on purpose, and even they never hold the address: each is a salted SHA-256 hash of the canonical address with the outcome and a timestamp, which can confirm a later lookup of the same address but cannot be read back into one. Malformed and reserved addresses are skipped and counted, not rejected. Reports are kept for 90 days, and GET /api/v1/ip/feedback/summary answers that window: totals per outcome, distinct addresses, and the IPv4 and IPv6 split.

Monitored lists

Your own addresses deserve the same check as your visitors’. A monitored list ( POST /api/v1/ip/monitors) keeps up to 500 of them, egress addresses, mail servers and office connections, under a daily, weekly or monthly re-check. The first run sets the baseline; from the next run on, every address that newly lands on a threat blocklist, becomes a Tor exit or scores high arrives by email with the reason, so you learn that a mail server sits on Spamhaus DROP before your recipients’ inboxes do.

Each run bills every address like a single lookup, and the seven-day repeat marker applies, so a daily list costs at most one credit per address a week; reserved addresses are free. GET /api/v1/ip/monitors/{id} answers the last run per address: its status (clean, flagged or reserved), the flags that fired (blocklisted, tor, high_risk), the list that names it, and whether it changed. POST /api/v1/ip/monitors/{id}/run re-checks the list ahead of schedule, and DELETE stops it.