graticule 2.3.0 → 2.4.0

data/.autotest

@@ -0,0 +1,13 @@
+Autotest.add_hook :initialize do |at|
+  at.clear_mappings
+
+  at.add_mapping %r%^lib/(.*)\.rb$% do |_, m|
+    at.files_matching %r%^test/#{m[1]}_test.rb$%
+  end
+
+  at.add_mapping(%r%^test/.*\.rb$%) {|filename, _| filename }
+
+  at.add_mapping %r%^test/fixtures/(.*)s.yml% do |_, _|
+    at.files_matching %r%^test/.*\.rb$%
+  end
+end

data/.gitignore

@@ -0,0 +1,10 @@
+Gemfile.lock
+test/config.yml
+*.gem
+pkg
+coverage
+rdoc
+.DS_Store
+.*.swp
+.*.swo
+.rvmrc

data/.travis.yml

@@ -0,0 +1,14 @@
+language: ruby
+rvm:
+  - 1.9.3
+  - 2.0.0
+before_script:
+  - cp test/config.yml.default test/config.yml
+only:
+  - master
+notifications:
+  email: false
+  webhooks:
+    urls:
+      - http://buildlight.collectiveidea.com/
+    on_start: true

data/CHANGELOG.txt

@@ -1,3 +1,6 @@
+2.4.0 (--)
+* Update MapQuest handler to use the current API
+
 2.3.0 (2013-04-01)
 * Google v3 API [Adamlb]
 * Escape XML entities in GeoCoder::MapQuest queries [Simon Coffey]
@@ -72,4 +75,4 @@
 * added Haversine, Spherical and Vincenty distance calculations
 
 0.1 (2006-10-31)
-* Initial release
+* Initial release

data/Gemfile

@@ -0,0 +1,7 @@
+source "https://rubygems.org"
+
+gemspec
+
+gem 'mocha'
+gem 'rake'
+gem 'rdoc'

data/LICENSE.txt

@@ -1,4 +1,4 @@
-Copyright 2006 Brandon Keepers, Collective Idea.  All rights reserved.
+Copyright 2013 Brandon Keepers, Collective Idea.  All rights reserved.
 
 Original geocoding code:
   Copyright 2006 Eric Hodel, The Robot Co-op.  All rights reserved.

data/README.md

@@ -0,0 +1,122 @@
+Graticule
+=========
+
+```
+  grat·i·cule |ˈgratəˌkyoōl|
+    Navigation. a network of parallels and meridians on a map or chart.
+```
+
+Graticule is a geocoding API for looking up address coordinates and performing distance calculations. It supports many popular APIs:
+
+* Yahoo
+* Google
+* MapQuest
+* Geocoder.ca
+* Geocoder.us
+* Geonames
+* SimpleGeo
+* Postcode Anywhere
+* MetaCarta
+* FreeThePostcode
+* LocalSearchMaps
+* Yandex
+
+### Installation
+
+```
+gem install graticule
+```
+
+### Usage
+
+There is a companion Rails plugin called [acts_as_geocodable](https://github.com/collectiveidea/acts_as_geocodable) that makes geocoding seem like magic.
+
+Graticule exposes to main APIs: location search and distance calculations. Graticule also
+provides a command line utility.
+
+#### Location Search / Geocoding
+
+```
+require 'rubygems'
+require 'graticule'
+
+geocoder = Graticule.service(:google).new "api_key"
+location = geocoder.locate("61 East 9th Street, Holland, MI")
+```
+
+For specific service documentation, please visit the [RDOCS -- rdoc.info link].
+
+#### Distance Calculation
+
+Graticule includes 3 different distance formulas, Spherical (simplest but least accurate), Vincenty (most accurate and most complicated), and Haversine (somewhere inbetween). The default is Haversine. There are two ways to calculate the distance between two points.
+
+First is `Location#distance_to`:
+
+```
+holland = geocoder.locate("Holland, MI")
+chicago = geocoder.locate("Chicago, IL")
+holland.distance_to(chicago, :formula => :haversine) # or :spherical or :vincenty
+# => 101.997458788177
+```
+
+You can also use the formula classes directly:
+
+```
+Graticule::Distance::Haversine.distance(holland, chicago)
+# => 101.997458788177
+```
+
+All units are miles by default, but you can switch to kilometers with the `units` option
+
+```
+holland.distance_to(chicago, :units => :kilometers)
+#
+Graticule::Distance::Haversine.distance(holland, chicago, :kilometers)
+```
+
+
+#### Command Line
+
+Graticule includes a command line interface (CLI). The CLI does not currently support all of the implemented services.
+
+```
+$ geocode -s google -a [api_key] Washington, DC
+Washington, DC US
+latitude: 38.895222, longitude: -77.036758
+```
+
+### Contributing
+
+In the spirit of [free software](http://www.fsf.org/licensing/essays/free-sw.html), **everyone** is encouraged to help improve this project.
+
+Here are some ways you can contribute:
+
+* Reporting bugs
+* Suggesting new features
+* Writing or editing documentation
+* Writing specifications
+* Writing code (**no patch is too small**: fix typos, add comments, clean up inconsistent whitespace)
+* Refactoring code
+* Reviewing patches
+
+### Submitting an Issue
+
+We use the [GitHub issue tracker](https://github.com/collectiveidea/graticule/issues) to track bugs and features. Before submitting a bug report or feature request, check to make sure it hasn't already been submitted. When submitting a bug report, please include a [Gist](https://gist.github.com/) that includes a stack trace and any details that may be necessary to reproduce the bug, including your gem version, Ruby version, and operating system. 
+
+### Submitting a Pull Request
+
+1. Fork the project.
+2. Create a topic branch.
+3. Implement your feature or bug fix.
+4. Add specs for your feature or bug fix.
+5. Run `rake`. If your changes are not 100% covered and passing, go back to step 4.
+6. Commit and push your changes.
+7. Submit a pull request. Please do not include changes to the gemspec, version, or history file. (If you want to create your own version for some reason, please do so in a separate commit.)
+
+### Other Links
+
+[Blog posts about Graticule](http://opensoul.org/tags/geocoding)
+
+[Geocoder: Alternative Geocoding library](https://github.com/alex.../geocoder)
+
+

data/Rakefile

@@ -0,0 +1,78 @@
+$LOAD_PATH.unshift File.expand_path("../lib", __FILE__)
+
+require 'bundler/setup'
+require 'graticule/version'
+require 'active_support'
+require 'rake/testtask'
+require 'yaml'
+
+desc 'Default: run unit tests.'
+task :default => :test
+
+task :build do
+  system "gem build graticule.gemspec"
+end
+
+task :release => :build do
+  system "gem push graticule-#{Graticule::VERSION}.gem"
+end
+
+task :install => :build do
+  system "gem install graticule-#{Graticule::VERSION}.gem"
+end
+
+desc 'Run the unit tests'
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'lib' << 'test'
+  t.pattern = 'test/**/*_test.rb'
+  t.verbose = true
+end
+
+require 'active_support'
+require 'net/http'
+require 'uri'
+RESPONSES_PATH = File.dirname(__FILE__) + '/test/fixtures/responses'
+
+def cache_responses(service)
+  test_config[service.to_s]['responses'].each do |file,url|
+    File.open("#{RESPONSES_PATH}/#{service}/#{file}", 'w') do |f|
+      f.puts Net::HTTP.get(URI.parse(url))
+    end
+  end
+end
+
+def test_config
+  file = File.dirname(__FILE__) + '/test/config.yml'
+  unless File.exists?(file)
+    raise "API keys not found.  Add them by:
+            cp #{file}.default #{file}
+            vi #{file}
+          "
+  end
+  @test_config ||= YAML.load(File.read(file)).tap do |config|
+    config.each do |service,values|
+      values['responses'].each {|f,url| update_placeholders!(values, url) }
+    end
+  end
+end
+
+def update_placeholders!(config, thing)
+  config.each do |option, value|
+    thing.gsub!(":#{option}", value) if value.is_a?(String)
+  end
+end
+
+namespace :test do
+  namespace :cache do
+    desc 'Cache test responses from all the geocoders'
+    task :all => test_config.keys
+
+    test_config.keys.each do |service|
+      desc "Cache test responses for #{service}"
+      task service do
+        cache_responses(service)
+      end
+    end
+  end
+end
+

data/graticule.gemspec

@@ -0,0 +1,26 @@
+# encoding: utf-8
+
+require File.expand_path("../lib/graticule/version.rb", __FILE__)
+
+Gem::Specification.new do |spec|
+  spec.name    = "graticule"
+  spec.version = Graticule::VERSION
+
+  spec.authors     = ["Brandon Keepers", "Daniel Morrison", "Collective Idea"]
+  spec.email       = ["brandon@opensoul.org", "daniel@collectiveidea.com", "code@collectiveidea.com"]
+  spec.description = "Graticule is a geocoding API that provides a common interface to all the popular services, including Google, Yahoo, Geocoder.us, and MetaCarta."
+  spec.summary     = "API for using all the popular geocoding services"
+  spec.homepage    = "https://github.com/collectiveidea/graticule"
+  spec.license     = "MIT"
+
+  spec.files         = `git ls-files`.split($\)
+  spec.test_files    = spec.files.grep(/^test/)
+  spec.executables   = ["geocode"]
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency "activesupport"
+  spec.add_dependency "i18n"
+  spec.add_dependency "happymapper", ">= 0.3.0"
+  spec.add_dependency "json"
+end
+

data/lib/graticule/cli.rb

@@ -23,13 +23,15 @@ module Graticule
 
     def self.start(args, out = STDOUT)
       options = { :service => :yahoo, :api_key => 'YahooDemo' }
+      supported_services = %w(yahoo google yandex geocoder_us metacarta)
 
       OptionParser.new do |opts|
         opts.banner = "Usage: geocode [options] location"
         opts.separator ""
         opts.separator "Options: "
 
-        opts.on("-s service", %w(yahoo google yandex geocoder_us metacarta), "--service service", "Geocoding service") do |service|
+        opts.on("-s service", supported_services, "--service service",
+                "Geocoding service.", "Currently supported services: #{supported_services.join(", ")}") do |service|
           options[:service] = service
         end
 

data/lib/graticule/geocoder/google.rb

@@ -2,16 +2,21 @@
 require 'json'
 module Graticule #:nodoc:
   module Geocoder #:nodoc:
-    #   gg = Graticule.service(:google).new(MAPS_API_KEY) API Key is not required
+    #   gg = Graticule.service(:google).new
     #   location = gg.locate '1600 Amphitheater Pkwy, Mountain View, CA'
     #   p location.coordinates
     #   #=> [37.423111, -122.081783
     #
+    # If you have a Google business account, initialize with:
+    #
+    #   gg = Graticule.service(:google).new(MAPS_API_KEY, MAPS_CLIENT_ID)
+    #
     class Google < Base
       # https://developers.google.com/maps/documentation/geocoding/
 
-      def initialize(key)
+      def initialize(key=nil, client_id=nil)
         @key = key
+        @client_id = client_id
         @url = URI.parse 'http://maps.googleapis.com/maps/api/geocode/json'
       end
 
@@ -129,9 +134,33 @@ module Graticule #:nodoc:
       end
 
       # Creates a URL from the Hash +params+..
+      #
+      # If initialized with a key and client id for a Business account, signs
+      # the url as required by v3 of the library:
+      #
+      # https://developers.google.com/maps/documentation/business/webservices#digital_signatures
+      # 
       def make_url(params) #:nodoc:
-        super params.merge(:key => @key, :sensor => false)
+        if @key && @client_id
+          url = super params.merge(:sensor => false, :client => @client_id)
+          make_signed_url(url)
+        else
+          super params.merge(:sensor => false)
+        end
       end
+
+      def make_signed_url(original_url) #:nodoc:
+        require "base64"
+        require 'openssl'
+        url_to_sign = "#{original_url.path}?#{original_url.query}"
+        decoded_key = Base64.decode64(@key.tr("-_", "+/"))
+        signature = OpenSSL::HMAC.digest('sha1', decoded_key, url_to_sign)
+        encoded_signature = Base64.encode64(signature).tr("+/", "-_")
+        signed_url = original_url.to_s + "&signature=#{encoded_signature}"
+        #puts signed_url
+        URI.parse signed_url
+      end
+
     end
   end
-end
+end

data/lib/graticule/geocoder/mapquest.rb

@@ -1,40 +1,19 @@
-require 'htmlentities'
-
 # encoding: UTF-8
 module Graticule #:nodoc:
   module Geocoder #:nodoc:
 
-    # Mapquest requires both a client id and a password, which you can
-    # get by registering at:
-    # http://developer.mapquest.com/Home/Register?_devAPISignup_WAR_devAPISignup_action=signup&_devAPISignup_WAR_devAPISignup_clientType=Developer
+    # Mapquest uses the Licenced Community API which requires an api key. You can sign up an account
+    # and get an api key by registering at: http://developer.mapquest.com/
     #
-    # mq = Graticule.service(:mapquest).new(CLIENT_ID, PASSWORD)
+    # mq = Graticule.service(:mapquest).new(API_KEY)
     # location = gg.locate('44 Allen Rd., Lovell, ME 04051')
     # [42.78942, -86.104424]
     #
     class Mapquest < Base
-      # I would link to the documentation here, but there is none that will do anything but confuse you.
-
-      PRECISION = {
-        'L1' => Precision::Address,
-        'I1' => Precision::Street,
-        'B1' => Precision::Street,
-        'B2' => Precision::Street,
-        'B3' => Precision::Street,
-        'Z3' => Precision::PostalCode,
-        'Z4' => Precision::PostalCode,
-        'Z2' => Precision::PostalCode,
-        'Z1' => Precision::PostalCode,
-        'A5' => Precision::Locality,
-        'A4' => Precision::Region,
-        'A3' => Precision::Region,
-        'A1' => Precision::Country
-      }
 
-      def initialize(client_id, password)
-        @password = password
-        @client_id = client_id
-        @url = URI.parse('http://geocode.dev.mapquest.com/mq/mqserver.dll')
+      def initialize(api_key)
+        @api_key = api_key
+        @url = URI.parse('http://www.mapquestapi.com/geocoding/v1/address')
       end
 
       # Locates +address+ returning a Location
@@ -45,66 +24,80 @@ module Graticule #:nodoc:
       protected
 
       def make_url(params) #:nodoc
-        request = Mapquest::Request.new(params[:q], @client_id, @password)
+        request = Mapquest::Request.new(params[:q], @api_key)
         url = @url.dup
-        url.query = escape(request.query)
+        url.query = request.query
         url
       end
 
       class Request
-        def initialize(address, client_id, password)
+        def initialize(address, api_key)
           @address = address
-          @client_id = client_id
-          @password = password
+          @api_key = api_key
         end
 
         def query
-          "e=5&<?xml version=\"1.0\" encoding=\"ISO-8859-1\"?><Geocode Version=\"1\">#{address_string}#{authentication_string}</Geocode>"
-        end
-
-        def address_string
-          "<Address><Street>#{escaped_address}</Street></Address><GeocodeOptionsCollection Count=\"0\"/>"
-        end
-        
-        def authentication_string
-          "<Authentication Version=\"2\"><Password>#{@password}</Password><ClientId>#{@client_id}</ClientId></Authentication>"
-        end
-
-        def escaped_address
-          HTMLEntities.new.encode(@address, :basic)
+          "key=#{URI.escape(@api_key)}&outFormat=xml&inFormat=kvp&location=#{URI.escape(@address)}"
         end
       end
 
+      # See http://www.mapquestapi.com/geocoding/geocodequality.html#granularity
+      PRECISION = {
+        'P1' => Precision::Point,
+        'L1' => Precision::Address,
+        'I1' => Precision::Street,
+        'B1' => Precision::Street,
+        'B2' => Precision::Street,
+        'B3' => Precision::Street,
+        'Z3' => Precision::PostalCode,
+        'Z4' => Precision::PostalCode,
+        'Z2' => Precision::PostalCode,
+        'Z1' => Precision::PostalCode,
+        'A5' => Precision::Locality,
+        'A4' => Precision::Region,
+        'A3' => Precision::Region,
+        'A1' => Precision::Country
+      }
+
       class Address
         include HappyMapper
-        tag 'GeoAddress'
-        element :latitude, Float, :tag => 'Lat', :deep => true
-        element :longitude, Float, :tag => 'Lng', :deep => true
-        element :street, String, :tag => 'Street'
-        element :locality, String, :tag => 'AdminArea5'
-        element :region, String, :tag => 'AdminArea3'
-        element :postal_code, String, :tag => 'PostalCode'
-        element :country, String, :tag => 'AdminArea1'
-        element :result_code, String, :tag => 'ResultCode'
+        tag 'location'
+        element :latitude, Float, :tag => 'lat', :deep => true
+        element :longitude, Float, :tag => 'lng', :deep => true
+        element :street, String, :tag => 'street'
+        element :locality, String, :tag => 'adminArea5'
+        element :region, String, :tag => 'adminArea3'
+        element :postal_code, String, :tag => 'postalCode'
+        element :country, String, :tag => 'adminArea1'
+        element :result_code, String, :tag => 'geocodeQualityCode'
 
         def precision
           PRECISION[result_code.to_s[0,2]] || :unknown
         end
       end
 
+      class Locations
+        include HappyMapper
+        has_many :addresses, Address, :tag => "location"
+      end
+
       class Result
         include HappyMapper
-        tag 'GeocodeResponse'
-        has_many :addresses, Address, :deep => true
+        has_one :locations, Locations, :tag => "locations"
+      end
+
+      class Response
+        include HappyMapper
+        has_one :result, Result, :deep => true
       end
 
       def prepare_response(xml)
-        Result.parse(xml, :single => true)
+        Response.parse(xml, :single => true)
       end
 
       # Extracts a location from +xml+.
-      def parse_response(result) #:nodoc:
-        addr = result.addresses.first
+      def parse_response(response) #:nodoc:
+        addr = response.result.locations.addresses.first
         Location.new(
           :latitude    => addr.latitude,
           :longitude   => addr.longitude,