API Documentation

Overview

This API service offers seamless and efficient integration of IP geolocation for your scripts or websites. Say goodbye to the hassle of configuring and maintaining local GeoIP libraries. Our AI-powered system aggregates and analyzes data from multiple sources, ensuring the most precise geolocation information. The database updates almost in real time, guaranteeing up-to-date accuracy without manual intervention. With flexible and developer-friendly integration options, you can effortlessly incorporate geolocation capabilities and focus on building better user experiences.

API Endpoints

• Single IP Lookup
• Bulk IP Lookup

Bulk IP Lookup

Available in: Business and Premium Plan

The Bulk IP lookup endpoint allows you to group up to 100 IP search requests into a single request (you can mix up IPv4 and IPv6 addresses). This can really speed up the processing of bulk IP lookup.

We support 2 methods to pass values to a batch request: comma-separated and JSON array.

Comma-separated parameter

In order to process IP addresses in bulk with this method, simply append multiple comma-separated IP addresses to the following API URL (HTTP GET method):

$ curl "http://ipwhois.pro/bulk/8.8.4.4,1.1.1.1,2c0f:fb50:4003::?key=YOUR_API_KEY"

JSON array as POST body

To make a batch request you can also POST a JSON array containing all IP addresses you'd like to get the data for. Here's an example that uses cURL and the batch endpoint to get information about 3 different IP addresses with a single API call:

$ curl --data '["8.8.4.4", "1.1.1.1", "2c0f:fb50:4003::"]' \
     --header "Content-Type: application/json" \
     --request POST "http://ipwhois.pro/bulk?key=YOUR_API_KEY"

Please note: A batch IP lookup request costs as many credits as IP addresses specified. For instance, the example above costs 3 credits.

Our API is available over a secure HTTPS connection. Simply add https:// to the request URLs to make the requests secure.

Live demo

You can edit this query and experiment with the options:

{
    "ip": "8.8.4.4",
    "success": true,
    "type": "IPv4",
    "continent": "North America",
    "continent_code": "NA",
    "country": "United States",
    "country_code": "US",
    "region": "California",
    "region_code": "CA",
    "city": "Mountain View",
    "latitude": 37.3860517,
    "longitude": -122.0838511,
    "is_eu": false,
    "postal": "94039",
    "calling_code": "1",
    "capital": "Washington D.C.",
    "borders": "CA,MX",
    flag {
        "img": "https://cdn.ipwhois.io/flags/us.svg",
        "emoji": "🇺🇸",
        "emoji_unicode": "U+1F1FA U+1F1F8"
    },
    connection {
        "asn": 15169,
        "org": "Google LLC",
        "isp": "Google LLC",
        "domain": "google.com"
    },
    timezone {
        "id": "America/Los_Angeles",
        "abbr": "PDT",
        "is_dst": true,
        "offset": -25200,
        "utc": "-07:00",
        "current_time": "2022-04-22T14:31:48-07:00"
    },
    currency {
        "name": "US Dollar",
        "code": "USD",
        "symbol": "$",
        "plural": "US dollars",
        "exchange_rate": 1
    },
    security {
        "anonymous": false,
        "proxy": false,
        "vpn": false,
        "tor": false,
        "hosting": false
    }
}

Please note: For illustration purposes, we have included all available fields in the above API response. Depending on your subscription plan, the API response may vary.

Returned data

Depending on your subscription plan and the options you choose for your API request, the response will contain a number of different fields. Below is a list of all available API response fields:

Specify response fields

You can restrict API results to specific data fields if you don’t need to keep track of all the data. In this case, you need to add the GET parameter fields to the API request's URL and set a specific field or fields list with a comma.

JSONP Callback

API supports callback function (JSONP). Simply append the GET parameter callback to your API request URL and set it to your function name.

Localization

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

Enable Threat Detection

Available in: Business and Premium Plan

Security Data return fields (proxy, vpn, tor, hosting) for threat detection. This will allow you to protect your site or application from abuse in the form of bypassing a ban, hiding the real IP address, site parsing, etc. In order to use this feature, append the GET parameter security to your API request URL and set it to 1.

Rate information in the API response

Available in: Basic, Business and Premium Plan

In order to use this feature, append the GET parameter rate to your API request URL and set it to 1.
Here is an example (in JSON format) of the information in the API response body:

{
    [...],
    rate {
        "limit": "250000",
        "remaining": 50155
    }
}

Usage limits

You can use our API for free up to 10,000 requests per month (identification by IP address and Referer header). See our pricing details if you need more.

We do not allow commercial use of this endpoint. Please see our pro service to access Bulk Endpoint, usage statistics, advanced features and commercial support.

Code examples

Simple code examples in popular languages are given below:

$ip = '8.8.4.4';
$ch = curl_init('http://ipwhois.pro/'.$ip);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HEADER, false);
$ipwhois = json_decode(curl_exec($ch), true);
curl_close($ch);
echo $ipwhois['country'] . ' ' . $ipwhois['flag']['emoji']; // Output: United States 🇺🇸

var ip = '8.8.4.4'; // Leave blank to lookup current IP address
var XMLHttp = new XMLHttpRequest();
XMLHttp.onreadystatechange = function() {
	if(this.readyState == 4 && this.status == 200) {
		var ipwhois = JSON.parse(this.responseText);
		console.log(ipwhois.country + ' ' + ipwhois.flag.emoji); // Output: United States 🇺🇸
	}
};
XMLHttp.open('GET', 'https://ipwhois.pro/' + ip, true);
XMLHttp.send();

var ip = '8.8.4.4'; // Leave blank to lookup current IP address
$.ajax({
	method: 'GET',
	contentType: 'application/json',
	url: 'https://ipwhois.pro/' + ip,
	dataType: 'json',
	success: function(ipwhois) {
		console.log(ipwhois.country + ' ' + ipwhois.flag.emoji); // Output: United States 🇺🇸
	}
});

import re
import json
from urllib2 import urlopen
ip = '8.8.4.4';
response = urlopen('http://ipwhois.pro/'+ip)
ipwhois = json.load(response)

# Output: United States 🇺🇸
print '{0} {1}'.format(ipwhois['country'],ipwhois['flag']['emoji'])

// List of IP addresses to query, up to 100
$ips = array('8.8.4.4','1.1.1.1','2c0f:fb50:4003::');
$endpoint = 'http://ipwhois.pro/bulk?key=YOUR_API_KEY';
$options = array(
	'http' => array(
		'method' => 'POST',
		'header' => 'Content-Type: application/json',
		'content' => json_encode($ips)
	)
);
$response = json_decode(file_get_contents($endpoint, false, stream_context_create($options)), true);
foreach($response as $ipwhois)
{
	echo $ipwhois['ip'] . ' - ' . $ipwhois['country'] . ' ' . $ipwhois['flag']['emoji']."\n";
	// Output:
	// 8.8.4.4 - United States 🇺🇸
	// 1.1.1.1 - Australia 🇦🇺
	// 2c0f:fb50:4003:: - Kenya 🇰🇪
}

// List of IP addresses to query, up to 100
var IPs = ['8.8.4.4','1.1.1.1','2c0f:fb50:4003::'];
var endpoint = 'https://ipwhois.pro/bulk?key=YOUR_API_KEY';
var xhr = new XMLHttpRequest();
xhr.onreadystatechange = function() {
	if(this.readyState == 4 && this.status == 200) {
		var response = JSON.parse(this.responseText);
		response.forEach(function(ipwhois) {
			console.log(ipwhois.ip + ' - ' + ipwhois.country + ' ' + ipwhois.flag.emoji);
			// Output:
			// 8.8.4.4 - United States 🇺🇸
			// 1.1.1.1 - Australia 🇦🇺
			// 2c0f:fb50:4003:: - Kenya 🇰🇪
		});
	}
};
var data = JSON.stringify(IPs);
xhr.open('POST', endpoint, true);
xhr.send(data);