graticule 0.1.1

data/lib/graticule/geocoders/meta_carta.rb

@@ -0,0 +1,102 @@
+
+module Graticule
+
+  # Library for looking up coordinates with MetaCarta's GeoParser API.
+  #
+  # http://labs.metacarta.com/GeoParser/documentation.html
+  class MetaCartaGeocoder < RestGeocoder
+    Location = Struct.new :name, :type, :population, :hierarchy,
+                          :latitude, :longitude, :confidence, :viewbox
+
+    def initialize # :nodoc:
+      @url = URI.parse 'http://labs.metacarta.com/GeoParser/'
+    end
+
+    # Locates +place+ and returns a Location object.
+    def locate(place)
+      locations, = get :q => place
+      return locations.first
+    end
+
+    # Retrieve all locations matching +place+.
+    #
+    # Returns an Array of Location objects and a pair of coordinates that will
+    # surround them.
+    def locations(place)
+      get :loc => place
+    end
+
+    def check_error(xml) # :nodoc:
+      raise AddressError, 'bad location' unless xml.elements['Locations/Location']
+    end
+
+    def make_url(params) # :nodoc:
+      params[:output] = 'locations'
+
+      super params
+    end
+
+    def parse_response(xml) # :nodoc:
+      locations = []
+
+      xml.elements['/Locations'].each do |l|
+        next if REXML::Text === l or l.name == 'ViewBox'
+        location = Location.new
+
+        location.viewbox = viewbox_coords l.elements['ViewBox/gml:Box/gml:coordinates']
+
+        location.name = l.attributes['Name']
+        location.type = l.attributes['Type']
+        population = l.attributes['Population'].to_i
+        location.population = population > 0 ? population : nil
+        location.hierarchy = l.attributes['Hierarchy']
+
+        coords = l.elements['Centroid/gml:Point/gml:coordinates'].text.split ','
+        location.latitude = coords.first.to_f
+        location.longitude = coords.last.to_f
+
+        confidence = l.elements['Confidence']
+        location.confidence = confidence.text.to_f if confidence
+
+        locations << location
+      end
+
+      query_viewbox = xml.elements['/Locations/ViewBox/gml:Box/gml:coordinates']
+
+      return locations, viewbox_coords(query_viewbox)
+    end
+
+    # Turns a element containing a pair of coordinates into a pair of coordinate
+    # Arrays.
+    def viewbox_coords(viewbox) # :nodoc:
+      return viewbox.text.split(' ').map do |coords|
+        coords.split(',').map { |c| c.to_f }
+      end
+    end
+
+  end
+
+  # A Location contains the following fields:
+  #
+  # +name+:: The name of this location
+  # +type+:: The type of this location (no clue what it means)
+  # +population+:: The number of people who live here or nil
+  # +hierarchy+:: The places above this place
+  # +latitude+:: Latitude of the location
+  # +longitude+:: Longitude of the location
+  # +confidence+:: Accuracy confidence (if any)
+  # +viewbox+:: Pair of coordinates forming a box around this place
+  # 
+  # viewbox runs from lower left to upper right.
+  class MetaCartaGeocoder::Location
+
+    ##
+    # The latitude and longitude for this location.
+
+    def coordinates
+      [latitude, longitude]
+    end
+
+  end
+
+end

data/lib/graticule/geocoders/rest.rb

@@ -0,0 +1,98 @@
+require 'open-uri'
+require 'rexml/document'
+
+module Graticule #:nodoc:
+
+  # Abstract class for implementing REST APIs.
+  #
+  # === Example
+  #
+  # The following methods must be implemented in sublcasses:
+  #
+  # +initialize+:: Sets @url to the service enpoint.
+  # +check_error+:: Checks for errors in the server response.
+  # +parse_response+:: Extracts information from the server response.
+  #
+  # If you have extra URL paramaters (application id, output type) or need to
+  # perform URL customization, override +make_url+.
+  #
+  #   class FakeService < RCRest
+  #   
+  #     class Error < RCRest::Error; end
+  #   
+  #     def initialize(appid)
+  #       @appid = appid
+  #       @url = URI.parse 'http://example.com/test'
+  #     end
+  #   
+  #     def check_error(xml)
+  #       raise Error, xml.elements['error'].text if xml.elements['error']
+  #     end
+  #   
+  #     def make_url(params)
+  #       params[:appid] = @appid
+  #       super params
+  #     end
+  #   
+  #     def parse_response(xml)
+  #       return xml
+  #     end
+  #   
+  #     def test(query)
+  #       get :q => query
+  #     end
+  #   
+  #   end
+  class RestGeocoder < Geocoder
+
+    # Web services initializer.
+    #
+    # Concrete web services implementations must set the +url+ instance
+    # variable which must be a URI.
+    def initialize
+      raise NotImplementedError
+    end
+
+    # Must extract and raise an error from +xml+, an REXML::Document, if any.
+    # Must returns if no error could be found.
+    def check_error(xml)
+      raise NotImplementedError
+    end
+
+    # Performs a GET request with +params+.  Calls the parse_response method on
+    # the concrete class with an REXML::Document instance and returns its
+    # result.
+    def get(params = {})
+      url = make_url params
+
+      url.open do |response|
+        res = REXML::Document.new response.read
+        check_error(res)
+        return parse_response(res)
+      end
+    rescue OpenURI::HTTPError => e
+      response = REXML::Document.new e.io.read
+      check_error response
+      raise
+    end
+
+    # Creates a URI from the Hash +params+.  Override this then call super if
+    # you need to add extra params like an application id or output type.
+    def make_url(params)
+      escaped_params = params.sort_by { |k,v| k.to_s }.map do |k,v|
+        "#{URI.escape k.to_s}=#{URI.escape v.to_s}"
+      end
+
+      url = @url.dup
+      url.query = escaped_params.join '&'
+      return url
+    end
+
+    # Must parse results from +xml+, an REXML::Document, into something sensible
+    # for the API.
+    def parse_response(xml)
+      raise NotImplementedError
+    end
+
+  end
+end

data/lib/graticule/geocoders/yahoo.rb

@@ -0,0 +1,101 @@
+module Graticule #:nodoc:
+  
+  # Yahoo geocoding API.
+  #
+  # http://developer.yahoo.com/maps/rest/V1/geocode.html
+  class YahooGeocoder < RestGeocoder
+
+    PRECISION = {
+      "country"=> :country,
+      "state" => :state,
+      "city" => :city,
+      "zip+4" => :zip,
+      "zip+2" => :zip,
+      "zip" => :zip,
+      "street" => :street,
+      "address" => :address
+    }
+
+    # Web services initializer.
+    #
+    # The +appid+ is the Application ID that uniquely identifies your
+    # application.  See: http://developer.yahoo.com/faq/index.html#appid
+    #
+    # Concrete web services implementations need to set the following instance
+    # variables then call super:
+    #
+    # +host+:: API endpoint hostname
+    # +service_name+:: service name
+    # +version+:: service name version number
+    # +method+:: service method call
+    #
+    # See http://developer.yahoo.com/search/rest.html
+    def initialize(appid)
+      @host = 'api.local.yahoo.com'
+      @service_name = 'MapsService'
+      @version = 'V1'
+      @method = 'geocode'
+      @appid = appid
+      @url = URI.parse "http://#{@host}/#{@service_name}/#{@version}/#{@method}"
+    end
+
+    # Returns a Location for +address+.
+    #
+    # The +address+ can be any of:
+    # * city, state
+    # * city, state, zip
+    # * zip
+    # * street, city, state
+    # * street, city, state, zip
+    # * street, zip
+    def locate(address)
+      get :location => address
+    end
+
+    def parse_response(xml) # :nodoc:
+      locations = []
+
+      xml.elements['ResultSet'].each do |r|
+        location = Location.new
+
+        location.precision = PRECISION[r.attributes['precision']] || :unknown
+
+        if r.attributes.include? 'warning' then
+          location.warning = r.attributes['warning']
+        end
+
+        location.latitude = r.elements['Latitude'].text.to_f
+        location.longitude = r.elements['Longitude'].text.to_f
+
+        location.street = r.elements['Address'].text.titleize unless r.elements['Address'].text.blank?
+        location.city = r.elements['City'].text.titleize unless r.elements['City'].text.blank?
+        location.state = r.elements['State'].text
+        location.zip = r.elements['Zip'].text
+        location.country = r.elements['Country'].text
+
+        locations << location
+      end
+
+      # FIXME: make API consistent and only return 1 location
+      return locations
+    end
+
+    # Extracts and raises an error from +xml+, if any.
+    def check_error(xml)
+      err = xml.elements['Error']
+      raise Error, err.elements['Message'].text if err
+    end
+
+    # Creates a URL from the Hash +params+.  Automatically adds the appid and
+    # sets the output type to 'xml'.
+    def make_url(params)
+      params[:appid] = @appid
+      params[:output] = 'xml'
+
+      super params
+    end
+
+  end
+
+  
+end

data/lib/graticule/location.rb

@@ -0,0 +1,28 @@
+
+module Graticule
+  class Location
+    attr_accessor :latitude, :longitude, :street, :city, :state, :zip, :country, :precision, :warning
+    
+    def initialize(attrs = {})
+      attrs.each do |key,value|
+        instance_variable_set "@#{key}", value
+      end
+    end
+    
+    # Returns an Array with latitude and longitude.
+    def coordinates
+      [latitude, longitude]
+    end
+    
+    def ==(object)
+      super(object) || [:latitude, :longitude, :street, :city, :state, :zip, :country, :precision].all? do |m|
+        object.respond_to?(m) && self.send(m) == object.send(m)
+      end
+    end
+    
+    def distance_to(destination, units = :miles, formula = :haversine)
+      "Graticule::Distance::#{formula.to_s.titleize}".constantize.distance(self, destination)
+    end
+    
+  end
+end

data/lib/graticule/version.rb

@@ -0,0 +1,3 @@
+module Graticule
+  Version = '0.1.1'
+end

data/test/fixtures/responses/geocoder_us/success.xml

@@ -0,0 +1,10 @@
+<?xml version="1.0"?>
+<rdf:RDF xmlns:dc="http://purl.org/dc/elements/1.1/"
+    xmlns:geo="http://www.w3.org/2003/01/geo/wgs84_pos#"
+    xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#">
+  <geo:Point rdf:nodeID="aid86937982">
+    <dc:description>1600 Pennsylvania Ave NW, Washington DC 20502</dc:description>
+    <geo:long>-77.037684</geo:long>
+    <geo:lat>38.898748</geo:lat>
+  </geo:Point>
+</rdf:RDF>

data/test/fixtures/responses/geocoder_us/unknown.xml

@@ -0,0 +1 @@
+couldn't find this address! sorry

data/test/fixtures/responses/google/badkey.xml

@@ -0,0 +1,10 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<kml xmlns="http://earth.google.com/kml/2.0">
+  <Response>
+    <name>1600 Amphitheater Pkwy, Mountain View, CA</name>
+    <Status>
+      <code>610</code>
+      <request>geocode</request>
+    </Status>
+  </Response>
+</kml>

data/test/fixtures/responses/google/limit.xml

@@ -0,0 +1,10 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<kml xmlns="http://earth.google.com/kml/2.0">
+  <Response>
+    <name>1600 Amphitheater Pkwy, Mountain View, CA</name>
+    <Status>
+      <code>620</code>
+      <request>geocode</request>
+    </Status>
+  </Response>
+</kml>

data/test/fixtures/responses/google/missing_address.xml

@@ -0,0 +1,10 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<kml xmlns="http://earth.google.com/kml/2.0">
+  <Response>
+    <name>1600</name>
+    <Status>
+      <code>601</code>
+      <request>geocode</request>
+    </Status>
+  </Response>
+</kml>

data/test/fixtures/responses/google/server_error.xml

@@ -0,0 +1,10 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<kml xmlns="http://earth.google.com/kml/2.0">
+  <Response>
+    <name>1600 Amphitheater Pkwy, Mountain View, CA</name>
+    <Status>
+      <code>500</code>
+      <request>geocode</request>
+    </Status>
+  </Response>
+</kml>

data/test/fixtures/responses/google/success.xml

@@ -0,0 +1,37 @@
+<kml>
+  <Response>
+    <name>1600 amphitheatre mtn view ca</name>
+    <Status>
+      <code>200</code>
+      <request>geocode</request>
+    </Status>
+    <Placemark>
+      <address> 
+        1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA
+      </address>
+      <AddressDetails Accuracy="8">
+        <Country>
+          <CountryNameCode>US</CountryNameCode>
+ 	  <AdministrativeArea>
+            <AdministrativeAreaName>CA</AdministrativeAreaName>
+           <SubAdministrativeArea>
+             <SubAdministrativeAreaName>Santa Clara</SubAdministrativeAreaName>
+             <Locality>
+               <LocalityName>Mountain View</LocalityName>
+    	       <Thoroughfare>
+                 <ThoroughfareName>1600 Amphitheatre Pkwy</ThoroughfareName>
+               </Thoroughfare>
+               <PostalCode>
+                 <PostalCodeNumber>94043</PostalCodeNumber>
+               </PostalCode>
+             </Locality>
+           </SubAdministrativeArea>
+         </AdministrativeArea>
+       </Country>
+     </AddressDetails>
+     <Point>
+       <coordinates>-122.083739,37.423021,0</coordinates>
+     </Point>
+   </Placemark>
+  </Response>
+</kml>

data/test/fixtures/responses/google/unavailable.xml

@@ -0,0 +1,10 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<kml xmlns="http://earth.google.com/kml/2.0">
+  <Response>
+    <name>42-44 Hanway Street, London</name>
+    <Status>
+      <code>603</code>
+      <request>geocode</request>
+    </Status>
+  </Response>
+</kml>