cloudmade 0.1.2

data/lib/cloudmade/examples.rb

@@ -0,0 +1,23 @@
+require 'cloudmade'
+include CloudMade
+
+cm = CloudMade::Client.from_parameters('BC9A493B41014CAABB98F0471D759707')
+
+puts 'Testing CloudMade Client'
+puts "Geocoding"
+puts "---------"
+puts "Find"
+puts cm.geocoding.find('Potsdamer Platz, Berlin, Germany')
+puts "Find closest"
+puts cm.geocoding.find_closest('pub', 50.9425, 6.9575)
+
+puts "Routing\n-------\n"
+puts cm.routing.route(
+ CloudMade::Point.new(47.25976, 9.58423),
+ CloudMade::Point.new(47.66117, 9.99882))
+ 
+puts "Tiles\n-----\n"
+tile = cm.tiles.get_tile(50.39947, 30.6479, 15)
+file = File.new('my_tile.png', 'w')
+file.write(tile)
+file.close

data/lib/cloudmade/exceptions.rb

@@ -0,0 +1,35 @@
+#
+# Copyright 2009 CloudMade.
+#
+# Licensed under the GNU Lesser General Public License, Version 3.0;
+# You may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.gnu.org/licenses/lgpl-3.0.txt
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+
+#Raised when API key is not specified in Connection constructor
+class APIKeyMissingError < Exception
+end
+
+#Raised when object was not found by geocoding service
+class ObjectNotFound < Exception
+end
+
+#Raised when HTTP code other than 200 returned
+class HTTPError < Exception
+end
+
+#Raised when specified route couldn't be found
+class RouteNotFound < Exception
+end
+
+#Raised when geometry is malformed
+class GeometryParseError < Exception
+end

data/lib/cloudmade/geocoding.rb

@@ -0,0 +1,144 @@
+#
+# Copyright 2009 CloudMade.
+#
+# Licensed under the GNU Lesser General Public License, Version 3.0;
+# You may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.gnu.org/licenses/lgpl-3.0.txt
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+
+module CloudMade
+  require 'cgi'
+
+  # Class that is responsible for geocoding services of Cloudmade
+  class GeocodingService < Service
+
+    # Find objects that match given query. Returns GeoResults object.
+    #
+    # * +query+ Query by which objects should be searched
+    # * +options+ Additional options, contains
+    # results: How many results should be returned.
+    # skip: Number of results to skip from beginning.
+    # bbox: Bounding box in which objects should be searched.
+    # bbox_only: If set to False, results will be searched in the whole world if there are no results for a given bbox.
+    # return_geometry: If specified, adds geometry in returned results. Defaults to true.
+    #
+    def find(query, options = {})
+      options['results'] = 10 unless options.has_key? 'results'
+      options['skip'] = 0 unless options.has_key? 'skip'
+      options['bbox_only'] = true unless options.has_key? 'bbox_only'
+      options['return_geometry'] = true unless options.has_key? 'return_geometry'
+      request = "/find/#{CGI.escape(query)}.js?#{Service.to_url_params(options)}"
+        
+      GeoResults.new(JSON.parse(connect request))
+    end
+
+    # Find closest object to a given point.
+    # For a list of available object types, see:
+    # http://www.cloudmade.com/developers/docs/geocoding-http-api/object_types
+    # Returns GeoResult object, that contain found objects.
+    # Raise ObjectNotFound: Raised when no object could be found in radius of 50 km from point.
+    #
+    # * +object_type+ Type of object, that should be searched.
+    # * +point+ Closest object to this point will be searched.
+    # * +options+ are
+    # * +return_geometry+ If specified, adds geometry in returned results. Defaults to true
+
+    # TODO: Modify lat, lon parameters to point
+    def find_closest(object_type, lat, lon, options = {})
+      lat_lon = "#{CGI.escape(lat.to_s + '+' + lon.to_s)}"
+      request = "/closest/#{object_type}/#{lat_lon}.js?#{Service.to_url_params(options)}"
+      geo_results = GeoResults.new(JSON.parse(connect request))
+      raise ObjectNotFound.new if (geo_results.results == nil or geo_results.results.size == 0)
+      return geo_results.results[0]
+    end
+
+    # :nodoc:
+    def url_template
+      return "http://#{@subdomain}.#{@connection.url}/#{@connection.api_key}/geocoding"
+    end
+  end
+
+  # Location of the object in geographical terms
+  class Location
+    # road: Road on which object is situated
+    attr_accessor :road
+    # city: City, where the object is situated
+    attr_accessor :city
+    # county: County, where the object is situated
+    attr_accessor :county
+    # country: Country in which the object is situated
+    attr_accessor :country
+    # postcode: Postcode, which corresponds to location of the object
+    attr_accessor :postcode
+
+    def initialize(data)
+      self.road = data['road']
+      self.city = data['city']
+      self.county = data['county']
+      self.country = data['country']
+      self.postcode = data['postcode']
+    end
+  end
+
+  # Parsed results of geocoding request
+  class GeoResults
+    # Founded results
+    attr_accessor :found
+    # List of found GeoResult objects
+    attr_accessor :results
+    # Bounds of result set
+    attr_accessor :bounds
+
+    def initialize(data)
+      self.found = Integer(data['found']) if data.has_key? 'found'
+      if (data['features'] != nil) then
+        self.results = data['features'].map { |feature_data| CloudMade::GeoResult.new(feature_data) }
+      end
+      self.bounds = CloudMade::BBox.from_coordinates(data['bounds']) if data.has_key? 'bounds'
+    end
+
+    def to_s
+      results.join(',') if results != nil
+    end
+  end
+
+  class GeoResult
+    # Id of the object
+    attr_accessor :id
+    # Geometry of the object
+    attr_accessor :geometry
+    # Centroid of the object
+    attr_accessor :centroid
+    # Bounds of result set
+    attr_accessor :bounds
+    # Properties of the object
+    attr_accessor :properties
+    # Location of the object
+    attr_accessor :location
+
+    def initialize(data)
+      self.id = data['id']
+      self.geometry = CloudMade::Geometry.parse(data['geometry'])
+      self.centroid = CloudMade::Geometry.parse(data['centroid'])
+      self.bounds = CloudMade::BBox.from_coordinates(data['bounds']) if data.has_key? 'bounds'
+      self.properties = data['properties']
+      if data.has_key? 'location'
+        self.location = Location.new(data['location'])
+      else
+        self.location = nil
+      end
+    end
+
+    def to_s
+      self.geometry.to_s
+    end
+  end
+end

data/lib/cloudmade/geometry.rb

@@ -0,0 +1,139 @@
+#
+# Copyright 2009 CloudMade.
+#
+# Licensed under the GNU Lesser General Public License, Version 3.0;
+# You may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.gnu.org/licenses/lgpl-3.0.txt
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+
+module CloudMade
+  class Geometry
+
+    class << self
+      def parse(data)
+        return nil if data == nil
+        case data['type'].downcase
+        when 'point' then return Point.new(data['coordinates'])
+        when 'line' then return Line.new(data['coordinates'])
+        when 'multilinestring' then return MultiLine.new(data['coordinates'])
+        when 'polygon' then return Polygon.new(data['coordinates'])
+        when 'multipolygon' then return MultiPolygon.new(data['coordinates'])
+        end
+      end
+    end
+  end
+
+  class Point < Geometry
+    attr_accessor :lat
+    attr_accessor :lon
+
+    # Posible initializers are
+    # Point.new(1, -1)
+    # Point.new([1, -1])
+    def initialize(*args)
+      if args.size == 1
+        @lat = args[0][0]
+        @lon = args[0][1]
+      elsif args.size == 2
+        @lat = args[0]
+        @lon = args[1]
+      end
+    end
+
+    def ==(point)
+      return (point.lat == @lat and point.lon == @lon)
+    end
+
+    def to_s
+      "Point(#{@lat},#{@lon})"
+    end
+
+    def to_latlon
+      "#{@lat},#{@lon}"
+    end
+  end
+
+  class Line < Geometry
+    attr_accessor :points
+
+    def initialize(coords)
+      @points = coords.map { |latlng| Point.new(latlng) }
+    end
+
+    def to_s
+      "Line(#{@points.join(',')})"
+    end
+  end
+
+
+  class MultiLine < Geometry
+    attr_accessor :lines
+
+    def initialize(coords)
+      @lines = coords.map { |line_coords| Line.new(line_coords) }
+    end
+
+    def to_s
+      "MultiLine(#{@lines.join(',')})"
+    end
+  end
+
+  class Polygon < Geometry
+    attr_accessor :border_line
+    attr_accessor :holes
+
+    def initialize(coords)
+      @border_line = Line.new(coords[0])
+      @holes = coords.slice(1, coords.length).map { |line_coords| Line.new(line_coords) }
+    end
+
+    def to_s
+      "Polygon(#{@border_line} - (#{@holes.join(',')}))"
+    end
+  end
+
+  class MultiPolygon < Geometry
+    attr_accessor :polygons
+
+    def initialize(coords)
+      @polygons = coords.map { |poly_coords| Polygon.new(poly_coords) }
+    end
+
+    def to_s
+      "MultiPolygon(#{@polygons.join(',')})"
+    end
+  end
+
+  class BBox < Geometry
+    attr_accessor :points
+    
+    def initialize(points)
+      self.points = points
+    end
+
+    class << self
+      def from_points(points)
+        return BBox.new(points)
+      end
+
+      def from_coordinates(coords)
+        point1 = Point.new(coords[0][0], coords[0][1])
+        point2 = Point.new(coords[1][0], coords[1][1])
+        return BBox.new([point1, point2])
+      end
+    end
+
+    def ==(bbox)
+      return (bbox.points[0] == self.points[0] and bbox.points[1] = self.points[1] or
+          bbox.points[0] == self.points[1] and bbox.points[1] = self.points[0])
+    end
+  end
+end

data/lib/cloudmade/locations.rb

@@ -0,0 +1,20 @@
+#
+# Copyright 2009 CloudMade.
+#
+# Licensed under the GNU Lesser General Public License, Version 3.0;
+# You may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.gnu.org/licenses/lgpl-3.0.txt
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+
+module CloudMade
+  class LocationsService < Service
+  end
+end

data/lib/cloudmade/routing.rb

@@ -0,0 +1,145 @@
+#
+# Copyright 2009 CloudMade.
+#
+# Licensed under the GNU Lesser General Public License, Version 3.0;
+# You may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.gnu.org/licenses/lgpl-3.0.txt
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+
+require 'cgi'
+require 'json'
+
+module CloudMade
+
+  #Class corresponding for CloudMade's routing service
+  class RoutingService < Service
+
+    ROUTE_TYPES = ['car', 'foot', 'bicycle']
+    OUTPUT_FORMATS = ['js', 'json', 'gpx']
+    STATUS_OK = 0
+    STATUS_ERROR = 1
+    EARTHS_DIRECTIONS = ["N", "NE", "E", "SE", "S", "SW", "W", "NW"]
+    TURN_TYPE = ["C", "TL", "TSLL", "TSHL", "TR", "TSLR", "TSHR", "U"]
+
+    # Build route. Returns route that was found, instance of CloudMade::Route
+    # * +start_point+ Starting point
+    # * +end_point+ Ending point
+    # * +route_type+ Type of route, e.g. 'car', 'foot', etc.
+    # * +transit_points+ List of points route must visit before
+    #   reaching end. Points are visited in the same order they are
+    #   specified in the sequence.
+    # * +route_type_modifier+ Modifier of the route type
+    # * +lang+ Language code in conformance to `ISO 3166-1 alpha-2` standard
+    # * +units+ Measure units for distance calculation
+    def route(start_point, end_point, transit_points = nil, route_type = 'car', lang = 'en', route_type_modifier = nil)
+      transit_points = ",[#{transit_points.map {|point| point.to_latlon}.join(',')}]" if not transit_points == nil
+      route_type_modifier = "/#{route_type_modifier}" if not route_type_modifier == nil
+      url = "/#{start_point.to_latlon}#{transit_points},#{end_point.to_latlon}/#{route_type}#{route_type_modifier}.js?lang=#{lang}&units=km"
+      return Route.new(JSON.parse(connect url))
+    end
+
+    #:nodoc:
+    def url_template
+      return "http://#{@subdomain}.#{@connection.url}/#{@connection.api_key}/api/0.3"
+    end
+  end
+
+
+  # Statistics of the route
+  class RouteSummary
+    attr_accessor :total_distance
+    attr_accessor :total_time
+    attr_accessor :start_point
+    attr_accessor :end_point
+    attr_accessor :transit_points
+
+    def initialize(summary)
+        self.total_distance = Float(summary['total_distance'])
+        self.total_time = Float(summary['total_time'])
+        self.start_point = summary['start_point']
+        self.end_point = summary['end_point']
+        self.transit_points = summary['transit_points']
+    end
+  end
+
+  # Wrapper around raw data being returned by routing service
+  class Route
+
+    # List of route instructions
+    attr_accessor :instructions
+    # Statistical info about the route
+    attr_accessor :summary
+    # Geometry of route
+    attr_accessor :geometry
+    #Version of routing HTTP API
+    attr_accessor :version    
+    # Status of response
+    attr_accessor :status
+    attr_accessor :status_message
+
+    STATUS_OK = 0
+    STATUS_ERROR = 1
+
+    def initialize(data)
+      begin
+        self.status = data['status'].to_i
+        self.instructions = data['route_instructions'].map { |instruction_data| RouteInstruction.new(instruction_data) }
+        self.summary = RouteSummary.new(data['route_summary'])
+        self.geometry = Line.new(data['route_geometry'])
+        self.version = data['version']
+        self.status_message = data['status_message']
+      rescue
+        raise RouteNotFound
+      end
+    end
+
+    def to_s
+      self.instructions.to_s
+    end
+  end
+
+  # Instructions on route passing
+  class RouteInstruction
+
+    # Text instruction
+    attr_reader :instruction
+    # Length of the segment in meters
+    attr_reader :length
+    # Index of the first point of the segment
+    attr_reader :position
+    # Estimated time required to travel the segment in seconds
+    attr_reader :time
+    # Length of the segments in specified units
+    attr_reader :length_caption
+    # Earth direction
+    attr_reader :earth_direction
+    # North-based azimuth
+    attr_reader :azimuth
+    # Code of the turn type
+    attr_reader :turn_type
+    # Angle in degress of the turn between two segments
+    attr_reader :turn_angle
+
+    def initialize(data)
+      @instruction = data[0]
+      @length = Float(data[1])
+      @position = Integer(data[2])
+      @time = Integer(data[3])
+      @length_caption = data[4]
+      @earth_direction = data[5]
+      @azimuth = Float(data[6])
+      if data.length == 9
+        @turn_type = data[7]
+        @turn_angle = data[8]
+      end
+    end
+  end
+end