Getting started

Getting started – getting started with the Services_GeoNames package

Instanciating the Services_GeoNames class

To instanciate the main class just do:

<?php

require_once 'Services/GeoNames.php';

$geo = new Services_GeoNames();

?>

And if you have a commercial account:

<?php

require_once 'Services/GeoNames.php';

$geo = new Services_GeoNames('your_username', 'your_authtoken');

?>

Using Services_GeoNames methods

To call a webservice method, just instanciate the class as described above and call the desired method with an array of parameters, for example:

<?php

require_once 'Services/GeoNames.php';

$geonames  = new Services_GeoNames('username''some authtoken...');
$countries $geonames->countryInfo(array('lang' => 'es'));
echo 
"List of all countries in spanish language:\n";
foreach (
$countries as $country) {
    
printf(" - %s (capital: %s)\n"$country->countryName$country->capital);
}

?>

Every method take an array as single parameter, for example in the GeoNames API documentation when you see something like:

Webservice Type : REST
Url : ws.geonames.org/citiesJSON?
Parameters :
north,south,east,west : coordinates of bounding box
callback : name of javascript function (optional parameter)
lang : language of placenames and wikipedia urls (default = en)
maxRows : maximal number of rows returned (default = 10)

That means that you can call the cities() method as follows:

<?php

require_once 'Services/GeoNames.php';

$geo    = new Services_GeoNames();
$cities $geo->cities(array(
    
'north'   => 44.1,
    
'south'   => -9.9,
    
'east'    => -22.4,
    
'west'    => 55.2,
    
'lang'    => 'de',
    
'maxRows' => 5,
));

?>

Note that for convenience, some methods can take a geonameId (integer) instead of the array as unique parameter, for example, the following two calls are equivalent:

<?php

require_once 'Services/GeoNames.php';

$geo = new Services_GeoNames();

// theses two method calls are equivalent
$children $geo->children(3175395);
$children $geo->children(array('geonameId' => 3175395));

?>

Available methods

API methods
Method name Parameters Return type
children() int geonameId or array array
cities() int geonameId or array array
countryCode() array stdclass
countryInfo() array array
countrySubdivision() array stdclass
earthquakes() array array
findNearby() array array
findNearbyPlaceName() array array
findNearbyPostalCodes() array stdclass
findNearbyStreets() array array
findNearByWeather() array stdclass
findNearbyWikipedia() array array
findNearestAddress() array stdclass
findNearestIntersection() array stdclass
get() array stdclass
gtopo30() array stdclass
hierarchy() int geonameId or array array
neighbourhood() array stdclass
neighbours() int geonameId or array array
postalCodeCountryInfo()   array
postalCodeLookup() array array
postalCodeSearch() array stdclass
search() array array
siblings() int geonameId or array array
srtm3() array stdclass
timezone() array stdclass
weather() array array
weatherIcao() array stdclass
wikipediaBoundingBox() array array
wikipediaSearch() array array
Non API methods
Method name Parameters Return type Description
Services_GeoNames::getSupportedEndpoints()   array returns an array of all supported services endpoints (aka methods)
Services_GeoNames::getRequest()   HTTP_Request2 returns the HTTP_Request2 request instance
Services_GeoNames::setRequest() HTTP_Request2   sets the HTTP_Request2 request instance

Handling exceptions

Services_GeoNames always raise either a Services_GeoNames_Exception or a Services_GeoNames_HTTPException instance, if you don't care of fine grained exceptions, you can just catch the Services_GeoNames_Exception, as it's the parent class of the Services_GeoNames_HTTPException. Here's an example of fine grained exception handling:

<?php

require_once 'Services/GeoNames.php';

$geo = new Services_GeoNames();

// now geonames uses your url
try {
    
$children $geo->children(3175395);
} catch (
Services_GeoNames_HTTPException $exc) {
    
// an http error occured
    
echo "HTTP error: " $exc->getMessage();
} catch (
Services_GeoNames_Exception $exc) {
    
// a programming error or an api error occured
    
echo "API error: " $exc->getMessage();
}

?>

Changing the default service url and adding failover servers

If for some reason you need to change the web service url, you can do the following:

<?php

require_once 'Services/GeoNames.php';

$geo = new Services_GeoNames();
$geo->url 'http://alternate.geonames.org';

// now geonames uses your url
try {
    
$children $geo->children(3175395);
} catch (
Services_GeoNames_Exception $exc) {
    echo 
"Failed: " $exc->getMessage();
}

?>

If you need high availability or if you are using the commercial version of the web services, Services_GeoNames allows you to specify an array of failover servers, you would just do:

<?php

require_once 'Services/GeoNames.php';

$geo = new Services_GeoNames();
$geo->failoverServers[] = 'http://failover1.geonames.org';
$geo->failoverServers[] = 'http://failover2.geonames.org';
$geo->failoverServers[] = 'http://failover3.geonames.org';

// now geonames will try the main url and if it fails, it will loop through
// the failovers servers you have just configured
try {
    
$children $geo->children(3175395);
} catch (
Services_GeoNames_Exception $exc) {
    echo 
"Failed: " $exc->getMessage();
}

?>

Customizing the http request

If you need a custom request, for example if you are behind a proxy, you can modify the Services_GeoNames request instance, for example:

<?php

require_once 'Services/GeoNames.php';
$geo = new Services_GeoNames();

// customize the http request
$geo->getRequest()->setConfig(array(
    
'proxy_host' => 'localhost',
    
'proxy_port' => 8118,
));

// now geonames uses your proxy
try {
    
$children $geo->children(3175395);
} catch (
Services_GeoNames_Exception $exc) {
    echo 
"Failed: " $exc->getMessage();
}

?>

For more infos please read the HTTP_Request2 documentation.