Batch Lookup Endpoint

Looks up to 1,000 IPv4 or IPv6 addresses in one request with an API key and returns the same data as the info endpoint for each, keyed by address. Every plan has it, the free one too; without a key the batch endpoint answers 401.

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. A batch needs an API key: without one the endpoint answers 401 with error.code missing_api_key and bills nothing (the 10 keyless lookups an hour are for single lookups).

POST/v2/batch

Batch Lookup

Send the addresses as a JSON array in the request body. For quick tests the same lookup also works as GET /v2/batch?ips=80.110.0.1,8.8.8.8, with up to 100 addresses.

Required attributes

Name
ips
Type
array
Description
1 to 1,000 IPv4 or IPv6 addresses. An item that is no IP address does not fail the batch: it 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.

Optional attributes

Name
language
Type
string
Description
Language for translated location names: de, en, es, fr, ja, pt, ru, zh (default: en).
Name
fields
Type
string
Description
Comma-separated dot paths to return for every address instead of the full object, e.g. ip,location.country.alpha2,security.is_vpn.
Name
hostname
Type
boolean
Description
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).
Name
user_agent
Type
string
Description
The User-Agent header your own visitor sent, one for every address of the batch, 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, plans with security data). Send it in the JSON body: in the query string of GET /v2/batch it ends up in URLs and access logs.
Name
coarse_location
Type
string
Description
omit leaves the city out of every answer for an anycast address or a coarse one (location.precision coarse), as on the info endpoint. For the plans with the network object (paid plans); other callers may send it and get the city as without it.

Response

data maps every requested address to the same object /v2/info returns, limited to the data your plan includes (the network, company and abuse objects are for paid plans). Without security data in your plan the security fields (including proxy_type) are null, as in /v2/info. 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).

The X-Data-As-Of header says when each data layer behind the answers was built, as for the info endpoint.

Request

POST

/v2/batch

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

Response

{
    "data": {
        "80.110.0.1": {
            "ip": "80.110.0.1",
            "connection": {
                "asn": 8412
            },
            "location": {
                "country": {
                    "alpha2": "AT"
                }
            }
        },
        "8.8.8.8": {
            "ip": "8.8.8.8",
            "connection": {
                "asn": 15169
            },
            "location": {
                "country": {
                    "alpha2": "US"
                }
            }
        }
    }
}