README.markdown

what-ip.heroku.com API

what-ip.heroku.com simple yet complete API will let your applications know everything about an IP address, from hostname to its geolocation. It is available through HTTP GET requests, free and unlimited.

Usage

• Caller (your) IP in JSON: /host.json
• Caller (your) IP in XML: /host.xml
• Caller (your) IP in plain text: /host.txt
• Given IP in JSON: /ip/66.249.92.104.json
• Given IP in XML: /ip/66.249.92.104.xml
• Given IP in plain text: /ip/66.249.92.104.txt

JSONP

You may provide a callback query string parameter when using JSON to achieve cross-domain requests in web browsers (a technique commonly known as JSONP). The response will be a JavaScript call to the function whose name was given as callback, with the original JSON object as argument.

Check this example if you're not familiar with this technique.

Example

<script>
  function responseReceived(response) {
    alert("Your IP Address is: " + response.host.ipv4);
  }
</script>
<script src="http://what-ip.heroku.com/host.json?callback=responseReceived"></script>

example.json

{
  "host": {
    "ipv4": "123.45.67.89",
    "hostname": "the.host.name", // or `null` if reverse DNS lookup failed
    "address": {
      /* if IP is in a private range (e.g. 192.168.0.1) */
      "city": "private",
      "country": "private"
      "geo": {
        "latitude": null,
        "longitude": null
      }
      /* otherwise
        (depending on geocoding accuracy, any of these may be `null`) */
      "city": "The City",
      "country": "THE COUNTRY (CODE)",
      "geo": {
        "latitude": 12.3456,
        "longitude": 34.5678
      }
    }
  }
}

example.xml

<?xml version="1.0" encoding="UTF-8"?>
<host>
  <ipv4>123.45.67.89</ipv4>
  <!-- if reverse DNS lookup succeeds -->
  <hostname>the.host.name</hostname>
  <!-- otherwise -->
  <hostname nil="true"></hostname>
  <!-- end -->
  <address>
    <!-- if IP is in a private range (e.g. 192.168.0.1) -->
    <city type="symbol">private</city>
    <country type="symbol">private</country>
    <geo>
      <latitude nil="true"></latitude>
      <longitude nil="true"></longitude>
    </geo>
    <!-- otherwise
      (depending on geocoding accuracy, any of these may be empty with `nil="true"`) -->
    <city>The City</city>
    <country>THE COUNTRY (CODE)</country>
    <geo>
      <latitude type="float">12.34567</latitude>
      <longitude type="float">34.56789</longitude>
    </geo>
  </addr>
</host>

plain_text_example.sh

ipv4: 123.45.67.89
# Any of the following may be empty if anything fails
hostname: the.host.name
city: The City
country: THE COUNTRY (CODE)
latitude: 12.34567
longitude: 34.56789