sg-ruby 0.1.0

data/.document

@@ -0,0 +1,5 @@
+README.rdoc
+lib/**/*.rb
+bin/*
+features/**/*.feature
+LICENSE

data/.gitignore

@@ -0,0 +1,21 @@
+## MAC OS
+.DS_Store
+
+## TEXTMATE
+*.tmproj
+tmtags
+
+## EMACS
+*~
+\#*
+.\#*
+
+## VIM
+*.swp
+
+## PROJECT::GENERAL
+coverage
+rdoc
+pkg
+
+## PROJECT::SPECIFIC

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2009 Dan Dofter
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.rdoc

@@ -0,0 +1,120 @@
+= sg-ruby
+
+A SimpleGeo Ruby client.
+
+For the specific documentation on APIs (and the full list of parameters) see:
+
+http://help.simplegeo.com/faqs/api-documentation/endpoints
+
+== Examples
+
+Start by requiring SimpleGeo and setting your authentication credentials:
+
+  require 'simplegeo'
+  SimpleGeo::Client.set_credentials('token', 'secret')
+  
+=== Getting a record
+
+  record = SimpleGeo::Client.get_record('com.simplegeo.global.geonames', '5373629')
+
+=== Getting multiple records
+
+  records = SimpleGeo::Client.get_records('com.simplegeo.global.geonames', ['1234', '5678'])
+
+=== Adding a record
+
+  record = SimpleGeo::Record.new({
+    :id => '1234',
+    :created => 1269832510,
+    :lat => 37.759650000000001,
+    :lon => -122.42608,
+    :layer => 'com.example.testlayer',
+    :properties => {
+      :test_property => 'foobar'
+    }
+  })
+  SimpleGeo::Client.add_record(record)
+
+=== Updating a record
+  
+  record = SimpleGeo::Client.get_record('com.example.testlayer', '1234')
+  record.lat = 40.714269
+  record.lon = -74.005973
+  SimpleGeo::Client.add_record(record)
+
+=== Adding / updating multiple records
+
+  records = [
+    SimpleGeo::Record.new({
+      :id => '1234',
+      :created => 1269832510,
+      :lat => 37.759650000000001,
+      :lon => -122.42608,
+      :layer => 'com.example.testlayer',
+      :properties => {
+        :test_property => 'foobar'
+      }
+    }),
+    SimpleGeo::Record.new({
+      :id => '5678',
+      :created => 1269832510,
+      :lat => 37.755470000000003,
+      :lon => -122.420646,
+      :layer => 'com.example.testlayer',
+      :properties => {
+        :mad_prop => 'baz'
+      }
+    })
+  ]
+  SimpleGeo::Client.add_records('com.example.testlayer', records)
+
+=== Deleting a record
+
+  SimpleGeo::Client.delete_record('1234')
+
+=== Getting a record's history
+
+  history = SimpleGeo::Client.get_history('com.example.testlayer', '1234')
+
+=== Getting nearby records
+
+See http://help.simplegeo.com/faqs/api-documentation/endpoints for other optional params
+
+  # by lat, lon
+  records = SimpleGeo::Client.get_nearby_records('com.example.testlayer', 
+    :lat => 37.759650000000001,
+    :lon => -122.42608)
+    
+  # by geohash
+  records = SimpleGeo::Client.get_nearby_records('com.example.testlayer', 
+    :geohash => '9q8yy1ujcsfm')
+
+=== Getting a nearby address for a lat and lon
+
+  nearby_address = SimpleGeo::Client.get_nearby_address(37.759650000000001, -122.42608)
+  
+=== Getting SpotRank density information
+
+  # by day
+  density_info = SimpleGeo::Client.get_density(37.75965, -122.42608, 'sat')
+  
+  # by hour
+  density_info = SimpleGeo::Client.get_density(37.75965, -122.42608, 'sat', '16' )
+
+=== Other APIs
+
+For more examples see: spec/client_spec.rb 
+
+== Note on Patches/Pull Requests
+ 
+* Fork the project.
+* Make your feature addition or bug fix.
+* Add tests for it. This is important so I don't break it in a
+  future version unintentionally.
+* Commit, do not mess with rakefile, version, or history.
+  (if you want to have your own version, that is fine but bump version in a commit by itself I can ignore when I pull)
+* Send me a pull request. Bonus points for topic branches.
+
+== Copyright
+
+Copyright (c) 2010 Dan Dofter. See LICENSE for details.

data/Rakefile

@@ -0,0 +1,50 @@
+require 'rubygems'
+require 'rake'
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gem|
+    gem.name = "sg-ruby"
+    gem.summary = %Q{A SimpleGeo Ruby Client}
+    gem.email = "dan@dofter.com"
+    gem.homepage = "http://github.com/archfear/sg-ruby"
+    gem.authors = ["Dan Dofter"]
+    
+    gem.add_dependency("oauth", ">= 0.4.0")
+    gem.add_dependency("json_pure")
+
+    gem.add_development_dependency "rspec", ">= 1.2.0"
+    gem.add_development_dependency("fakeweb", ">= 1.2.0")
+  end
+  Jeweler::GemcutterTasks.new
+rescue LoadError
+  puts "Jeweler (or a dependency) not available. Install it with: gem install jeweler"
+end
+
+require 'spec/rake/spectask'
+Spec::Rake::SpecTask.new(:spec) do |spec|
+  spec.libs << 'lib' << 'spec'
+  spec.spec_files = FileList['spec/**/*_spec.rb']
+end
+
+Spec::Rake::SpecTask.new(:rcov) do |spec|
+  spec.libs << 'lib' << 'spec'
+  spec.pattern = 'spec/**/*_spec.rb'
+  spec.rcov = true
+  spec.rcov_opts << "--sort coverage"
+  spec.rcov_opts << "--exclude gems,spec"
+end
+
+task :spec => :check_dependencies
+
+task :default => :spec
+
+require 'rake/rdoctask'
+Rake::RDocTask.new do |rdoc|
+  version = File.exist?('VERSION') ? File.read('VERSION') : ""
+
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = "sg-ruby #{version}"
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end

data/VERSION

@@ -0,0 +1 @@
+0.1.0

data/lib/simple_geo.rb

@@ -0,0 +1,23 @@
+require 'uri'
+require 'json'
+require 'oauth'
+
+require 'simple_geo/hash_utils'
+require 'simple_geo/connection'
+require 'simple_geo/endpoint'
+require 'simple_geo/client'
+require 'simple_geo/record'
+
+module SimpleGeo
+  API_VERSION = '0.1'.freeze
+  REALM = "http://api.simplegeo.com"
+  VERSION = File.read(File.join(File.dirname(__FILE__), '..', 'VERSION'))
+
+  class SimpleGeoError < StandardError; end
+  class Unauthorized < SimpleGeoError; end
+  class NotFound < SimpleGeoError; end
+  class ServerError < SimpleGeoError; end
+  class Unavailable < SimpleGeoError; end
+  class DecodeError < SimpleGeoError; end
+  class NoConnectionEstablished < SimpleGeoError; end
+end

data/lib/simple_geo/client.rb

@@ -0,0 +1,166 @@
+module SimpleGeo
+
+  class Client
+
+    @@connection = nil
+    @@debug = false
+
+    class << self
+
+      def set_credentials(token, secret)
+        @@connection = Connection.new(token, secret)
+        @@connection.debug = @@debug
+      end
+
+      def debug=(debug_flag)
+        @@debug = debug_flag
+        @@connection.debug = @@debug  if @@connection
+      end
+
+      def debug
+        @@debug
+      end
+
+      def add_record(record)
+        raise SimpleGeoError, "Record has no layer"  if record.layer.nil?
+        put Endpoint.record(record.layer, record.id), record
+      end
+
+      def delete_record(layer, id)
+        delete Endpoint.record(layer, id)
+      end
+
+      def get_record(layer, id)
+        record_hash = get Endpoint.record(layer, id)
+        record = Record.parse_geojson_hash(record_hash)
+        record.layer = layer
+        record
+      end
+
+      def add_records(layer, records)
+        features = {
+          :type => 'FeatureCollection',
+          :features => records.collect { |record| record.to_hash }
+        }
+        post Endpoint.add_records(layer), features
+      end
+
+      # This request currently generates a 500 error if an unknown id is passed in.
+      def get_records(layer, ids)
+        features_hash = get Endpoint.records(layer, ids)
+        records = []
+        features_hash['features'].each do |feature_hash|
+          record = Record.parse_geojson_hash(feature_hash)
+          record.layer = layer
+          records << record
+        end
+        records
+      end
+
+      def get_history(layer, id)
+        history_geojson = get Endpoint.history(layer, id)
+        history = []
+        history_geojson['geometries'].each do |point|
+          history << {
+            :created => Time.at(point['created']),
+            :lat => point['coordinates'][1],
+            :lon => point['coordinates'][0]
+          }
+        end
+        history
+      end
+
+      def get_nearby_records(layer, options)
+        if options[:geohash]
+          endpoint = Endpoint.nearby_geohash(layer, options.delete(:geohash))
+        elsif options[:lat] && options[:lon]
+          endpoint = Endpoint.nearby_coordinates(layer,
+            options.delete(:lat), options.delete(:lon))
+        else
+          raise SimpleGeoError, "Either geohash or lat and lon is required"
+        end
+
+        options = nil  if options.empty?
+        features_hash = get(endpoint, options)
+        nearby_records = {
+          :next_cursor => features_hash['next_cursor'],
+          :records => []
+        }
+        features_hash['features'].each do |feature_hash|
+          record = Record.parse_geojson_hash(feature_hash)
+          record.layer = layer
+          record_info = {
+            :distance => feature_hash['distance'],
+            :record => record
+          }
+          nearby_records[:records] << record_info
+        end
+        nearby_records
+      end
+
+      def get_nearby_address(lat, lon)
+        geojson_hash = get Endpoint.nearby_address(lat, lon)
+        HashUtils.symbolize_keys geojson_hash['properties']
+      end
+
+      def get_layer_information(layer)
+        layer_info = get Endpoint.layer(layer)
+        layer_info.delete('selfLink')
+        HashUtils.symbolize_keys(layer_info)
+      end
+
+      def get_density(lat, lon, day, hour=nil)
+        geojson_hash = get Endpoint.density(lat, lon, day, hour)
+        geojson_hash = HashUtils.recursively_symbolize_keys(geojson_hash)
+        if hour.nil?
+          density_info = []
+          geojson_hash[:features].each do |hour_geojson_hash|
+            density_info << hour_geojson_hash[:properties].merge(
+              {:geometry => hour_geojson_hash[:geometry]})
+          end
+          density_info
+        else
+          geojson_hash[:properties].merge({:geometry => geojson_hash[:geometry]})
+        end
+      end
+
+      def get_overlaps(south, west, north, east, options=nil)
+        info = get Endpoint.overlaps(south, west, north, east), options
+        HashUtils.recursively_symbolize_keys(info)
+      end
+
+      # this API call seems to always return a 404
+      def get_boundary(id)
+        info = get Endpoint.boundary(id)
+        HashUtils.recursively_symbolize_keys(info)
+      end
+
+      def get_contains(lat, lon)
+        info = get Endpoint.contains(lat, lon)
+        HashUtils.recursively_symbolize_keys(info)
+      end
+
+      def get(endpoint, data=nil)
+        raise NoConnectionEstablished  if @@connection.nil?
+        @@connection.get endpoint, data
+      end
+
+      def delete(endpoint, data=nil)
+        raise NoConnectionEstablished  if @@connection.nil?
+        @@connection.delete endpoint, data
+      end
+
+      def post(endpoint, data=nil)
+        raise NoConnectionEstablished  if @@connection.nil?
+        @@connection.post endpoint, data
+      end
+
+      def put(endpoint, data=nil)
+        raise NoConnectionEstablished  if @@connection.nil?
+        @@connection.put endpoint, data
+      end
+    end
+
+  end
+
+end

data/lib/simple_geo/connection.rb

@@ -0,0 +1,109 @@
+module SimpleGeo
+  class Connection
+
+    attr_accessor :debug
+
+    def initialize(token, secret)
+      consumer = OAuth::Consumer.new(token, secret, :site => REALM)
+      @access_token = OAuth::AccessToken.new(consumer)
+      debug = false
+    end
+
+    def get(endpoint, data=nil)
+      request :get, endpoint, data
+    end
+
+    def delete(endpoint, data=nil)
+      request :delete, endpoint, data
+    end
+
+    def post(endpoint, data=nil)
+      request :post, endpoint, data
+    end
+
+    def put(endpoint, data=nil)
+      request :put, endpoint, data
+    end
+
+    private
+
+      def request(method, endpoint, data)
+        headers = {'User-Agent' => "SimpleGeo Ruby Client v#{VERSION}"}
+
+        if [:get, :delete].include?(method) && !data.nil?
+          endpoint = endpoint + '?' + build_query(data)
+        end
+
+        if debug
+          puts "request: #{method.to_s.upcase} #{endpoint}"
+          puts "headers:"
+          headers.each do |key, value|
+            puts "#{key}=#{value}"
+          end
+          if [:post, :put].include?(method) && !data.nil?
+            puts "data:"
+            puts data.to_json
+          end
+        end
+
+        case method
+          when :get, :delete
+            response = @access_token.request(method, endpoint, headers)
+          when :post, :put
+            data = data.to_json  unless data.nil?
+            response = @access_token.request(method, endpoint, data, headers)
+        end
+
+        if debug
+          puts "\nresponse: #{response.code}"
+          puts "headers:"
+          response.header.each do |key, value|
+            puts "#{key}=#{value}"
+          end
+          puts "body:"
+          puts response.body
+        end
+
+        raise_errors(response)
+
+        if response.body.empty?
+          content = nil
+        else
+          begin
+            content = JSON.parse(response.body)
+          rescue JSON::ParserError
+            raise DecodeError, "content: <#{response.body}>"
+          end
+        end
+
+        content
+      end
+
+      def build_query(data)
+        data.map do |key, value|
+          [key.to_s, URI.escape(value.to_s)].join('=')
+        end.join('&')
+      end
+
+      def raise_errors(response)
+        response_description = "(#{response.code}): #{response.message}"
+        response_description += " - #{response.body}"  unless response.body.empty?
+
+        case response.code.to_i
+          when 401
+            raise Unauthorized
+          when 404
+            raise NotFound
+          when 500
+            raise ServerError, "SimpleGeo had an internal error. Please let them know. #{response_description}"
+          when 502..503
+            raise Unavailable, response_description
+          else
+            unless response.is_a? Net::HTTPSuccess
+              raise SimpleGeoError, response_description
+            end
+        end
+      end
+
+  end
+end