egeonameservice EGeoNameService - Simplifies the access to the GeoNames web services

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


EGeoNameService is a client library to access the JSON Web services offered by A full overview of the methods provided by the Web service and its results can be viewed at

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.


Developed with Yii 1.1.7


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 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 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

$egeo = new EGeoNameService();
$egeo->username = 'demo'; // your username

echo $egeo->languages.', '.$egeo->countryName.', '.$egeo->countryCode;
echo $egeo->geonames[0]->countryName;
echo $egeo->countryName.'<br/>';
echo $egeo->codes[0]['type'];
echo $egeo->earthquakes[0]->eqid;
echo $egeo->geonames[0]->countryName;
echo $egeo->geonames[0]->countryCode;
echo $egeo->postalCodes[1]->postalCode;


Change Log

version 1.1
  • Fixed open_basedir restriction issue
version 1.0
  • Initial Public Release
9 0
1 972 downloads
Yii Version: 1.1
License: BSD-2-Clause
Category: Web Service
Developed by: Antonio Ramirez
Created on: Apr 4, 2011
Last updated: 10 years ago


show all

Related Extensions