Skip to main content

Batch lookup

The batch lookup endpoint allows you to perform IP address lookups for multiple IP addresses in a single request. This is more efficient than making individual requests for each IP address.

Batch lookups are ideal for bulk data processing, security analysis, analytics, data enrichment, performance optimization, and more.

You can look up up to 1,000 IP addresses in a single request.

info

Batch lookups are only available for users on paid plans or with paid credits.

Each IP address in a batch request counts as 1 API request towards your quota.

Make a batch request​

POST /api/batch
curl -X POST "https://iplocate.io/api/batch?apikey=YOUR_API_KEY" -H "Content-Type: application/json" -d '["8.8.8.8", "1.1.1.1"]'

Parameters​

Send a JSON array of IPv4 or IPv6 addresses:

[
  "8.8.8.8",
  "1.1.1.1",
  "2001:4860:4860::8888"
]

Response​

The response is a JSON object with each input IP address as a key and the corresponding lookup result as the value:

{
  "8.8.8.8": {
    "ip": "8.8.8.8",
    "country": "United States",
    "country_code": "US",
    // ...
  },
  "1.1.1.1": {
    "ip": "1.1.1.1",
    "country": "United States",
    "country_code": "US",
    // ...
  },
  "2001:4860:4860::8888": {
    "ip": "2001:4860:4860:0000:0000:0000:0000:8888",
    "country": "United States",
    "country_code": "US",
    // ...
  }
}

Inline errors​

If an IP address in the batch request is invalid, the response will contain an error object for that IP address. Any valid IP addresses will be processed as normal.

Example​

Request
curl -X POST "https://iplocate.io/api/batch?apikey=YOUR_API_KEY" -H "Content-Type: application/json" -d '["invalid-ip","8.8.8.8"]'
Response
{
  "invalid-ip": {
    "error": "invalid ip"
  },
  "8.8.8.8": {
    "ip": "8.8.8.8",
    "country": "United States",
    "country_code": "US",
    // ...
  }
}

Invalid IP address​

The IP address is invalid.

{ "error": "invalid ip" }

Not found​

We have no data for this IP address.

{ "error": "not found" }

Error responses​

Too many IPs 400​

{
  "error": "Too many IPs. Maximum batch size is 1000."
}

Not available for free plans 400​

{
  "error": "Batch lookup is not available for free plans without credits. Please purchase credits at https://iplocate.io/account/credits or sign up to a paid plan."
}

No API key 401​

{
  "error": "Missing API key. Sign up for a free API key at https://iplocate.io/signup"
}

Invalid API key 401​

{
  "error": "Invalid API key"
}

Insufficient quota 429​

{
  "error": "Insufficient quota. Please upgrade your plan at https://iplocate.io/account"
}