Batch lookup: 1–100 IPs

POST /v1/ip/batch

Authentication: lookup scope and a paid plan; compare scope for source: all. Credits: 1 per IP; 2 per IP for comparison.

curl --fail-with-body --max-time 20 'https://orig.ooo/v1/ip/batch' \
  -H "Authorization: Bearer $ORIGOOO_API_KEY" \
  -H 'Content-Type: application/json' \
  --data '{"ips":["8.8.8.8","1.1.1.1"],"source":"canonical"}'

Validation and results

All inputs are validated before lookup. One invalid/private IP rejects the whole request with 422. Empty lists and more than 100 entries also fail. Free accounts receive 403 paid_plan_required. Credits for the full request must be available before it starts.

A completed request returns results in input order, credits_charged, remaining and reset_at. Inspect each item’s status/error: HTTP 200 for the batch does not mean every IP matched. Completed no-match items consume credits; source exceptions are not charged. Duplicate entries are separate billable items. A batch is one HTTP request toward throughput while its credits count individual IP entries.

Inspect individual item results

This illustrative excerpt contains one match and one no-match. Both completed items are charged. An error in one lookup must not be mistaken for a successful location.

{
  "results": [
    {
      "status": 200,
      "ip": "8.8.8.8",
      "country_code": "US",
      "source_id": "dbip-lite"
    },
    {
      "status": 404,
      "code": "no_match",
      "message": "No matching public range."
    }
  ],
  "credits_charged": 2,
  "remaining": 998,
  "reset_at": "EXAMPLE_RESET_TIME"
}

for (const item of body.results ?? []) {
  if (item.status === 200) useLocation(item);
  else handleUnknown(item.error?.code || item.code || 'lookup_failed');
}
// useLocation and handleUnknown are your application functions.