Look up IP addresses in batches
Send a list of IP addresses to one endpoint and receive a matching list of location results. Watch-IP's bulk IP lookup API accepts up to 100 IPv4 and IPv6 addresses per request for backend enrichment workflows. Keep your secret key on the server, process the response in input order, and handle missing records without losing the connection to your original data.
One request, up to 100 addresses
Use POST /v1/lookup with a JSON object containing an ips array. Each accepted batch contains at least one address and at most 100, and you can mix valid IPv4 and IPv6 addresses in the same list. The response wraps the ordered lookup results in a results array; every result uses the single-IP lookup shape, including found and nullable location fields.
Keep results aligned with your source records
For a successful batch, the API returns one result for each input address in the same order. Keep your own record identifiers alongside the submitted list so you can join the results back to your original rows. When a record is not found, preserve the row and mark the location unavailable; when only a field is missing, retain the rest of the result. Do not replace missing coordinates with zero, which would turn an absence of data into a misleading map location.
Validate before you submit
An empty list, a list larger than 100 addresses, or a malformed IP produces a request error — a malformed address rejects the whole batch rather than producing a partial-success result for the remaining inputs. Validate input and divide longer lists into batches before sending them, and keep a record of completed batches so a retry does not accidentally repeat an entire job.
Understand what batching changes
Batching reduces the number of HTTP requests needed to submit a list. It does not change the data source, add security fields, or turn 100 lookups into one unit of usage — lookup usage is recorded per submitted IP on accepted requests, so plan selection should account for both total lookup volume and request rate. The per-minute rate limit counts HTTP calls, not items: a batch of up to 100 IPs or email addresses is one request toward it, while each item still counts separately toward the monthly request cap.
Request and response shape
- ips
- Request body: a JSON array of 1–100 IPv4 or IPv6 addresses.
- results
- Response: an ordered array with one entry per input address, in the same order submitted.
- results[].found, results[].country, ...
- Each result uses the same shape and nullability as the single-IP lookup response — see the IP lookup product page.
Send a batch request
cURL — POST /v1/lookup
curl --fail-with-body \
'https://api.watch-ip.com/v1/lookup' \
--header "Authorization: Bearer ${WATCH_IP_SECRET_KEY}" \
--header 'Content-Type: application/json' \
--data '{"ips":["8.8.8.8","2001:4860:4860::8888"]}'These demonstration addresses do not imply particular current location values. Set WATCH_IP_SECRET_KEY in your server's environment first.
Frequently asked questions
How many IP addresses fit in a batch?
The current maximum is 100. Split longer lists into requests that each contain 1–100 addresses.
Can a batch contain both IPv4 and IPv6?
Yes. Every address must be valid, and database coverage can differ by address.
Are results returned in input order?
Yes. A successful accepted batch returns one result per input address in the same order.
What happens if one IP is malformed?
The whole request is rejected. Validate your input before submitting — this endpoint does not provide partial success for malformed input.
Is one batch billed as one lookup?
No. Usage is measured per IP. Review current lookup pricing and verified billing examples before estimating a large job's cost.
Can I upload a CSV file?
The documented endpoint accepts a JSON array of addresses. Your application can read its own CSV and submit batches; a hosted CSV-upload interface is not part of this API.
Does bulk lookup include VPN or Tor checks?
No. The current bulk response is the third-party geolocation database location result. Visitor-geo security indicators are a separate capability not present in lookup responses.