simplegeo 0.0.3 → 0.1.0

data/.document

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

data/.gitignore

@@ -1,8 +1,21 @@
-*.swp
-*.swo
-*.swn
-.tmp_*
-.project
-._*
+## MAC OS
 .DS_Store
-pkg/*
+
+## TEXTMATE
+*.tmproj
+tmtags
+
+## EMACS
+*~
+\#*
+.\#*
+
+## VIM
+*.swp
+
+## PROJECT::GENERAL
+coverage
+rdoc
+pkg
+
+## PROJECT::SPECIFIC

data/LICENSE

@@ -1,4 +1,4 @@
-Copyright (c) 2010 Scott Windsor
+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

data/README.rdoc

@@ -1,11 +1,116 @@
-= simplegeo-ruby
+= sg-ruby
 
-This is a Ruby client for the Simplegeo API (Version 0.1)
+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
 
+== Installation
+
+Open the Terminal or other UNIX shell and type:
+
+  sudo gem install sg-ruby
+
+== Examples
+
+Start by requiring SimpleGeo and setting your authentication credentials:
+
+  require 'simple_geo'
+  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 => Time.now,
+    :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 => Time.now,
+      :lat => 37.759650000000001,
+      :lon => -122.42608,
+      :layer => 'com.example.testlayer',
+      :properties => {
+        :test_property => 'foobar'
+      }
+    }),
+    SimpleGeo::Record.new({
+      :id => '5678',
+      :created => Time.now,
+      :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.
@@ -18,4 +123,4 @@ http://help.simplegeo.com/faqs/api-documentation/endpoints
 
 == Copyright
 
-Copyright (c) 2010 Scott Windsor. See LICENSE for details.
+Copyright (c) 2010 Dan Dofter. See LICENSE for details.

data/Rakefile

@@ -5,16 +5,16 @@ begin
   require 'jeweler'
   Jeweler::Tasks.new do |gem|
     gem.name = "simplegeo"
-    gem.summary = %Q{a simplegeo client written in ruby}
-    gem.description = %Q{a simplegeo client written in ruby.  see http://help.simplegeo.com/faqs/api-documentation/endpoints for more info.}
-    gem.email = "swindsor@gmail.com"
-    gem.homepage = "http://github.com/sentientmonkey/simplegeo-ruby"
-    gem.authors = ["Scott Windsor"]
-    gem.add_development_dependency "rspec", ">= 1.3.0"
-    gem.add_development_dependency "hanna", ">= 0.1.12"
-    gem.add_dependency('oauth', '>= 0.3.6')
-    gem.add_dependency('crack', '>= 0.1.7')
-    gem.add_dependency('json', '>= 1.2.2')
+    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
@@ -31,22 +31,20 @@ 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'
-gem 'hanna'
-require 'hanna/rdoctask'
-
+require 'rake/rdoctask'
 Rake::RDocTask.new do |rdoc|
   version = File.exist?('VERSION') ? File.read('VERSION') : ""
 
   rdoc.rdoc_dir = 'rdoc'
-  rdoc.title = "simplegeo #{version}"
+  rdoc.title = "simplegeo-ruby #{version}"
   rdoc.rdoc_files.include('README*')
   rdoc.rdoc_files.include('lib/**/*.rb')
-
 end

data/VERSION

@@ -1 +1 @@
-0.0.3
+0.1.0

data/lib/simple_geo/client.rb

@@ -0,0 +1,171 @@
+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_locate(ip)
+        info = get Endpoint.locate(ip)
+        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

data/lib/simple_geo/endpoint.rb

@@ -0,0 +1,71 @@
+module SimpleGeo
+
+  class Endpoint
+
+    class << self
+      def record(layer, id)
+        endpoint_url "records/#{layer}/#{id}.json"
+      end
+
+      def records(layer, ids)
+         ids = ids.join(',')  if ids.is_a? Array
+         endpoint_url "records/#{layer}/#{ids}.json"
+      end
+
+      def add_records(layer)
+        endpoint_url "records/#{layer}.json"
+      end
+
+      def history(layer, id)
+        endpoint_url "records/#{layer}/#{id}/history.json"
+      end
+
+      def nearby_geohash(layer, geohash)
+        endpoint_url "records/#{layer}/nearby/#{geohash}.json"
+      end
+
+      def nearby_coordinates(layer, lat, lon)
+        endpoint_url "records/#{layer}/nearby/#{lat},#{lon}.json"
+      end
+
+      def nearby_address(lat, lon)
+        endpoint_url "nearby/address/#{lat},#{lon}.json"
+      end
+
+      def density(lat, lon, day, hour=nil)
+        if hour.nil?
+          path = "density/#{day}/#{lat},#{lon}.json"
+        else
+          path = "density/#{day}/#{hour}/#{lat},#{lon}.json"
+        end
+        endpoint_url path
+      end
+
+      def layer(layer)
+        endpoint_url "layer/#{layer}.json"
+      end
+
+      def contains(lat, lon)
+        endpoint_url "contains/#{lat},#{lon}.json"
+      end
+
+      def overlaps(south, west, north, east)
+        endpoint_url "overlaps/#{south},#{west},#{north},#{east}.json"
+      end
+
+      def boundary(id)
+        endpoint_url "boundary/#{id}.json"
+      end
+
+      def locate(ip)
+        endpoint_url "locate/#{ip}.json"
+      end
+
+      def endpoint_url(path)
+        [REALM, API_VERSION, path].join('/')
+      end
+    end
+
+  end
+
+end

data/lib/simple_geo/hash_utils.rb

@@ -0,0 +1,24 @@
+module SimpleGeo
+  class HashUtils
+    def self.symbolize_keys(hash)
+      hash.inject({}) do |options, (key, value)|
+        options[(key.to_sym rescue key) || key] = value
+        options
+      end
+    end
+
+    def self.recursively_symbolize_keys(object)
+      if object.is_a? Hash
+        symbolized_hash = symbolize_keys(object)
+        symbolized_hash.each do |key, value|
+          symbolized_hash[key] = recursively_symbolize_keys(value)
+        end
+        symbolized_hash
+      elsif object.is_a? Array
+        object.map { |value| recursively_symbolize_keys(value) }
+      else
+        object
+      end
+    end
+  end
+end

data/lib/simple_geo/record.rb

@@ -0,0 +1,56 @@
+module SimpleGeo
+  class Record
+    attr_accessor :layer, :id, :lat, :lon, :type, :created, :properties
+
+    def initialize(options={})
+      options = {
+        :created => Time.now,
+        :type => 'object',
+        :properties => {}
+      }.merge(options)
+
+      @id = options[:id]
+      @layer = options[:layer]
+      @type = options[:type]
+      @lat = options[:lat]
+      @lon = options[:lon]
+      @created = options[:created]
+      @properties = options[:properties]
+    end
+
+    def to_hash
+      {
+        :type => 'Feature',
+        :id => id,
+        :created => created.to_i,
+        :geometry => {
+          :type => 'Point',
+          :coordinates => [ lon, lat ]
+        },
+        :properties => properties.merge({
+          :type => type
+        })
+      }
+    end
+
+    def to_json
+      self.to_hash.to_json
+    end
+
+    def ==(other)
+      other.class == self.class && self.to_hash == other.to_hash
+    end
+
+    def self.parse_geojson_hash(json_hash)
+      Record.new(
+        :id => json_hash['id'],
+        :type => json_hash['properties'].delete('type'),
+        :lat => json_hash['geometry']['coordinates'][1],
+        :lon => json_hash['geometry']['coordinates'][0],
+        :created => Time.at(json_hash['created']),
+        :properties => HashUtils.recursively_symbolize_keys(json_hash['properties'])
+      )
+    end
+
+  end
+end

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