logo
IP Address Geolocation XML API

The API returns the location of an IP address (country, region, city, zipcode, latitude, longitude) and the associated timezone in XML format. You can find below code samples with PHP, Javascript, Ruby, Python and ASP.

Usage
For city precision, do a query with the following API (if you omit the IP parameter it will check with your own IP) :
http://api.ipinfodb.com/v3/ip-city/?key=<your_api_key>&ip=74.125.45.100
For country precision (faster), do a query with the following API :

IPv4 Address

http://api.ipinfodb.com/v3/ip-country/?key=<your_api_key>&ip=74.125.45.100

IPv6 Address

http://api.ipinfodb.com/v3/ip-country/?key=<your_api_key>&ip=2001:0200:0102::
Note: Supported both the http and https API query.
If you don’t have an API key yet, just go to here and register for your free API key. You will need this API key to be able to use our newer APIs.
API parameters
Parameter Required Default Value
key Yes <empty> API key provided with your free account.
ip No Client IP IP address
format No raw raw, xml, json
callback No <empty> Required when using json callback.
Please use the appropriate API for your needs. You can help us keep the load low on our servers by making sure that :
  • If you only need the country name, avoid using the city precision API.
  • If you track your visitors, avoid querying our API for all your page views (you can store the geolocation in a cookie, see below for an example)
API list
API Precision Timezone Domains lookups
ip-city City Yes Yes
ip-country Country No Yes
Please use the appropriate API for your needs. You can help us keep the load low on our servers by making sure that :
  • If you only need the country name, avoid using the city precision API.
  • If you track your visitors, avoid querying our API for all your page views (you can store the geolocation in a cookie, see below for an example)
Why do I need to register?

We are always trying to improve on our free services and to do so we need to be able to tell who is querying what data and how often. This will enable us to fully optimize our limited resources to providing a more stable and reliable service to our users.

What is this API key and do I need it?

This API key is just a random string of characters which uniquely identifies each user. This is how we can track your usage for the purpose of optimizing our resources. Users of our existing APIs need not use this API key but please note that we are in the process of phasing out the old APIs and you will have to use our newer APIs in the future. These new APIs are more optimized for performance and as such we need to be able to allocate resources in an optimal fashion by tracking the usage of the APIs.

How do I get this API key?

This API key is free for everyone. You just have to go to here to register and a unique API key will sent to your email address.

Data accuracy

Over 99.5% on a country level and around 60% on a city level for the US within a 25 mile radius.

You can try a few lookups with our IP locator.

Servers uptime

We have 2 servers. They are load balanced & highly available (ldirectord + heartbeat setup). Our goal is to have over 99.99% uptime.

PHP example

We wrote a PHP class for our API. You can download it here. Here is an example using all the features of the class :

<?php
include('ip2locationlite.class.php');
 
//Load the class
$ipLite = new ip2location_lite;
$ipLite->setKey('<your_api_key>');
 
//Get errors and locations
$locations = $ipLite->getCity($_SERVER['REMOTE_ADDR']);
$errors = $ipLite->getError();
 
//Getting the result
echo "<p>\n";
echo "<strong>First result</strong><br />\n";
if (!empty($locations) && is_array($locations)) {
  foreach ($locations as $field => $val) {
    echo $field . ' : ' . $val . "<br />\n";
  }
}
echo "</p>\n";
 
//Show errors
echo "<p>\n";
echo "<strong>Dump of all errors</strong><br />\n";
if (!empty($errors) && is_array($errors)) {
  foreach ($errors as $error) {
    echo var_dump($error) . "<br /><br />\n";
  }
} else {
  echo "No errors" . "<br />\n";
}
echo "</p>\n";
Putting the geolocation data in a cookie
If you use our API to track your website visitors geolocation, we highly recommend that you put the geolocation data in a cookie (or in a database...). This way, you only query our servers for new visitors, not all page view. To achieve this, here is a quick sample in PHP how to set the country code in a cookie :
<?php
include_once('ip2locationlite.class.php');
 
//Set geolocation cookie
if(!$_COOKIE["geolocation"]){
  $ipLite = new ip2location_lite;
  $ipLite->setKey('<your_api_key>');
 
  $visitorGeolocation = $ipLite->getCountry($_SERVER['REMOTE_ADDR']);
  if ($visitorGeolocation['statusCode'] == 'OK') {
    $data = base64_encode(serialize($visitorGeolocation));
    setcookie("geolocation", $data, time()+3600*24*7); //set cookie for 1 week
  }
}else{
  $visitorGeolocation = unserialize(base64_decode($_COOKIE["geolocation"]));
}
 
var_dump($visitorGeolocation);
ASP example
<%
	'Get visitor IP
	Dim UserIPAddress
	UserIPAddress = Request.ServerVariables("HTTP_X_FORWARDED_FOR")
	If UserIPAddress = "" Then
	 UserIPAddress = Request.ServerVariables("REMOTE_ADDR")
	End If
%>
<%
	'Set API key
	api_key = "<your_api_key>"
%>
<%
	'Get info and print
	myxml="http://api.ipinfodb.com/v3/ip-city/?key="&api_key&"&ip=" &UserIPAddress&"&format=xml"
	set xml = server.CreateObject("MSXML2.DOMDocument.6.0")
	xml.async = "false"
	xml.resolveExternals = "false"
	xml.setProperty "ServerHTTPRequest", true
	xml.load(myxml)
	response.write "<p><strong>First result</strong><br />"
	for i=0 to 10
		response.write xml.documentElement.childNodes(i).nodename & "  :  "
		response.write xml.documentElement.childNodes(i).text & "<br/>"
	NEXT
	response.write "</p>"
%> 
Accents encoding

Depending on the locales of your server, you might have trouble displaying accent in country, region and city name. Using PHP, you might need to utf8_encode the answer from our API. For other languages, look at the documentation how to encode in UTF-8.

Query limit

We do not have a specific daily limit but queries that are at a rate faster than 2 per second will be put in "queue". If you stay below 2 queries/second everything will be normal. If you go over the limit, you will still get an answer for all queries but they will be slowed down to about 1 per second. Good programming practices such as not querying our API for all page views (you can store the data in a cookie or a database) will also help not reaching the limit.

If you need to perform more queries in website, it is better implement a local database query using IP2Location LITE. It is free for personal or commercial use with attribution required.

Keeping in touch for updates

The best way to get updates and news is with our RSS feed or on Twitter