Batch IP Locator

Geocode and map multiple IP addresses - free

What do you think?

Localize your site with the Locator API!

Seeing your location here on this map is cool, but wouldn't it be great if you could have it on your own site or blog? Well, you can! The Locator API is designed to provide you the same data you see here, neatly packaged for use on your own site (for free, of course).

Uses

So what if I can geocode my users' IP addresses on my page? What good is that to me? Here's a few ideas of how to use the Locator API:

  1. Surprise your users by asking "How're things in [user's city here]?"
  2. Keep your own site statistics on your server (ie in a MySQL database), granting you full access to the data
  3. Display localized news feeds based on your user's location immediately when they enter your site, without any action on the part of the user
  4. Create a tailor-made map of your site visitors

How?

So how do you install it? You don't need to. The Locator API allows you to integrate geographic data about your user into any site that allows javascript, including your blog. The beauty of this API is that you can literally copy-and-paste your way to a localized page. I've created a test page that you are free to dissect and use on your site. The Locator API can be accessed with the following URL: 

http://batchiplocator.webatu.com/api/locate.php

The HTML File

Here's the full HTML of the test page: 



<html>

<head>
  <script type="text/javascript" src="http://ajax.googleapis.com/ajax/libs/jquery/1.3.2/jquery.min.js"></script>
  <script type="text/javascript" src="http://batchiplocator.webatu.com/api/locate.php?method=js"></script>
  <script type='text/javascript'><!--
        function testSend() {
            var url = 'http://batchiplocator.webatu.com/api/locate.php?method=ajax&callback=?';
            $.getJSON(url,function(place) {
                $('#ipboxout').append('AJAX: ' + place.ip + ': ' + place.city + ' ' + place.country + '<br />' + place.lat + ', ' + place.lng + '<br />');

            });
        }
      
        function testJS() {
                $('#ipboxout').append('JS: ' + place.ip + ': ' + place.city + ' ' + place.country + '<br />' + place.lat + ', ' + place.lng + '<br />');
        }
      
  --></script>
</head>
<body>
<a href='../api'><-- back</a>
<input type=button value=TestAJAX onclick='testSend();'></input>
<input type=button value=TestJS onclick='testJS();'></input>
<div id='ipboxout' ></div>

</body>
</html>
The test page shows how to request the data using both JQuery and plain javascript. I am a huge fan of JQuery, because it's a javascript library that simplifies almost all of your javascript needs, including AJAX calls. Let's walk through both processes separately, starting with an AJAX call.

Method 1: The AJAX Call

In the Head element, I bring the JQuery library into my page from Google's code pages. Then I create a simple function to make the request, using the built-in "getJSON" to make sure I have cross-domain clearance, which will call for the data and append it to the "ipboxout" element. The callback function for the "getJSON" call displays each of its members in the appended text.

Notice the "method" argument in the URL is set to "ajax" to make sure that data is packaged correctly (as a JSONP object, as required by JQuery), and "callback" is set to "?" (allowing JQuery to assign a name to the object, which I later call "place" in the callback function). No IP address was set in the URL, so it returns the user's IP address.

This method should work in the majority of scenarios, and is ideal for applications that may request data for several different IP addresses on the same page, as the call is made behind the scenes without a page refresh. Depending on the user's connection, and the server load, there may be a momentary pause before the data is returned.

Method 2: Plain Javascript

Now for the plain javascript method. In the Head element, I bring in the javascript object directly to the page, by adding a "script" element and setting the Locator API URL to the "src" attribute. I then create a simple javascript function to display the object members and append them to the "ipboxout" element. The javascript object, complete with your user's geographic data, is loaded into your page as if you had coded it in the first place!

Notice the "method" argument is set to "js" to make sure the data is packaged correctly (as a JSON object ready to be used). "Callback" and "ip" are not set, meaning the user's IP address is used and the default name is assigned to the object ("place").

This method is simpler, does not require AJAX calls or libraries, and is initially faster. However, the javascript is loaded directly into the page, so each request will require a page reload.

Extra Information

The above should be sufficient to start implementing the Locator API on your site. For more detailed information about the API, see below.

The Request

The request takes three arguments, as outlined below (default, if not set, is in parentheses):

  1. ip: (user's IP) The target IP address to be geocoded. Accepts one IP address (alone, with no port number or anything on the end) at a time
  2. method: ("ajax") Method by which the object will be called. Accepts 'ajax' or 'js' - returning slightly different objects (see below)
  3. callback: ("place") Callback of the object (whatever you want to name it)

The JSON Object

The Locator API returns a JSON object containing the IP address, city, country, latitude and longitude of the given IP address. This data can be accessed using the following properties (given the default callback, "place"):

  1. place.ip
  2. place.city
  3. place.country
  4. place.lat
  5. place.lng

AJAX Method

When "method" is set to "ajax" the object returned is wrapped in parentheses, otherwise known as JSON with Padding or just JSONP. This allows the javascript to be passed across different domains without any fancy proxies or flash requirements. Requesting the following URL 

http://batchiplocator.webatu.com/api/locate.php?ip=64.233.173.200&method=ajax&callback=?
will return the following JSONP object 
place({"ip":"64.233.173.200","city":"Mountain View","country":"United States","lat":37.4192,"lng":-122.0574});

JS Method

When "method" is set to "js" the object returned is a plain javascript object that has been instantiated and is ready to go. The following URL 

http://batchiplocator.webatu.com/api/locate.php?ip=64.233.173.200&method=js
would return the following JSON object 
var place = {ip: "64.233.173.200",city: "Mountain View",country: "United States",lat: "37.4192",lng: "-122.0574"}

home |  blog |  geolite