Getting started
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
| 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 |
| 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.