Get City Details

The Geobytes Get City Details API is the free version of our legacy IP Locator API. You can use it to to programmatically determine the service area of an IP Address.

In PHP, for example you might access this service like this:

  
   function getIP() {
      foreach (array('HTTP_CLIENT_IP', 'HTTP_X_FORWARDED_FOR', 'HTTP_X_FORWARDED', 'HTTP_X_CLUSTER_CLIENT_IP', 'HTTP_FORWARDED_FOR', 'HTTP_FORWARDED', 'REMOTE_ADDR') as $key) {
         if (array_key_exists($key, $_SERVER) === true) {
            foreach (explode(',', $_SERVER[$key]) as $ip) {
               if (filter_var($ip, FILTER_VALIDATE_IP) !== false) {
                  return $ip;
               }
            }
         }
      }
   }

$tags=json_decode(file_get_contents('http://getcitydetails.geobytes.com/GetCityDetails?fqcn='. getIP()), true);
if($tags['geobyteslocationcode']!='')
{
    echo '
Welcome to visitors from '.$tags['geobytesfqcn'].'. '.PHP_EOL ;
}
print_r($tags);
echo PHP_EOL ;
print_r($tags[geobytescity]);
echo PHP_EOL.'
The value of GeobytesCity is:'.$tags[geobytescity].'
';

Which produces an output of something like this:

More than just resolves the location of IP Addresses

In addition to resolving the location of IP Addresses, the Get City Details API can accept a Geobytes Location Code (which you can lookup here), – as in this example:

$tags=json_decode(file_get_contents('http://getcitydetails.geobytes.com/GetCityDetails?fqcn=USNYNYOR', true);
if($tags['geobyteslocationcode']!='')
{
    echo '
USNYNYOR is the Geobytes Location Code for '.$tags['geobytesfqcn'].'. '.PHP_EOL ;
}
print_r($tags);
echo PHP_EOL ;
print_r($tags[geobytescity]);

or a fully qualified city name – as in this example:

$tags=json_decode(file_get_contents('http://getcitydetails.geobytes.com/GetCityDetails?fqcn=San%20Francisco,%20CA,%20United%20States', true);
if($tags['geobyteslocationcode']!='')
{
    echo '
San Francisco, CA, United States is the fully qualified city name for '.$tags['geobytesfqcn'].'. '.PHP_EOL ;
}
print_r($tags);
echo PHP_EOL ;
print_r($tags[geobytescity]);

or a Latitude and Longitude – as in this example where we are using it to GeoCode to the nearest city:

$tags=json_decode(file_get_contents('http://getcitydetails.geobytes.com/GetCityDetails?callback=?&latitude=40.7487&longitude=-73.9845', true);
if($tags['geobyteslocationcode']!='')
{
    echo '
40.7487 and -73.9845 are the latitude and longitude for '.$tags['geobytesfqcn'].'. '.PHP_EOL ;
}
print_r($tags);
echo PHP_EOL ;
print_r($tags[geobytescity]);


BTW If you would like to see a live real life example, then there is not a lot of point viewing the source of this page, as although this page does use the above example to populate the city details above, this is a server side example so you can’t see it in this page’s source.

However, because the Get City Details API also supports returning the city’s details in JSON-P format, you can also use it client side by setting the “callback” parameter – and our Ajax Autocomplete Cities List page does just this – in that case you can view the source of the page to see how the two APIs are working together to provide the user with a facility to select a city from a list, and then to display that city’s details in a web form.

Optional Default Location Parameter

Finally, there is one optional parameter that you can use to set the default location that the API will return in the 1% or so of cases where our server is unable to determine location of the IP Address. The default location is set via the “defaultlocation” parameter as shown in this example:

  
   function getIP() {
      foreach (array('HTTP_CLIENT_IP', 'HTTP_X_FORWARDED_FOR', 'HTTP_X_FORWARDED', 'HTTP_X_CLUSTER_CLIENT_IP', 'HTTP_FORWARDED_FOR', 'HTTP_FORWARDED', 'REMOTE_ADDR') as $key) {
         if (array_key_exists($key, $_SERVER) === true) {
            foreach (explode(',', $_SERVER[$key]) as $ip) {
               if (filter_var($ip, FILTER_VALIDATE_IP) !== false) {
                  return $ip;
               }
            }
         }
      }
   }

$tags=json_decode(file_get_contents('http://getcitydetails.geobytes.com/GetCityDetails?defaultlocation=USNYNYOR&fqcn='. getIP()), true);
if($tags['geobyteslocationcode']!='')
{
    echo '
Welcome to visitors from '.$tags['geobytesfqcn'].'. '.PHP_EOL ;
}
print_r($tags);
echo PHP_EOL ;
print_r($tags[geobytescity]);
echo PHP_EOL.'
The value of GeobytesCity is:'.$tags[geobytescity].'
';

Example using curl and grep

curl -s http://getcitydetails.geobytes.com/GetCityDetails?fqcn=67.162.105.1 | grep -oP '(?<="geobytesfqcn":")[^"]*'

returns

Chicago, IL, United States

Reasonable Free Access Limits

If you expect to exceed the services “Reasonable Free Access Limit” of 16,384 accesses per hour, (about 4.5 look-ups per second), or wish to access the service via SSL, then you may wish to purchase some Mapbytes to pay for these additional look-ups, and thereby become a VIP.

VIP Access does have its advantages. In addition to being able to exceed the free quoter limits mentioned above, VIP clients also receive:

  • SSL Access to all of our API’s
  • Email Notification of Events that could impact their access
  • Email Support
  • VIP Priority handling of their API requests

You can become a VIP by purchasing as little as $9.99 worth of Mapbytes via the Buy Now Buttons in the right margin – that by the way works out at about 1/100th of a cent per request or 10,000 requests per dollar.

– because everybody's somewhere