Watch-IP

Bulk IP Lookup API Reference

POST/v1/lookup

Batch version of GET /v1/lookup/{ip} — resolves up to 100 IPv4/IPv6 addresses in a single backend request, returned in the same order they were submitted. Same response fields as the single-IP endpoint, except userAgent and hostname (single-IP-only options with no batch equivalent).

Authentication

Provide a secret key via Authorization: Bearer YOUR_SECRET_KEY, the same key type as the single-IP lookup endpoint.

Request body

ips
An array of 1–100 IPv4/IPv6 address strings. The entire batch is validated before any lookup runs — one malformed address fails the whole call.

Errors

400
An empty ips array, more than 100 IPs, or a malformed IP anywhere in the array.
401
Missing or invalid API key.
403
A publishable key was used instead of a secret key.
429
The per-minute rate limit or the plan's monthly request cap has been exceeded — see errors and rate limits for how to tell which.

Example

Request

curl https://api.watch-ip.com/v1/lookup \
  -H "Authorization: Bearer YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{"ips": ["203.0.113.1", "2001:db8::1"]}'

Response

{
  "results": [
    { "ip": "203.0.113.1", "country": "US", "region": "Texas", "regionCode": "TX", "city": "Austin", "postalCode": "78701", "latitude": 30.2672, "longitude": -97.7431, "continent": "NA", "timezone": "America/Chicago", "found": true },
    { "ip": "2001:db8::1", "country": null, "region": null, "regionCode": null, "city": null, "postalCode": null, "latitude": null, "longitude": null, "continent": null, "timezone": null, "found": false }
  ]
}

Limits

Each IP in the batch is billed and recorded individually — a 100-IP call records 100 lookup usage events, not one. A duplicate IP submitted twice is billed twice. Toward the per-minute rate limit, the whole call counts as one request. Location data for this endpoint is provided by DB-IP (IP Geolocation by DB-IP, db-ip.com — CC BY 4.0) and GeoNames (IP Geolocation data by GeoNames.org — CC BY 4.0).

Related pages