A couple of days I was doing some work on BeWelcome, updating some code to fetch geo data from Geonames.org. Our old code had been using a mixture of a spaf maps class and php functions and trying to get it to work properly seemed to demand quite a bit of tinkering - plus, there was the chance I might break something. I then had a look at the Geonames site and there are quite a few different libraries for querying Geonames - but nothing in plain PHP. However, looking at the documentation of their API it didn't seem like it would be very hard to knock something up - so that's what I did.

After about 2 hours of coding, I had some very basic classes that provide the most useful functionality of Geonames (useful for BeWelcome anyway): doing a fulltext wildcard search, fetching details for one specific location, and fetching hierarchies of locations. The library provides some static functions for generating location objects, and these location objects can then in turn be worked with using some of the same methods that the library provides (such as getting child locations or parent locations).

The usage is currently extremely simple - some examples:

// searching for a location
$results = GeoNamesService::search($searchterm, $rowcount /* optional, defaults to 100 */);

// fetching parent hierarchy for a location
$hierarchy = GeoNamesService::hierarchy($id);

// getting the parent of an existing GeoNamesObject
$parent = $geo_object->getParent();

As you can probably guess, the main reasoning was taking out the boilerplate code and removing the stuff we just didn't use. As a consequence, this library doesn't currently offer that much extra functionality. This will be built in later though, so you're able to use some of the options when searching, for instance. Also, a number of the other ways of interacting with Geonames are worth looking at, like finding a location by postcode.

After I had spent a bit of time on the project and got it to a working basic (including some unit-tests), I figured I'd breathe some life into it and so I put it on GitHub - so anyone can take it and use it if they have a need for it. It's available here: PHP Geonames Library and the license is a GPL v.3 so you can just grab and use in any OS project as you see fit.