sundawg_geonames_client 0.0.1

data/Manifest

@@ -0,0 +1,8 @@
+Manifest
+README.rdoc
+Rakefile
+lib/geonames_client.rb
+lib/geonames_client_helper.rb
+test/geonames_client_helper_test.rb
+test/geonames_client_integration_test.rb
+test/geonames_client_test.rb

data/README.rdoc

@@ -0,0 +1,65 @@
+== 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:
+
+- http://www.geonames.org
+- http://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.
+
+- http://flori.github.com/json/
+- http://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:
+
+http://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.

data/Rakefile

@@ -0,0 +1,13 @@
+# Rakefile
+require 'rubygems'
+require 'rake'
+require 'echoe'
+
+Echoe.new('sundawg_geonames_client', '0.0.1') do |p|
+  p.description    = "Ruby client interface to all and future RESTful geo-services provided by geonames.org."
+  p.url            = "http://github.com/SunDawg/geonames_client"
+  p.author         = "Christopher Sun"
+  p.email          = "christopher.sun@gmail.com"
+  p.ignore_pattern = ["tmp/*", "script/*"]
+  p.development_dependencies = ['mocha']
+end

data/lib/geonames_client.rb

@@ -0,0 +1,48 @@
+require 'net/http'
+require 'uri'
+require 'cgi'
+
+module SunDawg
+  class GeonamesClient
+    URL = "http://ws.geonames.org"
+
+    def initialize(options = {})
+      options[:json].nil? ? options[:json] = true : nil 
+      options[:camelize].nil? ? options[:camelize] = false : nil
+      options[:username].nil? ? options[:username] = "SunDawg" : nil
+      @options = options
+    end
+
+    def method_missing(signature, *args)
+      raise ArgumentError.new("must provide a hash of geoname parameters for first argument when calling web services [#{signature}] [#{args.inspect}]") if args.size < 1 || !args[0].is_a?(Hash)
+      signature = smart_camelize(signature.to_s) unless @options[:camelize]
+      do_http_call(service_resource(signature), args[0])
+    end
+
+    protected
+
+    def do_http_call(resource, params)
+      params.merge!(:username => @options[:username])
+      resource += "?" + query_string(params)
+      url = URI.parse(resource)
+      response = Net::HTTP.start(url.host, url.port) do |http|
+        http.get(resource)
+      end
+      response.body
+    end
+
+    def query_string(params) 
+      params.keys.map { |i| "#{i}=#{CGI::escape(params[i])}#{i == params.keys.last ? "" : "&"}" }.join 
+    end
+
+    # provided to remove active support dependency
+    def smart_camelize(s)
+      s = s.split(/[^a-z0-9]/i).map{|w| w.capitalize}.join
+      "#{s[0..0].swapcase!}#{s[1..s.length]}"
+    end
+
+    def service_resource(service) 
+      "#{URL}/#{service}#{ @options[:json] ? "JSON" : "" }"
+    end
+  end
+end

data/lib/geonames_client_helper.rb

@@ -0,0 +1,24 @@
+module SunDawg
+  class GeonamesClientHelper
+
+    def self.postal_code_to(params, options = {})
+      json = SunDawg::GeonamesClient.new(options.reject { |k, v| k == :json }.reject { |k, v| k == :camelize }).postal_code_lookup params
+      yield(SunDawg::GeonamesClient.new(options), {:lat => get_lat(json), :lng => get_lng(json)}, json)
+    end
+
+    protected
+
+    # simple string search so we don't need to import a json library
+    def self.get_lat(s)
+      json_parse("lat", s)
+    end
+
+    def self.get_lng(s)
+      json_parse("lng", s)
+    end
+
+    def self.json_parse(field, s)
+      s.match(/"#{field}":-?(\d|\.)+/)[0].split(":")[1]
+    end
+  end
+end

data/sundawg_geonames_client.gemspec

@@ -0,0 +1,34 @@
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+  s.name = %q{sundawg_geonames_client}
+  s.version = "0.0.1"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 1.2") if s.respond_to? :required_rubygems_version=
+  s.authors = ["Christopher Sun"]
+  s.date = %q{2010-04-16}
+  s.description = %q{Ruby client interface to all and future RESTful geo-services provided by geonames.org.}
+  s.email = %q{christopher.sun@gmail.com}
+  s.extra_rdoc_files = ["README.rdoc", "lib/geonames_client.rb", "lib/geonames_client_helper.rb"]
+  s.files = ["Manifest", "README.rdoc", "Rakefile", "lib/geonames_client.rb", "lib/geonames_client_helper.rb", "test/geonames_client_helper_test.rb", "test/geonames_client_integration_test.rb", "test/geonames_client_test.rb", "sundawg_geonames_client.gemspec"]
+  s.homepage = %q{http://github.com/SunDawg/geonames_client}
+  s.rdoc_options = ["--line-numbers", "--inline-source", "--title", "Sundawg_geonames_client", "--main", "README.rdoc"]
+  s.require_paths = ["lib"]
+  s.rubyforge_project = %q{sundawg_geonames_client}
+  s.rubygems_version = %q{1.3.6}
+  s.summary = %q{Ruby client interface to all and future RESTful geo-services provided by geonames.org.}
+  s.test_files = ["test/geonames_client_helper_test.rb", "test/geonames_client_integration_test.rb", "test/geonames_client_test.rb"]
+
+  if s.respond_to? :specification_version then
+    current_version = Gem::Specification::CURRENT_SPECIFICATION_VERSION
+    s.specification_version = 3
+
+    if Gem::Version.new(Gem::RubyGemsVersion) >= Gem::Version.new('1.2.0') then
+      s.add_development_dependency(%q<mocha>, [">= 0"])
+    else
+      s.add_dependency(%q<mocha>, [">= 0"])
+    end
+  else
+    s.add_dependency(%q<mocha>, [">= 0"])
+  end
+end

data/test/geonames_client_helper_test.rb

@@ -0,0 +1,29 @@
+require 'test/unit'
+require 'geonames_client_helper'
+
+class GeonamesClientHelperTest < Test::Unit::TestCase
+  def test_postal_code_to_timezone
+    json = SunDawg::GeonamesClientHelper.postal_code_to(:postalcode => "10069", :country => "US") do |client, params|
+      assert_equal "40.777952", params[:lat]
+      assert_equal "-73.988381", params[:lng]
+      client.timezone params 
+    end
+    assert_match "America/New_York", json
+  end
+
+  def test_get_lat
+    s = '{"postalcodes":[{"adminName2":"Olsztyn","postalcode":"10-069","countryCode":"PL","lng":20.4833333,"placeName":"Olsztyn","lat":53.7833333,"adminName1":"Warmińsko-Mazurskie"},{"adminName2":"New York","adminCode2":"061","postalcode":"10069","adminCode1":"NY","countryCode":"US","lng":-73.988381,"placeName":"New York City","lat":40.777952,"adminName1":"New York"},{"adminName2":"Torino","adminCode2":"TO","postalcode":"10069","countryCode":"IT","lng":7.248118,"placeName":"Villar Perosa","lat":44.91932,"adminName1":"Piemonte"}]}'
+    assert_equal "53.7833333", SunDawg::GeonamesClientHelper.send(:get_lat, s)
+
+    s = '{"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"}]}'
+    assert_equal "40.777952", SunDawg::GeonamesClientHelper.send(:get_lat, s)
+  end
+
+  def test_get_lng
+    s = '{"postalcodes":[{"adminName2":"Olsztyn","postalcode":"10-069","countryCode":"PL","lng":20.4833333,"placeName":"Olsztyn","lat":53.7833333,"adminName1":"Warmińsko-Mazurskie"},{"adminName2":"New York","adminCode2":"061","postalcode":"10069","adminCode1":"NY","countryCode":"US","lng":-73.988381,"placeName":"New York City","lat":40.777952,"adminName1":"New York"},{"adminName2":"Torino","adminCode2":"TO","postalcode":"10069","countryCode":"IT","lng":7.248118,"placeName":"Villar Perosa","lat":44.91932,"adminName1":"Piemonte"}]}'
+    assert_equal "20.4833333", SunDawg::GeonamesClientHelper.send(:get_lng, s)
+
+    s = '{"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"}]}'
+    assert_equal "-73.988381", SunDawg::GeonamesClientHelper.send(:get_lng, s)
+  end
+end

data/test/geonames_client_integration_test.rb

@@ -0,0 +1,47 @@
+require 'test/unit'
+require 'rubygems'
+require 'geonames_client'
+
+class GeonamesClientIntegrationTest < Test::Unit::TestCase
+  def setup
+    @client = SunDawg::GeonamesClient.new
+  end
+
+  def test_postal_code_lookup_json
+    json = client.postal_code_lookup :postalcode => "10069", :country => "US"
+    assert_match "New York", json 
+  end
+
+  def test_postal_code_lookup_camelize
+    json = SunDawg::GeonamesClient.new(:camelize => true).postalCodeLookup :postalcode => "10069", :country => "US"
+    assert_match "New York", json
+  end
+
+  def test_country_code_json
+    json = client.country_code :lat => "47.03", :lng => "10.2"
+    assert_match "Austria", json
+    assert_match "AT", json
+
+    json = client.country_code :lat => "40.7", :lng => "-73.98"
+    assert_match "United States", json
+    assert_match "US", json
+  end
+
+  def test_timezone
+    json = client.timezone :lat => "40.777952", :lng => "-73.988381"
+    assert_match "America/New_York", json
+  end
+
+  # validate hitting non JSON resource
+  def test_country_code_xml
+    xml = SunDawg::GeonamesClient.new(:json => false).country_code :lat => "47.03", :lng => "10.2", :type => "xml"
+    assert_match "<countryName>Austria</countryName>", xml 
+    assert_match "<countryCode>AT</countryCode>", xml
+  end
+
+  protected
+
+  def client
+    @client
+  end
+end

data/test/geonames_client_test.rb

@@ -0,0 +1,40 @@
+require 'test/unit'
+require 'rubygems'
+require 'geonames_client'
+require 'mocha'
+
+class GeonamesClientTest < Test::Unit::TestCase
+  def setup
+    @client = SunDawg::GeonamesClient.new
+  end
+
+  def test_invalid_arguments
+    assert_raise ArgumentError do
+      client.foo 
+    end
+  end
+
+  def test_do_http_call
+    params = {:arg1 => "x", :arg2 => "y"}
+    client.expects(:do_http_call).with("http://ws.geonames.org/fooJSON", params)
+    client.foo params
+  end
+
+  def test_query_string
+    params = {:arg1 => "x", :arg2 => "123"}
+    query_string = client.send(:query_string, params)
+
+    # hash is not-ordered
+    assert (query_string == "arg1=x&arg2=123" or query_string == "arg2=123&arg1=x")
+  end
+
+  def test_smart_camelize
+    assert_equal "helloWorld", client.send(:smart_camelize, "hello_world")
+  end
+
+  protected
+
+  def client
+    @client
+  end
+end

metadata

@@ -0,0 +1,91 @@
+--- !ruby/object:Gem::Specification 
+name: sundawg_geonames_client
+version: !ruby/object:Gem::Version 
+  prerelease: false
+  segments: 
+  - 0
+  - 0
+  - 1
+  version: 0.0.1
+platform: ruby
+authors: 
+- Christopher Sun
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2010-04-16 00:00:00 -04:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: mocha
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 0
+        version: "0"
+  type: :development
+  version_requirements: *id001
+description: Ruby client interface to all and future RESTful geo-services provided by geonames.org.
+email: christopher.sun@gmail.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- README.rdoc
+- lib/geonames_client.rb
+- lib/geonames_client_helper.rb
+files: 
+- Manifest
+- README.rdoc
+- Rakefile
+- lib/geonames_client.rb
+- lib/geonames_client_helper.rb
+- test/geonames_client_helper_test.rb
+- test/geonames_client_integration_test.rb
+- test/geonames_client_test.rb
+- sundawg_geonames_client.gemspec
+has_rdoc: true
+homepage: http://github.com/SunDawg/geonames_client
+licenses: []
+
+post_install_message: 
+rdoc_options: 
+- --line-numbers
+- --inline-source
+- --title
+- Sundawg_geonames_client
+- --main
+- README.rdoc
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      segments: 
+      - 1
+      - 2
+      version: "1.2"
+requirements: []
+
+rubyforge_project: sundawg_geonames_client
+rubygems_version: 1.3.6
+signing_key: 
+specification_version: 3
+summary: Ruby client interface to all and future RESTful geo-services provided by geonames.org.
+test_files: 
+- test/geonames_client_helper_test.rb
+- test/geonames_client_integration_test.rb
+- test/geonames_client_test.rb