Home » Web Services » Services_GeoNames » Manual

Introduction

Introduction – introduction to the Services_GeoNames package

Introduction

Services_GeoNames is a PHP interface to the various webservices offered by the GeoNames project.

The GeoNames database contains over 8,000,000 geographical names corresponding to over 6,500,000 unique features. All features are categorized into one out of nine feature classes and further subcategorized into one out of 645 feature codes. Beyond names of places in various languages, data stored include latitude, longitude, elevation, population, administrative subdivision and postal codes. All coordinates use the WGS84 system (World Geodetic System 1984).

Those data are accessible free of charge through a number of Web services and a daily database export. The Web services include direct and reverse geocoding, finding places through postal codes, finding places next to a given place, and finding Wikipedia articles about neighbouring places.

Installation

To install the package with pear just do:

$ pear install -f Services_GeoNames

And to uninstall it:

$ pear uninstall Services_GeoNames

Links

• GeoNames project homepage
• GeoNames API documentation.

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

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.

Examples

Examples – various code examples

Search for all cities named Paris

<?php
require_once 'Services/GeoNames.php';

$geo = new Services_GeoNames();

$cities = $geo->search(array('name_equals' => 'Paris'));
echo "List of cities named Paris:\n";
foreach($cities as $city) {
    printf(" - %s (%s)\n", $city->name, $city->countryName);
}
echo "\n";

?>

Find all postal codes near by Toulouse in a radius of 10km

<?php

require_once 'Services/GeoNames.php';

$geo = new Services_GeoNames();

$postalCodes = $geo->findNearbyPostalCodes(array(
    'lat'     => 43.606,
    'lng'     => 1.444,
    'radius'  => 10, // 10km
    'maxRows' => 100
));
echo "List of postal codes near by Toulouse in a radius of 10km:\n";
foreach ($postalCodes as $code) {
    printf(" - %s (%s)\n", $code->postalCode, $code->placeName);
}
echo "\n";

?>

List all countries and capitals in spanish

<?php
require_once 'Services/GeoNames.php';

$geo = new Services_GeoNames();
$countries = $geo->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);
}
echo "\n";

?>

List neightbours countries of France

<?php
require_once 'Services/GeoNames.php';

$geo = new Services_GeoNames();

// retrieve the geonameId if we don't know it
$array     = $geo->countryInfo(array('country' => 'FR'));
$geonameId = $array[0]->geonameId;

$neighbours = $geo->neighbours(array('geonameId' => $geonameId));
echo "Neighbours of France are:\n";
foreach ($neighbours as $neighbour) {
    printf(" - %s\n", $neighbour->countryName);
}

?>