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. It can be used to query up to 25 IP for a single lookup. You can find below code samples with Javascript.

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://ipinfodb.com/ip_query.php?ip=74.125.45.100&output=json&timezone=false

You can also add the optional callback parameter :

http://ipinfodb.com/ip_query.php?ip=74.125.45.100&output=json&callback=myfunction&timezone=false

To add timezone data, simply set the timezone parameter to true

http://ipinfodb.com/ip_query.php?ip=74.125.45.100&output=json&timezone=true

For multiples lookups (up to 25) in one request, the following API can be used :

http://ipinfodb.com/ip_query2.php?ip=74.125.45.100,206.190.60.37&output=json&timezone=false

Using the second API you can also replace IP addresses with domain names (note : 1 second pause for each domain) :

http://ipinfodb.com/ip_query2.php?ip=ebay.com,google.com&output=json&timezone=false

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

http://ipinfodb.com/ip_query_country.php?ip=74.125.45.100&output=json

If you use this service on a regular basis, please consider making a donation. Our API are totally free but we need donations in order to pay for hosting and our 3 dedicated servers.

API list

API	Precision	Multiple request	Timezone	Domains lookups
ip_query.php	city	no	yes	no
ip_query2.php	city	yes (25)	yes	yes
ip_query_country.php	country	no	no
ip_query2_country.php	country	yes	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 do one IP request at a time, use ip_query.php instead of ip_query2.php
If you don't need timezone data, set the timezone parameter to false (timezone=false) because it requires 2 additionnal queries on our side
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 :

{
  "Ip" : "74.125.45.100",
  "Status" : "OK",
  "CountryCode" : "US",
  "CountryName" : "United States",
  "RegionCode" : "06",
  "RegionName" : "California",
  "City" : "Mountain View",
  "ZipPostalCode" : "94043",
  "Latitude" : "37.4192",
  "Longitude" : "-122.057"
}

Or with the optionnal "timezone=true" parameter, you will get the current GMT offset (in seconds!) of the location :

{
  "Ip" : "74.125.45.100",
  "Status" : "OK",
  "CountryCode" : "US",
  "CountryName" : "United States",
  "RegionCode" : "06",
  "RegionName" : "California",
  "City" : "Mountain View",
  "ZipPostalCode" : "94043",
  "Latitude" : "37.4192",
  "Longitude" : "-122.057",
  "TimezoneName" : "America/Los_Angeles",
  "Gmtoffset" : "-28800",
  "Isdst" : "0"
}

Data accuracy

Over 99.5% on a country level and around 80% on a city level for the US within a 25 mile radius. The database used for this API is compiled from the free Maxmind CSV database (Geolite City) and rearranged with many scripts.

You can try a few lookups with our IP locator.

Servers location and uptime

We have 3 servers. Two are are load balanced & highly available (ldirectord + heartbeat setup). They are located in Montreal, Canada and used for the primary domain (ipinfodb.com). We also have a third server located in Los Angeles, US (backup.ipinfodb.com or us.ipinfodb.com). It can be used as the first server you query but keep in mind that it's not redundant as our main server in case of hardware failure. Our goal is to have over 99.99% uptime on the main server. 100% uptime can be reached by adding a failover server (eg backup.ipinfodb.com) in your code.

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_query.php" : "ip_query_country.php";
  var domain = 'ipinfodb.com';
  var url = "http://" + domain + "/" + api + "?output=json" + ((timezone) ? "&timezone=true" : "&timezone=false" ) + "&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['Status'] == '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. This should not affect most users but for high volume websites, you can either use our IP database on your server or we can whitelist your IP for 5$/month (simply use the donate form and leave a comment with your server IP). 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.

API source code

You can find the code of the APIs on this page

Keeping in touch for updates

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

Support

For all non googable questions, visit the forum. We also offer custom integration.

Free IP address geolocation tools