1. Introduction
2. Requirements
3. Usage
4. Examples of Usage
5. Resources
6. Change Log

Introduction ¶

EGeoNameService is a client library to access the JSON Web services offered by http://www.geonames.org. A full overview of the methods provided by the Web service and its results can be viewed at http://www.geonames.org/export/ws-overview.html.

This class is perfect when we want to start a geolocation application and don't have the required database to support the services and in combination with EGMap Extension.

I have created a GitHub repository for those willing to contribute on any of the extensions I created. Please, check the link at the bottom of this wiki.

Requirements ¶

Developed with Yii 1.1.7

Usage ¶

Unzip and extract the contents on your extensions folder. After you can configure your main.php to preload it or just by using Yii::import.

In order to make use of the Geonames.org you are required to register on their site to get a username. The services are free and your username is required to keep track for the requests. 30'000 credits is the daily limit per application (identified by the parameter 'username'), the hourly limit is 2000 credits. More information at geonames.

The class parses Geonames.org JSON response and converts the first level array elements to objects of type EGeoNameResult in order to easy the access of the response and provide better code reading.

Please review the following code:

/* For a response like this
 {
  "languages": "de-AT,hr,hu,sl",
  "distance": 0,
  "countryName": "Austria",
  "countryCode": "AT"
} */

// You can access it this way
echo $egeobject->languages;

/* For a response like this
  {"geonames": [{
  "adminCode3": "3333",
  "adminCode2": "1726",
  "countryName": "Switzerland",
  "adminCode1": "SG",
  "fclName": "city, village,...",
  "elevation": 0,
  "countryCode": "CH",
  "lng": 8.988454,
  "adminName2": "Wahlkreis See-Gaster",
  "adminName3": "Goldingen",
  "fcodeName": "populated place",
  "distance": "1.62758",
  "adminName4": "",
  "timezone": {
    "dstOffset": 2,
    "gmtOffset": 1,
    "timeZoneId": "Europe/Zurich"
  },
  "toponymName": "Atzmännig",
  "fcl": "P",
  "continentCode": "EU",
  "name": "Atzmännig",
  "fcode": "PPL",
  "geonameId": 6559633,
  "lat": 47.287633,
  "adminName1": "Sankt Gallen",
  "population": 0
}]}*/

// You access the results like this
// Please see how array elements of top
// result is converted as the root elements
// but not the rest
echo $egeobject->geonames[0]->distance;
echo $egeobject->geonames[0]->timezone['timeZoneId'];

// The component also returns the results of the call as an array.
// So if you are not happy with the object acces style.
$results = $egeobject->postalCodeSearch(array('postalcode'=>'07800','country'=>'ES'));

echo $results['postalCodes'][0]['adminName2'];

Every function call requires some parameters, in order to easy the task of a programmer to find out which parameters are required and/or optional, the class has been very well documented in its code.

You pass the required parameters by passing an key named array to the method. For example:

$result = $egeo->astergdem(array('lat'=>'50.01','lng'=>'10.2'));

Examples of Usage ¶

Yii::import('ext.egeonames.*');
		
$egeo = new EGeoNameService();
$egeo->username = 'demo'; // your username

$egeo->countryCode(array('lat'=>'47.03','lng'=>'10.2'));
echo $egeo->languages.', '.$egeo->countryName.', '.$egeo->countryCode;
		
$egeo->countryInfo(array('country'=>'DE','lang'=>'es');
echo $egeo->geonames[0]->countryName;
		
$egeo->countrySubdivision(array('lat'=>'47.03','lng'=>'10.2'));
echo $egeo->countryName.'<br/>';
echo $egeo->codes[0]['type'];
		
$egeo->earthquakes(array('north'=>'44.1','south'=>'-9.9','east'=>'-22.4','west'=>'55.2'));
echo $egeo->earthquakes[0]->eqid;
		
$egeo->findNearby(array('lat'=>'48.865618158309374','lng'=>'2.344207763671875'));//,));
echo $egeo->geonames[0]->countryName;
		
$egeo->findNearbyPlaceName(array('lat'=>'47.3','lng'=>'9'));
echo $egeo->geonames[0]->countryCode;
		
$egeo->findNearbyPostalCodes(array('postalcode'=>'07300','country'=>'ES','radius'=>10));
echo $egeo->postalCodes[1]->postalCode;

Resources ¶

• GitHub repository
• Project page
• Geonames.org
• Forum Post

Change Log ¶

version 1.1 ¶

• Fixed open_basedir restriction issue

version 1.0 ¶

• Initial Public Release