geonames_client 1.0.0

data/.gitignore

@@ -0,0 +1,4 @@
+*.gem
+.bundle
+Gemfile.lock
+pkg/*

data/.rspec

@@ -0,0 +1,4 @@
+--color
+--format documentation
+--backtrace
+--debug

data/.rvmrc

@@ -0,0 +1,2 @@
+rvm use ruby-1.8.7-p334@geonames_client
+rvm info

data/Gemfile

@@ -0,0 +1,15 @@
+#!/usr/bin/env ruby
+source "http://rubygems.org"
+
+group :development, :test do
+  gem 'ruby-debug'
+	gem 'guard'
+  gem 'rb-fsevent'
+  gem 'growl'
+	gem 'guard-rspec'
+	gem 'guard-shell'
+	gem 'httparty'
+end
+
+# Specify your gem's dependencies in geonames_client.gemspec
+gemspec

data/Guardfile

@@ -0,0 +1,7 @@
+#!/usr/bin/env ruby
+
+guard 'rspec', :version => 2, :all_on_start => true, :all_after_pass => false, :cli => '--color --format doc' do
+  watch( %r{^spec/.+_spec\.rb$} )
+  watch( %r{^lib/(.+)\.rb$} )     { |m| "spec/lib/#{m[1]}_spec.rb" }
+  watch( 'spec/spec_helper.rb' )  { "spec" }
+end

data/Rakefile

@@ -0,0 +1,6 @@
+require "bundler/gem_tasks"
+
+require 'rspec/core/rake_task'
+RSpec::Core::RakeTask.new('spec')
+
+task :default => :spec

data/geonames_client.gemspec

@@ -0,0 +1,250 @@
+# -*- encoding: utf-8 -*-
+$:.push File.expand_path("../lib", __FILE__)
+require "geonames_client/version"
+
+Gem::Specification.new do |s|
+  s.name        = "geonames_client"
+  s.version     = GeonamesClient::VERSION
+  s.authors     = ["C. Jason Harrelson"]
+  s.email       = ["jason@lookforwardenterprises.com"]
+  s.homepage    = ""
+  s.summary     = %q{A client to consume the geonames web services.}
+  s.description = %q{A client to consume the geonames web services (www.geonames.org).}
+
+  s.rubyforge_project = "geonames_client"
+
+  s.files         = `git ls-files`.split("\n")
+  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  s.require_paths = ["lib"]
+
+  development_dependencies = {
+    %q<rake>     => [">= 0.9.2"],
+    %q<rspec>    => [">= 2.6.0"],
+    %q<httparty> => [">= 0.8.0"]
+  }
+
+  runtime_dependencies = {
+    %q<httparty> => [">= 0.8.0"]
+  }
+
+  if s.respond_to? :specification_version then
+    current_version = Gem::Specification::CURRENT_SPECIFICATION_VERSION
+    s.specification_version = 3
+
+    if Gem::Version.new(Gem::VERSION) >= Gem::Version.new('1.2.0') then
+      development_dependencies.each do |name, versions|
+        s.add_development_dependency( name, versions )
+      end
+
+      runtime_dependencies.each do |name, versions|
+        s.add_runtime_dependency( name, versions )
+      end
+    else
+      development_dependencies.each do |name, versions|
+        s.add_dependency( name, versions )
+      end
+
+      runtime_dependencies.each do |name, versions|
+        s.add_dependency( name, versions )
+      end
+    end
+  else
+    development_dependencies.each do |name, versions|
+      s.add_dependency( name, versions )
+    end
+
+    runtime_dependencies.each do |name, versions|
+      s.add_dependency( name, versions )
+    end
+  end
+end
+# -*- encoding: utf-8 -*-
+$:.push File.expand_path("../lib", __FILE__)
+require "geonames_client/version"
+
+Gem::Specification.new do |s|
+  s.name        = "geonames_client"
+  s.version     = GeonamesClient::VERSION
+  s.authors     = ["C. Jason Harrelson"]
+  s.email       = ["jason@lookforwardenterprises.com"]
+  s.homepage    = ""
+  s.summary     = %q{A client to consume the geonames web services.}
+  s.description = %q{A client to consume the geonames web services (www.geonames.org).}
+
+  s.rubyforge_project = "geonames_client"
+
+  s.files         = `git ls-files`.split("\n")
+  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  s.require_paths = ["lib"]
+
+  development_dependencies = {
+    %q<rake>             => [">= 0.9.2" ],
+    %q<rspec>            => [">= 2.6.0" ],
+    %q<ruby-debug>       => [">= 0.10.4"],
+    %q<guard>            => [">= 0.4.2" ],
+    %q<guard-rspec>      => [">= 0.4.0" ],
+  }
+
+  runtime_dependencies = {
+
+  }
+
+  if s.respond_to? :specification_version then
+    current_version = Gem::Specification::CURRENT_SPECIFICATION_VERSION
+    s.specification_version = 3
+
+    if Gem::Version.new(Gem::VERSION) >= Gem::Version.new('1.2.0') then
+      development_dependencies.each do |name, versions|
+        s.add_development_dependency( name, versions )
+      end
+
+      runtime_dependencies.each do |name, versions|
+        s.add_runtime_dependency( name, versions )
+      end
+    else
+      development_dependencies.each do |name, versions|
+        s.add_dependency( name, versions )
+      end
+
+      runtime_dependencies.each do |name, versions|
+        s.add_dependency( name, versions )
+      end
+    end
+  else
+    development_dependencies.each do |name, versions|
+      s.add_dependency( name, versions )
+    end
+
+    runtime_dependencies.each do |name, versions|
+      s.add_dependency( name, versions )
+    end
+  end
+end
+# -*- encoding: utf-8 -*-
+$:.push File.expand_path("../lib", __FILE__)
+require "geonames_client/version"
+
+Gem::Specification.new do |s|
+  s.name        = "geonames_client"
+  s.version     = GeonamesClient::VERSION
+  s.authors     = ["C. Jason Harrelson"]
+  s.email       = ["jason@lookforwardenterprises.com"]
+  s.homepage    = ""
+  s.summary     = %q{A client to consume the geonames web services.}
+  s.description = %q{A client to consume the geonames web services (www.geonames.org).}
+
+  s.rubyforge_project = "geonames_client"
+
+  s.files         = `git ls-files`.split("\n")
+  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  s.require_paths = ["lib"]
+
+  development_dependencies = {
+    %q<rake>             => [">= 0.9.2" ],
+    %q<rspec>            => [">= 2.6.0" ],
+    %q<ruby-debug>       => [">= 0.10.4"],
+    %q<guard>            => [">= 0.4.2" ],
+    %q<guard-rspec>      => [">= 0.4.0" ],
+  }
+
+  runtime_dependencies = {
+
+  }
+
+  if s.respond_to? :specification_version then
+    current_version = Gem::Specification::CURRENT_SPECIFICATION_VERSION
+    s.specification_version = 3
+
+    if Gem::Version.new(Gem::VERSION) >= Gem::Version.new('1.2.0') then
+      development_dependencies.each do |name, versions|
+        s.add_development_dependency( name, versions )
+      end
+
+      runtime_dependencies.each do |name, versions|
+        s.add_runtime_dependency( name, versions )
+      end
+    else
+      development_dependencies.each do |name, versions|
+        s.add_dependency( name, versions )
+      end
+
+      runtime_dependencies.each do |name, versions|
+        s.add_dependency( name, versions )
+      end
+    end
+  else
+    development_dependencies.each do |name, versions|
+      s.add_dependency( name, versions )
+    end
+
+    runtime_dependencies.each do |name, versions|
+      s.add_dependency( name, versions )
+    end
+  end
+end
+# -*- encoding: utf-8 -*-
+$:.push File.expand_path("../lib", __FILE__)
+require "geonames_client/version"
+
+Gem::Specification.new do |s|
+  s.name        = "geonames_client"
+  s.version     = GeonamesClient::VERSION
+  s.authors     = ["C. Jason Harrelson"]
+  s.email       = ["jason@lookforwardenterprises.com"]
+  s.homepage    = ""
+  s.summary     = %q{A client to consume the geonames web services.}
+  s.description = %q{A client to consume the geonames web services (www.geonames.org).}
+
+  s.rubyforge_project = "geonames_client"
+
+  s.files         = `git ls-files`.split("\n")
+  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  s.require_paths = ["lib"]
+
+  development_dependencies = {
+    %q<rake>             => [">= 0.9.2" ],
+    %q<rspec>            => [">= 2.6.0" ],
+    %q<ruby-debug>       => [">= 0.10.4"],
+    %q<guard>            => [">= 0.4.2" ],
+    %q<guard-rspec>      => [">= 0.4.0" ],
+  }
+
+  runtime_dependencies = {
+
+  }
+
+  if s.respond_to? :specification_version then
+    current_version = Gem::Specification::CURRENT_SPECIFICATION_VERSION
+    s.specification_version = 3
+
+    if Gem::Version.new(Gem::VERSION) >= Gem::Version.new('1.2.0') then
+      development_dependencies.each do |name, versions|
+        s.add_development_dependency( name, versions )
+      end
+
+      runtime_dependencies.each do |name, versions|
+        s.add_runtime_dependency( name, versions )
+      end
+    else
+      development_dependencies.each do |name, versions|
+        s.add_dependency( name, versions )
+      end
+
+      runtime_dependencies.each do |name, versions|
+        s.add_dependency( name, versions )
+      end
+    end
+  else
+    development_dependencies.each do |name, versions|
+      s.add_dependency( name, versions )
+    end
+
+    runtime_dependencies.each do |name, versions|
+      s.add_dependency( name, versions )
+    end
+  end
+end

data/lib/geonames_client/_location.rb

@@ -0,0 +1,68 @@
+class Location
+
+  def self.deg2rad(deg)
+     (deg * Math::PI / 180)
+  end
+
+  def self.rad2deg(rad)
+     (rad * 180 / Math::PI)
+  end
+
+  def self.acos(rad)
+     Math.atan2(Math.sqrt(1 - rad**2), rad)
+  end
+
+  def self.distance_in_miles(loc1, loc2)
+     lat1 = loc1.latitude
+     lon1 = loc1.longitude
+     lat2 = loc2.latitude
+     lon2 = loc2.longitude
+     theta = lon1 - lon2
+
+     dist = Math.sin(self.deg2rad(lat1)) * Math.sin(deg2rad(lat2))
+        + Math.cos(self.deg2rad(lat1)) * Math.cos(self.deg2rad(lat2)) * Math.cos(deg2rad(theta))
+
+     dist = self.rad2deg(self.acos(dist))
+
+     (dist * 60 * 1.1515).round #distance in miles
+  end
+
+  def miles_to(location)
+     Location.distance_in_miles(self, location)
+  end
+
+  def self.locationArea(location, miles)
+     radius = miles.to_f
+     latR = radius / ((6076 / 5280) * 60)
+     lonR = radius / (((Math.cos(location.latitude * Math::PI / 180) * 6076) / 5280) * 60)
+
+     {
+        :min_latitude => location.latitude - latR,
+        :min_longitude => location.longitude - lonR,
+        :max_latitude => location.latitude + latR,
+        :max_longitude => location.longitude + lonR
+     }
+  end
+
+  def self.location_ids_in_range(location, miles)
+     la = Location.locationArea(location, miles)
+     Location.find(:all,
+        :select => Location.connection.quote_column_name( 'id' ),
+        :conditions => ["(#{connection.quote_table_name 'locations'}.#{connection.quote_column_name 'latitude'} <= ?) AND (#{connection.quote_table_name 'locations'}.#{connection.quote_column_name 'latitude'} >= ?) AND " +
+           "(#{connection.quote_table_name 'locations'}.#{connection.quote_column_name 'longitude'} >= ?) AND (#{connection.quote_table_name 'locations'}.#{connection.quote_column_name 'longitude'} <= ?)",
+           la[:max_latitude], la[:min_latitude], la[:min_longitude], la[:max_longitude]
+        ]
+     ).collect { |l| l.id }
+  end
+
+  def self.locations_in_range(location, miles)
+     la = Location.locationArea(location, miles)
+     Location.find(:all,
+        :conditions => ["(#{connection.quote_table_name 'locations'}.#{connection.quote_column_name 'latitude'} <= ?) AND (#{connection.quote_table_name 'locations'}.#{connection.quote_column_name 'latitude'} >= ?) AND " +
+           "(#{connection.quote_table_name 'locations'}.#{connection.quote_column_name 'longitude'} >= ?) AND (#{connection.quote_table_name 'locations'}.#{connection.quote_column_name 'longitude'} <= ?)",
+           la[:max_latitude], la[:min_latitude], la[:min_longitude], la[:max_longitude]
+        ]
+     )
+  end
+
+end

data/lib/geonames_client/location.rb

@@ -0,0 +1,123 @@
+module GeonamesClient
+  # This class is not suitable for distances over a couple of miles.  Due to the fact
+  # that spherical triginometry must be employed due to the curvature of the earth.
+  #
+  class Location
+
+    attr_reader :latitude_in_decimal_degrees, :longitude_in_decimal_degrees
+
+    def initialize( latitude_in_decimal_degrees,
+                    longitude_in_decimal_degrees )
+      @latitude_in_decimal_degrees  = latitude_in_decimal_degrees
+      @longitude_in_decimal_degrees = longitude_in_decimal_degrees
+    end
+
+    def bounding_box_locations_as_array( distance )
+      bounding_box_locations( distance ).map &:to_a
+    end
+
+    def bounding_box_locations_as_hash_like_array( distance )
+        [
+          :northeast,
+          :northwest,
+          :southwest,
+          :southeast
+        ].zip( bounding_box_locations_as_array( distance ) )
+    end
+
+    def bounding_box_locations_as_hash( distance )
+      hash = {}
+
+      bounding_box_locations_as_hash_like_array( distance ).each do |direction, location|
+        hash[direction] = location
+      end
+
+      hash
+    end
+
+    def bounding_box_locations( distance )
+      %w(
+        northeast
+        northwest
+        southwest
+        southeast
+      ).map do |direction|
+        send( "bounding_box_#{direction}_location", distance )
+      end
+    end
+
+    def to_a
+      [
+        latitude_in_decimal_degrees,
+        longitude_in_decimal_degrees
+      ]
+    end
+
+    def ==( another_location )
+      return false unless another_location.is_a?( Location )
+      return false unless another_location.latitude_in_decimal_degrees == latitude_in_decimal_degrees
+      return false unless another_location.longitude_in_decimal_degrees == longitude_in_decimal_degrees
+
+      true
+    end
+
+  private
+
+    %w(
+      northeast
+      northwest
+      southwest
+      southeast
+    ).each do |direction|
+
+      define_method "dx_#{direction}" do |distance|
+        rount_float( distance * Math.cos( send( "#{direction}_theta" ).degrees ), 2 )
+      end
+
+      define_method "dy_#{direction}" do |distance|
+        rount_float( distance * Math.sin( send( "#{direction}_theta" ).degrees ), 2 )
+      end
+
+      define_method "delta_latitude_#{direction}" do |distance|
+        rount_float( send( "dy_#{direction}", distance ) / 110540.0, 6 )
+      end
+
+      define_method "delta_longitude_#{direction}" do |distance|
+        rount_float( send( "dx_#{direction}", distance ) / (111320.0 * Math.cos( latitude_in_decimal_degrees.degrees )), 6 )
+      end
+
+      define_method "latitude_#{direction}" do |distance|
+        rount_float( latitude_in_decimal_degrees + send( "delta_latitude_#{direction}", distance ), 6 )
+      end
+
+      define_method "longitude_#{direction}" do |distance|
+        rount_float( longitude_in_decimal_degrees + send( "delta_longitude_#{direction}", distance ), 6 )
+      end
+
+      define_method "bounding_box_#{direction}_location" do |distance|
+        Location.new send( "latitude_#{direction}",  distance ),
+                     send( "longitude_#{direction}", distance )
+      end
+
+    end
+
+    # Measuring theta from due east.
+    {
+      :northeast => 45,
+      :northwest => 135,
+      :southwest => 225,
+      :southeast => 315
+    }.each do |direction, value|
+
+      define_method "#{direction}_theta" do
+        value
+      end
+
+    end
+
+    def rount_float( val, precision )
+      sprintf( "%.#{precision}f", val ).to_f
+    end
+
+  end
+end

data/lib/geonames_client/nearby_street.rb

@@ -0,0 +1,29 @@
+module GeonamesClient
+  class NearbyStreet
+
+    attr_reader :name
+
+    def initialize( options )
+      @name = options[:name]
+    end
+
+    def self.all( *names )
+      names.map { |name| NearbyStreet.new( :name => name ) }
+    end
+
+    def ==( another_nearby_street )
+      return false unless another_nearby_street.is_a?( NearbyStreet )
+      return false unless another_nearby_street.name == name
+
+      true
+    end
+
+    def <=>( another_nearby_street )
+      return -1 if name < another_nearby_street.name
+      return  1 if name > another_nearby_street.name
+
+      0
+    end
+
+  end
+end

data/lib/geonames_client/service.rb

@@ -0,0 +1,96 @@
+require 'httparty'
+
+module GeonamesClient
+  class Service
+
+    include HTTParty
+
+    base_uri ServiceDefinition.address
+
+    attr_reader :api_key
+
+    def initialize( api_key )
+      @api_key = api_key
+    end
+
+    def service_definition
+      @service_definition ||= ServiceDefinition.new
+    end
+
+    def get_nearby_streets( options )
+      options.merge!( :username => api_key )
+
+      NearbyStreet.all *nearby_streets( options ).sort
+    end
+
+    def get_nearby_streets_within_radius( options )
+      options.merge!( :username => api_key )
+
+      street_names = (nearby_streets( options ) +
+                      nearby_streets_northeast( options ) +
+                      nearby_streets_northwest( options ) +
+                      nearby_streets_southeast( options ) +
+                      nearby_streets_southwest( options ) ).uniq
+
+
+      NearbyStreet.all *street_names.sort
+    end
+
+    def nearby_streets( options )
+      uri = service_definition.full_nearby_streets_uri( options )
+
+      response = self.class.get( uri )
+
+      check_response_for_error( response )
+
+      response.parsed_response['geonames']['streetSegment'].map { |s| s['name'] }.uniq.compact
+    end
+
+    def check_response_for_error( response )
+      geonames = response['geonames']
+      return unless geonames
+      error = geonames['status']
+
+      unless error.nil?
+        raise "Geonames returned error: (#{error['value']}) #{error['message']}"
+      end
+    end
+
+    %w(
+      northeast
+      northwest
+      southwest
+      southeast
+    ).each do |direction|
+
+      define_method "nearby_streets_#{direction}" do |options|
+        location = bounding_box( options )[direction.to_sym]
+        lat      = location.first
+        long     = location.last
+
+        uri = service_definition.full_nearby_streets_uri( :latitude  => lat,
+                                                          :longitude => long,
+                                                          :username  => api_key )
+
+        response = self.class.get( uri )
+
+        check_response_for_error( response )
+        geonames = response.parsed_response['geonames']
+        geonames.nil? ? [] : response.parsed_response['geonames']['streetSegment'].map { |s| s['name'] }.uniq.compact
+      end
+
+    end
+
+    def bounding_box( options )
+      location = Location.new( options[:latitude].to_f,
+                               options[:longitude].to_f )
+
+      location.bounding_box_locations_as_hash( options[:radius] || default_radius )
+    end
+
+    def default_radius
+      402
+    end
+
+  end
+end

data/lib/geonames_client/service_definition.rb

@@ -0,0 +1,76 @@
+module GeonamesClient
+  class ServiceDefinition
+
+    def self.address
+      'api.geonames.org'
+    end
+
+    def base_uri
+      ['http://', self.class.address].join
+    end
+
+    def nearby_streets_path
+      '/findNearbyStreets'
+    end
+
+    def nearby_streets_json_path
+      '/findNearbyStreetsJSON'
+    end
+
+    def latitude_parameter
+      'lat'
+    end
+
+    def longitude_parameter
+      'lng'
+    end
+
+    def username_parameter
+      'username'
+    end
+
+    def nearby_streets_base_path( format=:xml )
+      format = format.to_sym
+
+      raise "Invalid format: expected one of #{available_formats.join( ', ' )}" unless available_formats.include?( format )
+
+      return [base_uri,
+              format == :xml ? nearby_streets_path : nearby_streets_json_path].join ''
+    end
+
+    def full_nearby_streets_uri( params={} )
+      expected_parameters.each do |p|
+        raise "Please provide the :#{p} parameter" unless params.has_key?( p.to_sym )
+      end
+
+      format = params.delete( :format ) || default_format
+
+      [nearby_streets_base_path( format ), query_string( params )].join '?'
+    end
+
+  private
+
+    def default_format
+      :xml
+    end
+
+    def available_formats
+      [:xml, :json]
+    end
+
+    def expected_parameters
+      %w(
+        latitude
+        longitude
+        username
+      )
+    end
+
+    def query_string( params )
+      expected_parameters.map do |p|
+        [send( "#{p}_parameter" ), params[p.to_sym]].join '='
+      end.join '&'
+    end
+
+  end
+end

data/lib/geonames_client/version.rb

@@ -0,0 +1,3 @@
+module GeonamesClient
+  VERSION = "1.0.0"
+end