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.