# Batch Endpoint

Looks up to 1,000 IPv4 or IPv6 addresses in one request and returns the same data as the info endpoint (opens new window) for each, keyed by address. Use it to enrich logs, sign-up lists or analytics exports without sending one request per address.

Billing

Each valid address counts as one request against your quota; the X-Cost header of the response tells you the total. Items that are no IP address are not billed. Duplicate addresses in the same batch are looked up and billed once, also in another notation of the same address (2001:db8::1 and 2001:DB8:0:0:0:0:0:1), under the spelling sent first. A batch your quota cannot cover is refused with a 429 before any address is looked up; quota.required in the response is what it needed. If your plan does not include the batch endpoint, it answers 403 with error.code plan_upgrade_required.

Request Method: POST (or GET with ips in the query string)
Request URL: https://api.iplookupapi.com/v1/batch

# Request Parameters

Parameter	Type	Mandatory	Description
`apikey`	string	️	Your API Key
`ips`	array	️	1 to 1,000 IPv4 or IPv6 addresses as a JSON array in the body (`{"ips": [...]}`), or 1 to 100 comma-separated in the query string. An item that is no IP address is listed in `errors` and neither looked up nor billed; only a batch without a single IP address, or with too many items, is refused with a `422`
`language`	string		Language for localising the IP data: `de`, `en`, `es`, `fr`, `ja`, `pt`, `ru`, `zh` (default: `en`)
`fields`	string		Comma-separated dot paths to return for every address, e.g. `ip,location.country.alpha2`
`hostname`	boolean		`true` looks up the reverse-DNS name of every address, in parallel within 8 seconds: each answer gets `hostname` (`null` without a name) and, after its other keys, `hostname_status`: `found`, `not_found` or `timeout` (no answer in time; ask again later)
`user_agent`	string		The `User-Agent` header your own visitor sent, one for every address, at most 512 characters: each answer's `security.bot.spoofed` then says whether the address belongs to the operator of the bot that user agent claims to be (bot verification (opens new window), plans with security data). Send it in the JSON body: in the query string it ends up in URLs and access logs
`coarse_location`	string		`omit` leaves the city out of every answer for an anycast address or a coarse one (`location.precision` `coarse`), as on the info endpoint (opens new window). For the plans with the `network` object (paid plans); other plans may send it and get the city as without it

Private and reserved addresses (e.g. 10.0.0.1) do not fail the batch; they come back with their range_type and without location data. errors follows data when items of the batch are no IP address: each such item (cut to 64 characters) with the reason, e.g. {"not-an-ip": "Not a valid IP address."}. Before, such an item failed the whole batch (what changed (opens new window)).

# Sample Request

curl "https://api.iplookupapi.com/v1/batch?fields=ip,location.country.alpha2" \
    -H "apikey: YOUR-API-KEY" \
    -H "Content-Type: application/json" \
    -d '{"ips": ["80.110.0.1", "8.8.8.8"]}'

The same lookup as a simple GET:

curl "https://api.iplookupapi.com/v1/batch?apikey=YOUR-API-KEY&ips=80.110.0.1,8.8.8.8&fields=ip,location.country.alpha2"

# Sample Response

With fields=ip,location.country.alpha2:

{
    "data": {
        "80.110.0.1": {
            "ip": "80.110.0.1",
            "location": {
                "country": {
                    "alpha2": "AT"
                }
            }
        },
        "8.8.8.8": {
            "ip": "8.8.8.8",
            "location": {
                "country": {
                    "alpha2": "US"
                }
            }
        }
    }
}

Without fields, every address carries the full object described on the info endpoint (opens new window) page.

← Info Endpoint