periplus 0.2.0 → 0.3.0

data/README.rdoc

@@ -1,17 +1,23 @@
 = periplus
 
-Bing Maps REST API client.
+Simple Bing Maps REST API client.
+
+Currently supports:
+
+* Routing
+* Geocoding
+* Mapping
 
 == Use it
   require 'periplus'
 
-  my_request = Periplus::Request.new 'my_bing_key'
-  response = my_request.route [{:street => "1600 Pennsylvania Ave.",
-                                :city => "Washington",
-                                :state => "DC",
-                                :postal_code => "20500"},
-                               {:postal_code => "90210"}],
-                              :distanceUnit => :mi
+  response = Periplus.route_details 'my_bing_key',
+                                     [{:street => "1600 Pennsylvania Ave.",
+                                       :city => "Washington",
+                                       :state => "DC",
+                                       :postal_code => "20500"},
+                                      {:postal_code => "90210"}],
+                                     :distanceUnit => :mi
 
   puts "#{response.distance} #{response.distance_units.to_s}.pluralize, #{response.duration} seconds"
   # "2665.06415 miles, 137797 seconds"

data/VERSION

@@ -1 +1 @@
-0.2.0
+0.3.0

data/lib/periplus.rb

@@ -8,6 +8,16 @@ module Periplus
   include HTTParty
   format :json
 
+  @verbose = false
+  
+  def self.verbose=(value)
+    @verbose = value
+  end
+  
+  def self.verbose
+    @verbose
+  end
+  
   def self.route_details(key, waypoints, options = {})
     request = Request.new key
     url = request.route_details_url waypoints, options
@@ -20,13 +30,13 @@ module Periplus
     Location.new (get url)
   end
 
-  def self.route_map_url(key, waypoints, options = {})
+  def self.route_map_url(key, waypoints, pushpins = [], options = {})
     request = Request.new key
-    request.route_map_url waypoints, options
+    request.route_map_url waypoints, pushpins, options
   end
 
-  def self.address_map_url(key, address, options = {})
+  def self.address_map_url(key, address, pushpins = [], options = {})
     request = Request.new key
-    request.address_map_url address, options
+    request.address_map_url address, pushpins, options
   end
 end

data/lib/periplus/bing_response.rb

@@ -1,13 +1,11 @@
+require 'pp'
+
 module Periplus
   class BingResponse
     def initialize(httparty_response)
       @response = httparty_response
 
-      if @response.response.kind_of? Net::HTTPClientError
-        http_code = @response.response.code
-        http_message = @response.response.message
-        raise "An error has occurred communicating with the Bing Maps service. HTTP Status: #{http_code} (#{http_message})"
-      end
+      raise error if @response.response.kind_of? Net::HTTPClientError
 
       parse
     end
@@ -21,5 +19,17 @@ module Periplus
 
       @primary_resource = resources.first
     end
+    
+    def error
+      http_code = @response.response.code
+      http_message = @response.response.message
+      message = "An error has occurred communicating with the Bing Maps service. HTTP Status: #{http_code} (#{http_message})"
+      if Periplus.verbose
+        message << "\n  URL: #{@response.request.path}"
+        message << "\n  Response:"
+        message << "\n  #{PP.pp(@response.response.body, "")}"
+      end
+      message
+    end
   end
 end

data/lib/periplus/request.rb

@@ -7,7 +7,7 @@ module Periplus
       @api_key = api_key
     end
     
-    BING_URL = "http://dev.virtualearth.net/REST/v1/"
+    BING_MAPS_URL = "http://dev.virtualearth.net/REST/v1/"
     ROUTE_PATH = "Routes"
     LOCATION_PATH = "Locations"
     ROUTE_IMAGE_PATH = "Imagery/Map/Road/Routes/Driving"
@@ -17,24 +17,48 @@ module Periplus
       options = default_options(options).merge(hashify_waypoints(waypoints))
                                         .merge(:o => "json")
 
-      "#{BING_URL}#{ROUTE_PATH}?#{options.to_params}"
+      "#{BING_MAPS_URL}#{ROUTE_PATH}?#{options.to_params}"
     end
 
-    def route_map_url(waypoints, options = {})
+    # Generate a URL for a routes map.
+    #
+    # * waypoints is a list of hashes or objects with properties or keys like
+    #   street, address, city, state, province, etc.
+    # * pushpins is an optional list of hashes with :latitude, :longitude, 
+    #   :type (optional -- 1, 2, 3, etc. per the bing spec) or :label (optional -- no longer than 2 characters per bing spec)
+    # * options is a hash that gets turned directly into url params for bing
+    def route_map_url(waypoints, pushpins = [], options = {})
       options = options.merge(hashify_waypoints(waypoints))
                        .merge(:key => @api_key)
-      "#{BING_URL}#{ROUTE_IMAGE_PATH}?#{options.to_params}"
+      base = "#{BING_MAPS_URL}#{ROUTE_IMAGE_PATH}?#{options.to_params}"
+      if pushpins and pushpins.length > 0
+        formatted_pins = pushpins.map {|p| "pp=#{format_pushpin(p)}" }.join '&'
+        base = "#{base}&#{formatted_pins}" if pushpins
+      end
+      base
     end
 
-    def address_map_url(address, options = {})
+    # Generate a URL for a location map
+    #
+    # * address is a hash or object with properties or keys like
+    #   street, address, city, state, province, etc.
+    # * pushpins is an optional list of hashes with :latitude, :longitude, 
+    #   :type (optional -- 1, 2, 3, etc. per the bing spec) or :label (optional -- no longer than 2 characters per bing spec)
+    # * options is a hash that gets turned directly into url params for bing
+    def address_map_url(address, pushpins = [], options = {})
       options = default_options(options)
-      "#{BING_URL}#{QUERY_IMAGE_PATH}#{URI.escape(format_waypoint(address))}?#{options.to_params}"
+      base = "#{BING_MAPS_URL}#{QUERY_IMAGE_PATH}#{URI.escape(format_waypoint(address))}?#{options.to_params}"
+      if pushpins and pushpins.length > 0
+        formatted_pins = pushpins.map {|p| "pp=#{format_pushpin(p)}" }.join '&'
+        base = "#{base}&#{formatted_pins}" if pushpins
+      end
+      base
     end
 
     def location_details_url(address, options = {})
       options = default_options(options).merge(:o => "json")
                                         .merge(structure_address(address))
-      "#{BING_URL}#{LOCATION_PATH}?#{options.to_params}"
+      "#{BING_MAPS_URL}#{LOCATION_PATH}?#{options.to_params}"
     end
 
    private
@@ -66,10 +90,15 @@ module Periplus
         object.send key_or_attribute
       end
     end
+
+    def format_pushpin(pushpin)
+      "#{pushpin[:latitude]},#{pushpin[:longitude]};#{pushpin[:type] || ""};#{pushpin[:label] || ""}"
+    end
     
     ADDRESS_STRUCTURE = {
       :street => :addressLine,
       :address => :addressLine,
+      :name => :addressLine,
       :city => :locality,
       :state => :adminDistrict,
       :province => :adminDistrict,
@@ -82,13 +111,15 @@ module Periplus
     }
 
     def structure_address(address)
+      return {:query => address} if address.kind_of? String
+
       ADDRESS_STRUCTURE.inject({}) do |structured, key_val|
         unconverted, converted = key_val
         
         if has_key_or_attribute? address, converted
-          structured[converted] = get_by_key_or_attribute address, converted
+          structured[converted] ||= get_by_key_or_attribute address, converted
         elsif has_key_or_attribute? address, unconverted
-          structured[converted] = get_by_key_or_attribute address, unconverted
+          structured[converted] ||= get_by_key_or_attribute address, unconverted
         end
         structured
       end
@@ -110,6 +141,14 @@ module Periplus
     def format_waypoint(waypoint)
       return waypoint if waypoint.instance_of? String
       
+      # use lat/long if provided
+      if has_key_or_attribute?(waypoint, :latitude) and
+          has_key_or_attribute?(waypoint, :longitude)
+        latitude = get_by_key_or_attribute waypoint, :latitude
+        longitude = get_by_key_or_attribute waypoint, :longitude
+        return "#{latitude},#{longitude}" if latitude and longitude
+      end
+      
       if WAYPOINT_FORMAT
           .find_all { |el| el.instance_of? Symbol }
           .any? { |key| has_key_or_attribute?(waypoint, key) }

data/periplus.gemspec

@@ -5,11 +5,11 @@
 
 Gem::Specification.new do |s|
   s.name = %q{periplus}
-  s.version = "0.2.0"
+  s.version = "0.3.0"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
-  s.authors = ["Ryan Crum"]
-  s.date = %q{2011-06-22}
+  s.authors = [%q{Ryan Crum}]
+  s.date = %q{2011-08-03}
   s.description = %q{A library that behaves as a client for the Bing Maps REST sdk}
   s.email = %q{ryan.j.crum@gmail.com}
   s.extra_rdoc_files = [
@@ -31,7 +31,7 @@ Gem::Specification.new do |s|
     "lib/periplus/request.rb",
     "lib/periplus/route.rb",
     "periplus.gemspec",
-    "spec/bing_response.spec",
+    "spec/bing_response_spec.rb",
     "spec/location_spec.rb",
     "spec/periplus_spec.rb",
     "spec/request_spec.rb",
@@ -39,9 +39,9 @@ Gem::Specification.new do |s|
     "spec/spec_helper.rb"
   ]
   s.homepage = %q{http://github.com/thorstadt/periplus}
-  s.licenses = ["MIT"]
-  s.require_paths = ["lib"]
-  s.rubygems_version = %q{1.6.2}
+  s.licenses = [%q{MIT}]
+  s.require_paths = [%q{lib}]
+  s.rubygems_version = %q{1.8.5.1}
   s.summary = %q{Bing Maps REST Client}
 
   if s.respond_to? :specification_version then

data/spec/bing_response_spec.rb

@@ -0,0 +1,60 @@
+require File.expand_path(File.dirname(__FILE__) + '/spec_helper')
+
+describe Periplus::BingResponse do
+  it "throws an exception if the httparty response is HTTP status 4xx" do
+    http_error = Net::HTTPUnauthorized.new "1_1", 401, "Unauthorized"
+    response = mock HTTParty::Response, :response => http_error
+    
+    lambda do
+      Periplus::BingResponse.new(response)
+    end.should raise_error(RuntimeError, "An error has occurred communicating with the Bing Maps service. HTTP Status: 401 (Unauthorized)")
+  end
+
+  it "provides helpful debugging information for service failrues" do
+    http_error = Net::HTTPNotFound.new("1_1", 404, "Not Found")
+    http_error.stub!(:body).and_return(
+      {:some_really_long_properties_that_extend => {:deeply_past_the_place_where => {:they_wrap => "stuff"}}}
+    )
+    http_request = HTTParty::Request.new "GET", "/API/cheese"
+    response = mock HTTParty::Response, :response => http_error,
+                                        :request => http_request
+    
+    Periplus.verbose = true
+    
+    lambda do
+      begin
+        Periplus::BingResponse.new(response)
+      rescue RuntimeError => e
+        e.message.should == <<-EOF
+An error has occurred communicating with the Bing Maps service. HTTP Status: 404 (Not Found)
+  URL: /API/cheese
+  Response:
+  {:some_really_long_properties_that_extend=>
+  {:deeply_past_the_place_where=>{:they_wrap=>"stuff"}}}
+        EOF
+        raise e
+      end
+    end.should raise_error(RuntimeError)
+  end
+
+  it "throws an exception if the httparty response contains no routes" do
+    http_ok = Net::HTTPOK.new "1_1", 200, "OK"
+    empty_resource_sets = {
+      "resourceSets" => []
+    }
+
+    empty_single_resource_set = {
+      "resourceSets" => [{"resources" => []}]
+    }
+
+    [empty_resource_sets, empty_single_resource_set].each do |parsed_response|
+      response = mock HTTParty::Response, :response => http_ok, :parsed_response => parsed_response
+      
+      begin
+        Periplus::BingResponse.new(response)
+      rescue Exception => e
+        e.message.should == "Not found."
+      end
+    end
+  end
+end

data/spec/request_spec.rb

@@ -47,11 +47,11 @@ describe "Request" do
 
   it "formats an address object correctly" do
     class PeriplusAddress
-      attr_accessor :address
-      attr_accessor :city
-      attr_accessor :state
-      attr_accessor :country
-      attr_accessor :postal_code
+      attr_accessor :address,
+        :city,
+        :state,
+        :country,
+        :postal_code
     end
 
     address = PeriplusAddress.new 
@@ -67,6 +67,32 @@ describe "Request" do
     formatted.should == "1600 Pennsylvania Ave Washington, DC US 20500"
   end
 
+  it "formats an address object correctly with latitude/longitude" do
+    class PeriplusAddress
+      attr_accessor :address, 
+        :city,
+        :state,
+        :country,
+        :postal_code,
+        :latitude,
+        :longitude  
+    end
+
+    address = PeriplusAddress.new 
+    address.address = "1600 Pennsylvania Ave"
+    address.city = "Washington"
+    address.state = "DC"
+    address.country = "US"
+    address.postal_code = 20500
+    address.latitude = "40.32332"
+    address.longitude = "-2.32142"
+    
+    req = Periplus::Request.new 'fake key'
+    formatted = req.send :format_waypoint, address
+
+    formatted.should == "40.32332,-2.32142"
+  end
+
   it "builds a location details url correctly" do
     address = {
       :street => "1600 Pennsylvania Ave",
@@ -80,4 +106,64 @@ describe "Request" do
     url = req.location_details_url address
     url.should == "http://dev.virtualearth.net/REST/v1/Locations?key=fake%20key&o=json&addressLine=1600%20Pennsylvania%20Ave&locality=Washington&adminDistrict=DC&countryRegion=US&postalCode=20500"
   end
+
+  it "builds a location details url from a query string correctly" do
+    address = "1600 Pennsylvania Ave Washington, DC"
+    req = Periplus::Request.new 'fake key'
+    url = req.location_details_url address
+    url.should == "http://dev.virtualearth.net/REST/v1/Locations?key=fake%20key&o=json&query=1600%20Pennsylvania%20Ave%20Washington%2C%20DC"
+  end
+
+  it "builds a location details url correctly with a place name" do
+    address = {
+      :name => "The White House",
+      :city => "Washington",
+      :state => "DC",
+      :country => "US",
+      :zip => 20500
+    }
+
+    req = Periplus::Request.new 'fake key'
+    url = req.location_details_url address
+    url.should == "http://dev.virtualearth.net/REST/v1/Locations?key=fake%20key&o=json&addressLine=The%20White%20House&locality=Washington&adminDistrict=DC&countryRegion=US&postalCode=20500"
+  end
+
+  it "builds a location details url correctly with a place name and an address" do
+    address = {
+      :name => "The White House",
+      :street => "1600 Pennsylvania Ave",
+      :city => "Washington",
+      :state => "DC",
+      :country => "US",
+      :zip => 20500
+    }
+
+    req = Periplus::Request.new 'fake key'
+    url = req.location_details_url address
+    url.should == "http://dev.virtualearth.net/REST/v1/Locations?key=fake%20key&o=json&addressLine=1600%20Pennsylvania%20Ave&locality=Washington&adminDistrict=DC&countryRegion=US&postalCode=20500"
+  end
+
+  it "formats pushpins correctly" do
+    req = Periplus::Request.new 'fake key'
+
+    pushpin = {:latitude => 1337, :longitude => 42.24}
+    formatted = req.send :format_pushpin, pushpin
+    formatted.should == "1337,42.24;;"
+
+    pushpin = {:latitude => 1337, :longitude => 42.24, :label => "pi"}
+    formatted = req.send :format_pushpin, pushpin
+    formatted.should == "1337,42.24;;pi"
+
+    pushpin = {:latitude => 1337, :longitude => 42.24, :type => 3, :label => "pi"}
+    formatted = req.send :format_pushpin, pushpin
+    formatted.should == "1337,42.24;3;pi"
+  end
+
+  it "formats a route url correctly with pushpins" do
+    req = Periplus::Request.new 'fake_key'
+    
+    waypoints = ["New York, NY", "Buffalo, NY", "Louisville, KY"]
+    url = req.route_map_url waypoints, [{:latitude => 1337, :longitude => 42}, {:latitude => 42, :longitude => 1337, :label => "sw"}]
+    url.should == "http://dev.virtualearth.net/REST/v1/Imagery/Map/Road/Routes/Driving?wp.1=New%20York%2C%20NY&wp.2=Buffalo%2C%20NY&wp.3=Louisville%2C%20KY&key=fake_key&pp=1337,42;;&pp=42,1337;;sw"
+  end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: periplus
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
   prerelease: 
 platform: ruby
 authors:
@@ -9,12 +9,11 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2011-06-22 00:00:00.000000000 -04:00
-default_executable: 
+date: 2011-08-03 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: httparty
-  requirement: &2168771280 !ruby/object:Gem::Requirement
+  requirement: &7342460 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -22,10 +21,10 @@ dependencies:
         version: '0'
   type: :runtime
   prerelease: false
-  version_requirements: *2168771280
+  version_requirements: *7342460
 - !ruby/object:Gem::Dependency
   name: activesupport
-  requirement: &2168769920 !ruby/object:Gem::Requirement
+  requirement: &7341160 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -33,10 +32,10 @@ dependencies:
         version: '0'
   type: :runtime
   prerelease: false
-  version_requirements: *2168769920
+  version_requirements: *7341160
 - !ruby/object:Gem::Dependency
   name: rspec
-  requirement: &2168769200 !ruby/object:Gem::Requirement
+  requirement: &7339640 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -44,10 +43,10 @@ dependencies:
         version: 2.4.0
   type: :development
   prerelease: false
-  version_requirements: *2168769200
+  version_requirements: *7339640
 - !ruby/object:Gem::Dependency
   name: bundler
-  requirement: &2168768480 !ruby/object:Gem::Requirement
+  requirement: &7338260 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -55,10 +54,10 @@ dependencies:
         version: 1.0.0
   type: :development
   prerelease: false
-  version_requirements: *2168768480
+  version_requirements: *7338260
 - !ruby/object:Gem::Dependency
   name: jeweler
-  requirement: &2168790180 !ruby/object:Gem::Requirement
+  requirement: &7337440 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -66,10 +65,10 @@ dependencies:
         version: 1.6.2
   type: :development
   prerelease: false
-  version_requirements: *2168790180
+  version_requirements: *7337440
 - !ruby/object:Gem::Dependency
   name: rcov
-  requirement: &2168817340 !ruby/object:Gem::Requirement
+  requirement: &7336020 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -77,7 +76,7 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *2168817340
+  version_requirements: *7336020
 description: A library that behaves as a client for the Bing Maps REST sdk
 email: ryan.j.crum@gmail.com
 executables: []
@@ -100,13 +99,12 @@ files:
 - lib/periplus/request.rb
 - lib/periplus/route.rb
 - periplus.gemspec
-- spec/bing_response.spec
+- spec/bing_response_spec.rb
 - spec/location_spec.rb
 - spec/periplus_spec.rb
 - spec/request_spec.rb
 - spec/route_spec.rb
 - spec/spec_helper.rb
-has_rdoc: true
 homepage: http://github.com/thorstadt/periplus
 licenses:
 - MIT
@@ -122,7 +120,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: -1957350740199156852
+      hash: 94696388149448647
 required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
   requirements:
@@ -131,7 +129,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 1.6.2
+rubygems_version: 1.8.5.1
 signing_key: 
 specification_version: 3
 summary: Bing Maps REST Client

data/spec/bing_response.spec

@@ -1,36 +0,0 @@
-require 'periplus'
-require File.expand_path(File.dirname(__FILE__) + '/spec_helper')
-
-describe "BingResponse" do
-  it "throws an exception if the httparty response is HTTP status 4xx" do
-    http_error = Net::HTTPUnauthorized.new "1_1", 401, "Unauthorized"
-    response = mock HTTParty::Response, :response => http_error
-    
-    begin
-      Periplus::BingResponse.new(response)
-    rescue Exception => e
-      e.message.should == "An error has occurred communicating with the Bing Maps service. HTTP Status: 401 (Unauthorized)"
-    end
-  end
-
-  it "throws an exception if the httparty response contains no routes" do
-    http_ok = Net::HTTPOK.new "1_1", 200, "OK"
-    empty_resource_sets = {
-      "resourceSets" => []
-    }
-
-    empty_single_resource_set = {
-      "resourceSets" => [{"resources" => []}]
-    }
-
-    [empty_resource_sets, empty_single_resource_set].each do |parsed_response|
-      response = mock HTTParty::Response, :response => http_ok, :parsed_response => parsed_response
-      
-      begin
-        Periplus::BingResponse.new(response)
-      rescue Exception => e
-        e.message.should == "Not found."
-      end
-    end
-  end
-end