About

Sundawg Geonames Client is a ruby gem for the RESTful web services provided by geonames.org. This client attempts to use the method_missing functionality of Ruby to quickly provide generic support for any and all services provided by geonames.org. For more information on these services and geonames, please see the following:

• www.geonames.org

• www.geonames.org/export/ws-overview.html

Installation

You can install the gem as so:

gem install sundawg_geonames_client

Tests

You can confirm tests and functionality with geonames.org by running:

rake tests

Usage

To use the client, you simply call the service method you want on geonames.org directly on the client. Any parameters that the service requires are passed as a hash object to the client.

For example, to call the postalCodeLookup service, you would do the following:

SunDawg::GeonamesClient.new.postal_code_lookup :postalcode => "10069", :country => "US"
=> {"postalcodes":[{"adminName2":"New York","adminCode2":"061","postalcode":"10069","adminCode1":"NY","countryCode":"US","lng":-73.988381,"placeName":"New York City","lat":40.777952,"adminName1":"New York"}]}

By default, the client uses the JSON service provided by geonames.org and provides the raw JSON output back to you. You can then use the JSON parser of your choice to parse the data i.e. json gem or ActiveSupport.

• flori.github.com/json/

• api.rubyonrails.org/classes/ActiveSupport/JSON.html

The client allows you to pass in several configration changes. If you want to use camelcase notation as the service is provided, then you can pass in :camelize => true when creating the client. This will remove all of the string manipulation to turn snake case notation into camel notation, thus allowing you to break out of the Ruby conventions if you want.

Here is the same call, but with camel notation.

SunDawg::GeonamesClient.new(:camelize => true).postalCodeLookup :postalcode => "10069", :country => "US"

You can also turn off JSON support and attempt to hit the standard service with :json => false. One small warning, is that the documentation is unclear as to whether you will always get XML or non-markup text in your response. For example the countryCode service seems to return the ISO Alpha2 country when you hit the non-JSON service. Passing in a :type => “xml” will force XML.

SunDawg::GeonamesClient.new(:json => false).country_code :lat => "47.03", :lng => "10.2", :type => "xml"

Lastly, you can pass a username to the client. This is a new requirement imposed by geonames.org to identify a malignant client that is creating DDOS issues for geonames.org. Their explanation is here:

geonames.wordpress.com/2010/03/16/ddos-part-ii/

SunDawg::Geonames client will default the username if you do not provide one.

Helper Feature

The reason for this library is for my need to convert postal code information into other sorts of useful information. This requires two calls to the geonames.org services, one to turn a postal code into longitude and latitude coordinates, then a call to the service that will provide the interesting information.

There is a small helper class that will allow you to chain a postal_code_lookup service call with other geonames.org service calls. For example, if I want to get the timezone associated with a postal code, I can use the helper as so:

json = SunDawg::GeonamesClientHelper.postal_code_to(:postalcode => "10069", :country => "US") do |client, params, original_json|
  assert_equal "40.777952", params[:lat]
  assert_equal "-73.988381", params[:lng]
  client.timezone params
end
assert_match "America/New_York", json

The helper is invoking the postal code service and then executing the yield block. You are provided an instance of the client with whatever options you specified, a hash containing longitude and latitude that can be passed to subsequent calls, and for complete-ness sake, the JSON response from the postal call.

The helper automatically uses the first match from the postal service.