Batch processing gives you the ability to query multiple IP addresses in one HTTP request.
This is significantly faster than submitting individual queries.

The API base path is http://ip-api.com/batch

Only POST requests are accepted.

Parameters

Query parameters (such as custom fields) are appended as GET request parameters, for example:
http://ip-api.com/batch?fields=61439

There is no API key required.

Building a request

A request needs to formatted as a JSON array, containing up to 100 IP addresses or objects.
HTTP 422 Unprocessable Entity will be returned for requests containing more than the beforementioned amount.

The array can be made of single IP addresses, or, for more options, it can contain objects with the following:

{
    "query": "IPv4/IPv6 required",
    "fields": "response fields optional",
    "lang": "response language optional"
}

You can also supply default values for fields and lang as GET parameters. Setting them individually, as shown above, will override the defaults.

cURL examples

Quick test

You can edit this query and experiment with the options

Returned data

The API can return the following fields and values

If you don't require all the returned fields, use the GET parameter fields to specify which data should be returned.
Separate the fields by comma (fields=status,message,query,country,city) or use a generated, numeric value (to save bandwidth)

Localization

Localized city, regionName and country can be requested by setting the GET parameter lang to one of the following:

SSL (HTTPS)

256-bit SSL encryption is not available for this free API. Please see our pro service.

Usage limits

This endpoint is limited to 15 requests per minute from an IP address.

If you go over the limit your requests will be throttled (HTTP 429) until your rate limit window is reset. If you constantly go over the limit your IP address will be banned for 1 hour.

The returned HTTP header X-Rl contains the number of requests remaining in the current rate limit window. X-Ttl contains the seconds until the limit is reset.
Your implementation should always check the value of the X-Rl header, and if its is 0 you must not send any more requests for the duration of X-Ttl in seconds.

We do not allow commercial use of this endpoint. Please see our pro service for SSL access, unlimited queries and commercial support.

PHP code example

<?php
// An example script doing a batch request

// List of IP addresses to query, up to 100
$ips = ['208.80.152.201', '8.8.8.8', '24.48.0.1'];

// ip-api endpoint URL
// see http://ip-api.com/docs/api:batch for documentation
$endpoint = 'http://ip-api.com/batch';

$options = [
	'http' => [
		'method' => 'POST',
		'user_agent' => 'Batch-Example/1.0',
		'header' => 'Content-Type: application/json',
		'content' => json_encode($ips)
	]
];
$response = file_get_contents($endpoint, false, stream_context_create($options));

// Decode the response and print it
$array = json_decode($response, true);
print_r($array);
?>

JavaScript code example

// An example script doing a batch request

// List of IP addresses to query, up to 100
var IPs = ["208.80.152.201", "8.8.8.8", "24.48.0.1"];

// ip-api endpoint URL
// see http://ip-api.com/docs/api:batch for documentation
var endpoint = 'http://ip-api.com/batch';

var xhr = new XMLHttpRequest();
xhr.onreadystatechange = function() {
	if (this.readyState == 4 && this.status == 200) {
		// Result array
		var response = JSON.parse(this.responseText);
		console.log(response);
		response.forEach(function (item) {
			console.log(item.query + " is in " + item.city + ", " + item.country); 
		});
	}
};
var data = JSON.stringify(IPs);
console.log("sending:", data);

xhr.open('POST', endpoint, true);
xhr.send(data);