IP location JSON API

IP Address Geolocation JSON API

The API returns the location of an IP address (country, region, city, zipcode, latitude and longitude) and the associated timezone in JSON format.

Usage

For city precision, simply do a query at this address (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&format=json

For country precision (faster), simply do a query with the following API :

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

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)

Output

This is a sample of the output you will get in JSON with city precision :

{
	"statusCode" : "OK",
	"statusMessage" : "",
	"ipAddress" : "74.125.45.100",
	"countryCode" : "US",
	"countryName" : "UNITED STATES",
	"regionName" : "CALIFORNIA",
	"cityName" : "MOUNTAIN VIEW",
	"zipCode" : "94043",
	"latitude" : "37.3956",
	"longitude" : "-122.076",
	"timeZone" : "-08:00"
}

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 be 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.

Javascript example

In this example, the geolocation data is stored as serialized JSON in a cookie after the first query. You can download a jQuery version of the script as well.

<html>
<head>
<script type="text/javascript">
//IPInfoDB javascript JSON query example
//Tested with FF 3.5, Opera 10, Chome 5 and IE 8
//Geolocation data is stored as serialized JSON in a cookie
//Bug reports : http://forum.ipinfodb.com/viewforum.php?f=7
function geolocate(timezone, cityPrecision, objectVar) {
 
  var api = (cityPrecision) ? "ip-city" : "ip-country";
  var domain = 'api.ipinfodb.com';
  var url = "http://" + domain + "/" + api + "/?key=<your_api_key>&format=json" + "&callback=" + objectVar + ".setGeoCookie";
  var geodata;
  var callbackFunc;
  var JSON = JSON || {};
 
  // implement JSON.stringify serialization
  JSON.stringify = JSON.stringify || function (obj) {
    var t = typeof (obj);
    if (t != "object" || obj === null) {
      // simple data type
      if (t == "string") obj = '"'+obj+'"';
        return String(obj);
    } else {
    // recurse array or object
      var n, v, json = [], arr = (obj && obj.constructor == Array);
      for (n in obj) {
        v = obj[n]; t = typeof(v);
        if (t == "string") v = '"'+v+'"';
        else if (t == "object" && v !== null) v = JSON.stringify(v);
        json.push((arr ? "" : '"' + n + '":') + String(v));
      }
      return (arr ? "[" : "{") + String(json) + (arr ? "]" : "}");
    }
  };
 
  // implement JSON.parse de-serialization
  JSON.parse = JSON.parse || function (str) {
    if (str === "") str = '""';
      eval("var p=" + str + ";");
      return p;
  };
 
  //Check if cookie already exist. If not, query IPInfoDB
  this.checkcookie = function(callback) {
    geolocationCookie = getCookie('geolocation');
    callbackFunc = callback;
    if (!geolocationCookie) {
      getGeolocation();
    } else {
      geodata = JSON.parse(geolocationCookie);
      callbackFunc();
    }
  }
 
  //API callback function that sets the cookie with the serialized JSON answer
  this.setGeoCookie = function(answer) {
    if (answer['statusCode'] == 'OK') {
      JSONString = JSON.stringify(answer);
      setCookie('geolocation', JSONString, 365);
      geodata = answer;
      callbackFunc();
    }
  }
 
  //Return a geolocation field
  this.getField = function(field) {
    try {
      return geodata[field];
    } catch(err) {}
  }
 
  //Request to IPInfoDB
  function getGeolocation() {
    try {
      script = document.createElement('script');
      script.src = url;
      document.body.appendChild(script);
    } catch(err) {}
  }
 
  //Set the cookie
  function setCookie(c_name, value, expire) {
    var exdate=new Date();
    exdate.setDate(exdate.getDate()+expire);
    document.cookie = c_name+ "=" +escape(value) + ((expire==null) ? "" : ";expires="+exdate.toGMTString());
  }
 
  //Get the cookie content
  function getCookie(c_name) {
    if (document.cookie.length > 0 ) {
      c_start=document.cookie.indexOf(c_name + "=");
      if (c_start != -1){
        c_start=c_start + c_name.length+1;
        c_end=document.cookie.indexOf(";",c_start);
        if (c_end == -1) {
          c_end=document.cookie.length;
        }
        return unescape(document.cookie.substring(c_start,c_end));
      }
    }
    return '';
  }
}
</script>
</head>
 
<body>
<script type="text/javascript">
//function geolocate(timezone, cityPrecision, objectVar).
//If you rename your object name, you must rename 'visitorGeolocation' in the function
var visitorGeolocation = new geolocate(false, true, 'visitorGeolocation');
 
//Check for cookie and run a callback function to execute after geolocation is read either from cookie or IPInfoDB API
var callback = function(){
                alert('Visitor country code : ' + visitorGeolocation.getField('countryCode'))
               };
visitorGeolocation.checkcookie(callback);
</script>
</body>
</html>

Examples

Another jQuery example

If you find or write examples in other languages, please post them in the forum.

Accents encoding

Depending on the locales of your server, you might have trouble diplaying 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.

Keeping in touch for updates

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