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.


Data formats

JSON endpoint

You can call the API by sending HTTP GET requests to http://ipwhois.app/json/{IP}

{IP} can be an IPv4 or IPv6 address, or none to use the current IP address.


Example

You can edit this query and experiment with the options

GET
Actual response
{
  "ip": "8.8.4.4",
  "success": true,
  "type": "IPv4",
  "continent": "North America",
  "continent_code": "NA",
  "country": "United States",
  "country_code": "US",
  "country_flag": "https://cdn.ipwhois.io/flags/us.svg",
  "country_capital": "Washington",
  "country_phone": "+1",
  "country_neighbours": "CA,MX,CU",
  "region": "New Jersey",
  "city": "Newark",
  "latitude": 40.735657,
  "longitude": -74.1723667,
  "asn": "AS15169",
  "org": "Google LLC",
  "isp": "Google LLC",
  "timezone": "America/New_York",
  "timezone_name": "Eastern Standard Time",
  "timezone_dstOffset": 0,
  "timezone_gmtOffset": -18000,
  "timezone_gmt": "GMT -5:00",
  "currency": "US Dollar",
  "currency_code": "USD",
  "currency_symbol": "$",
  "currency_rates": 1,
  "currency_plural": "US dollars",
  "completed_requests": 0
}

Returned data

The API can return the following fields and values

name description
ip IP used for the query (e.g. 8.8.4.4)
success true or false
message included only when success is false
Can be one of the following: invalid IP address, you've hit the monthly limit
type IP address type (IPv4 or IPv6)
continent Continent name (e.g. North America)
continent_code Two-letter continent code (e.g. NA)
country Country name (e.g. United States)
country_code Two-letter country code (e.g. US)
country_capital The capital of country (e.g. Washington)
country_phone Country Phone Code (e.g. +1)
country_neighbours Neighboring countries (e.g. CA,MX,CU)
region Region/state (e.g. Virginia)
city City (e.g. Ashburn)
latitude Latitude (e.g. 39.0437567)
longitude Longitude (e.g. -77.4874416)
as AS number (e.g. AS15169)
org Organization name (e.g. Level 3 Communications)
isp ISP name (e.g. Level 3 Communications)
timezone City timezone (e.g. America/New_York)
timezone_name Full time zone name (e.g. Eastern Standard Time)
timezone_dstOffset The offset for daylight-savings time in seconds.
timezone_gmtOffset The offset from UTC (in seconds) for the given location. (e.g. -18000)
timezone_gmt Timezone GMT. (e.g. GMT -5:00)
currency Country currency name. (e.g. US Dollar)
currency_code Country currency code. (e.g. USD)
currency_symbol Country currency symbol. (e.g. $)
currency_rates The current exchange rate against the US dollar.
currency_plural Currency plural. (e.g. US dollars)
completed_requests Number of API calls for the current month (Updated every 2 minutes).

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 objects parameter to the API request's URL and set a specific field or fields list with a comma.

For example: objects=country,city,timezone


JSONP Callback

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

For example: callback=getIPinfo


Localization

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

lang description demo
en English (default)
ru Русский (Russian)
de Deutsch (German)
es Español (Spanish)
pt-BR Español - Argentina (Spanish)
fr Français (French)
zh-CN 中国 (Chinese)
ja 日本語 (Japanese)

Usage limits

You can use our API for free up to 10,000 requests per month. See our pricing details if you need more.

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


Code examples

Simple code examples in popular languages are given below:

  • PHP
  • Javascript
  • jQuery
  • Python
PHP (CURL)
$ip = $_SERVER['REMOTE_ADDR'];

$ch = curl_init('http://ipwhois.app/json/'.$ip);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$json = curl_exec($ch);
curl_close($ch);

// Decode JSON response
$ipwhois_result = json_decode($json, true);

// Country code output, field "country_code"
echo $ipwhois_result['country_code'];
Javascript (XMLHttpRequest)
var ip = ''; // Current IP
var XMLHttp = new XMLHttpRequest();

XMLHttp.onreadystatechange = function() {
	if (this.readyState == 4 && this.status == 200) {
		var json = JSON.parse(this.responseText);
		// Country code output, field "country_code"
		alert(json.country_code);
	}
};
XMLHttp.open("GET", "http://ipwhois.app/json/" + ip, true);
XMLHttp.send();
Javascript (jQuery.ajax)
var ip = ''; // Current IP

// Sending an API request using jQuery.ajax
$.ajax({
	method: 'GET',
	contentType: 'application/json',
	url: 'http://ipwhois.app/json/' + ip,
	dataType: 'json',
	success: function(json) {
	    // Country code output, field "country_code"
	    alert(json.country_code);
	}
});
Python
import urllib2
import json

ip = "8.8.4.4";

# Sending an API request
response = urllib2.urlopen("http://ipwhois.app/json/"+ip)
ipgeolocation = json.load(response)

# Country code output, field "country_code"
print ipgeolocation["country_code"]