[ class tree: Services_GeoNames ] [ index: Services_GeoNames ] [ all elements ]

Class: Services_GeoNames

Source Location: /Services_GeoNames-1.0.1/Services/GeoNames.php

Class Overview

Main interface to the GeoNames API:



  • Release: 1.0.1


  • 2008-2009 David Jean Louis



Inherited Variables

Inherited Methods

Class Details

[line 78]
Main interface to the GeoNames API:
  • Method: array children(): children(array $params)
  • Method: array cities(): cities(array $params)
  • Method: stdclass countryCode(): countryCode(array $params)
  • Method: array countryInfo(): countryInfo(array $params)
  • Method: stdclass countrySubdivision(): countrySubdivision(array $params)
  • Method: array earthquakes(): earthquakes(array $params)
  • Method: array findNearby(): findNearby(array $params)
  • Method: array findNearbyPlaceName(): findNearbyPlaceName(array $params)
  • Method: array findNearbyPostalCodes(): findNearbyPostalCodes(array $params)
  • Method: array findNearbyStreets(): findNearbyStreets(array $params)
  • Method: stdclass findNearByWeather(): findNearByWeather(array $params)
  • Method: array findNearbyWikipedia(): findNearbyWikipedia(array $params)
  • Method: stdclass findNearestAddress(): findNearestAddress(array $params)
  • Method: stdclass findNearestIntersection(): findNearestIntersection(array $params)
  • Method: stdclass get(): get(array $params)
  • Method: stdclass gtopo30(): gtopo30(array $params)
  • Method: array hierarchy(): hierarchy(array $params)
  • Method: stdclass neighbourhood(): neighbourhood(array $params)
  • Method: array neighbours(): neighbours(array $params)
  • Method: array postalCodeCountryInfo(): postalCodeCountryInfo(array $params)
  • Method: array postalCodeLookup(): postalCodeLookup(array $params)
  • Method: array postalCodeSearch(): postalCodeSearch(array $params)
  • Method: array search(): search(array $params)
  • Method: array siblings(): siblings(array $params)
  • Method: array weather(): weather(array $params)
  • Method: stdclass weatherIcao(): weatherIcao(array $params)
  • Method: stdclass srtm3(): srtm3(array $params)
  • Method: stdclass timezone(): timezone(array $params)
  • Method: array wikipediaBoundingBox(): wikipediaBoundingBox(array $params)
  • Method: array wikipediaSearch(): wikipediaSearch(array $params)
  • Author: David Jean Louis <>
  • Version: Release: 1.0.1
  • Copyright: 2008-2009 David Jean Louis
  • Link:
  • Link:
  • Link:
  • Since: Class available since release 0.1.0
  • License: MIT License

[ Top ]

Class Variables

$endpoints = array(
        'children'                => 'geonames',
        'cities'                  => 'geonames',
        'countryCode'             => false,
        'countryInfo'             => 'geonames',
        'countrySubdivision'      => false,
        'earthquakes'             => 'earthquakes',
        'findNearby'              => 'geonames',
        'findNearbyPlaceName'     => 'geonames',
        'findNearbyPostalCodes'   => 'postalCodes',
        'findNearbyStreets'       => 'streetSegment',
        'findNearByWeather'       => 'weatherObservation',
        'findNearbyWikipedia'     => 'geonames',
        'findNearestAddress'      => 'address',
        'findNearestIntersection' => 'intersection',
        'get'                     => false,
        'gtopo30'                 => false,
        'hierarchy'               => 'geonames',
        'neighbourhood'           => 'neighbourhood',
        'neighbours'              => 'geonames',
        'postalCodeCountryInfo'   => 'geonames',
        'postalCodeLookup'        => 'postalcodes', // not a typo
        'postalCodeSearch'        => 'postalCodes',
        'search'                  => 'geonames',
        'siblings'                => 'geonames',
        'weather'                 => 'weatherObservations',
        'weatherIcao'             => 'weatherObservation',
        'srtm3'                   => false,
        'timezone'                => false,
        'wikipediaBoundingBox'    => 'geonames',
        'wikipediaSearch'         => 'geonames',

[line 167]

Array of supported endpoints (listed alphabetically) and their corresponding root property (if any). You can retrieve the list of endpoints (only the keys of this array) with the Services_GeoNames::getSupportedEndpoints() method.

Note that we only support json endpoints, so the following endpoints are not supported:

  • extendedFindNearby (JSON not available for now)
  • rssToGeo (RSS/KML only)
For a full documentation of the available endpoints services, please see:

Type:   array

[ Top ]

$failoverServers = array()

[line 120]

Array of failover servers.

Type:   array

[ Top ]

$request =

[line 130]

The HTTP_Request2 instance, you can customize the request if you want to (proxy, auth etc...) with the get/setRequest() methods.

Type:   HTTP_Request2

[ Top ]

$token =

[line 148]

Auth token, only relevant for the geonames commercial web services:

Type:   string

[ Top ]

$url =  ''

[line 112]

Url of the GeoNames web service.
  • Access: public

Type:   string

[ Top ]

$username =

[line 139]

Auth username, only relevant for the geonames commercial web services:

Type:   string

[ Top ]

Method Detail

__construct (Constructor)   [line 213]

void __construct( [string $username = null], [string $token = null])

Constructor, if you're using a commercial account (optional), you must pass your "username" and "token".
  • Access: public


string   $username   —  Username for commercial webservice (optional)
string   $token   —  Token for commercial webservice (optional)

[ Top ]

formatQueryString   [line 360]

string formatQueryString( [array $params = array()])

Builds a valid query string (url and utf8 encoded) to pass to the endpoint and returns it.
  • Return: The formatted query string
  • Access: protected


array   $params   —  Associative array of query parameters (name=>val)

[ Top ]

getRequest   [line 387]

HTTP_Request2 getRequest( )

Returns the HTTP_Request2 instance, if it's not yet set it is instanciated on the fly.

[ Top ]

getSupportedEndpoints   [line 420]

array getSupportedEndpoints( )

Returns an array of supported services endpoints.

[ Top ]

isUtf8   [line 435]

boolean isUtf8( string $str)

Check if the given string is a UTF-8 string or an iso-8859-1 one.
  • Return: Wether the string is unicode or not
  • Access: protected


string   $str   —  The string to check

[ Top ]

sendRequest   [line 303]

string sendRequest( string $urlPath)

Sends the request to the server using HTTP_Request2.
  • Return: The response body
  • Throws: Services_GeoNames_HTTPException When something goes wrong when building the request or requesting the server.
  • Throws: HTTP_Request2_Exception
  • Access: protected


string   $urlPath   —  The url path *without* the scheme://host

[ Top ]

setRequest   [line 406]

void setRequest( HTTP_Request2 $request)

Sets the HTTP_Request2 instance.


HTTP_Request2   $request   —  The request to set

[ Top ]

__call   [line 237]

mixed __call( string $endpoint, [array $params = array()])

Method interceptor that retrieves the corresponding endpoint and return a json decoded object or throw a Services_GeoNames_Exception.
  • Return: stdclass|array The JSON decoded response or an array
  • Throws: Services_GeoNames_Exception When an invalid method is called or when the websercices returns an error
  • Access: public


string   $endpoint   —  The endpoint to call
array   $params   —  Array of parameters to pass to the endpoint

[ Top ]

Documentation generated on Mon, 11 Mar 2019 15:39:14 -0400 by phpDocumentor 1.4.4. PEAR Logo Copyright © PHP Group 2004.