API Documentation

Overview

This API service is designed for quick and easy visitors IP geolocation integration into your script or website. Get rid of setting up local GeoIP libraries and forget about regular updates. Our neural network analyzes dozens of sources and almost real-time updates the database.

API Endpoints

• Single IP Lookup
• Bulk IP Lookup

Single IP Lookup

You can call the API by sending HTTP GET requests to http://ipwho.is/[IP address]

[IP address] can be an IPv4 or IPv6 address, or none to use the current IP address.

# Get details for 8.8.4.4
$ curl "http://ipwho.is/8.8.4.4"

# Get details for your own IP address
$ curl "http://ipwho.is/"

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 Output Format

Using the GET parameter output, you can switch the API result format between JSON (default), XML and CSV. If you are using JSON, this parameter can be omitted.

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://ipwho.is/'.$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://ipwho.is/' + 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://ipwho.is/' + 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://ipwho.is/'+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);