Bulk Lookups

A simple solution to lookup multiple addresses is to call our single IP endpoint for each of the IPs. Here is a sample using common Unix command-line tools.

Let's say you have a file named ips.txt in your current directory that contains all the IP addresses you want to lookup, with each IP on a dedicated line:

66.165.2.7
1.1.1.1
8.8.4.4

On Linux, you can use the xargs command to pipe the file content to curl and do a lookup for every IP in the file:

cat ips.txt | xargs -I% curl "https://api.ipregistry.co/%?key=YOUR_API_KEY"

The main drawback of this method is that you pay the price of the network latency to send and receive payloads for each single IP request. You could send requests in parallel to hide the network latency but it has its own limits. As a solution, we recommend using our batch lookup endpoint (see below).

Batch processing

The batch lookup endpoint offers the ability to request data for up to 1024 IP addresses in a single call.

The recommended approach is to send an HTTP POST to the batch endpoint with a JSON array that contains the IP addresses to look up as body.

To continue with the file based example, you can split your IPs list into groups of 1024 addresses and transform each group into a JSON array:

cat ips.txt | xargs -n 1024 | sed 's/ /","/g' | sed 's/^/["/g' | sed 's/$/"]/g' > ips-batch.txt

then, you only have to send IP groups to the Ipregistry endpoint:

cat ips-batch.txt | sed 's/"/\\"/g' | xargs --max-procs 8 --max-args 1 -I% \
    curl --silent --request POST \
         --header "Content-Type: application/json" \
         --data % "https://api.ipregistry.co/?key=YOUR_API_KEY"

Using the batch lookup endpoint, IP Info is returned in the same order as the IP addresses you specified in the input. However, the command xargs --max-procs 8 parallelizes the execution, which provides unordered results. If you need to keep the original order, use --max-procs 1 or sort the final result based on IP addresses.

Batch lookups and filtering

Endpoints that output JSON supports response filtering, this includes the batch lookup endpoint.

When appending multiple GET arguments to the Ipregistry API endpoint in your shell, make sure to wrap the URL between double quotes to prevent your shell to evaluate characters such as &.

Hereafter is the example from the previous section returning only the country code and name for each inputted IP address:

cat ips-batch.txt | sed 's/"/\\"/g' | xargs --max-procs 8 --max-args 1 -I% \
    curl --silent --request POST \
         --header "Content-Type: application/json" \
         --data % "https://api.ipregistry.co/?key=YOUR_API_KEY&fields=location.country.code,location.country.name"