factual-api 0.1

data/CHANGELOG.md

@@ -0,0 +1,9 @@
+## v0.1
+* initial version
+** a table agnostic read api, usage as: api.table(table_alias).rows
+** normal (but powerful) filters, usage as: api.table(:global).filters(:country => {'$sw' => 'u'}, :region => 'ca')
+** general mapping of ALL v3 api params, e.g. geo, query, sort, select, limit, offset
+** places sugers, usage as: api.crosswalk(FACTUAL_ID); api.resolve(:name => 'factual inc.', :region => 'ca')
+** facets
+** different format, usage as: json_api = Factual::Api.new( KEY, SECRET, :json)
+** immutable api objects

data/README.md

@@ -0,0 +1,73 @@
+# Introduction
+
+This is the Factual supported Ruby driver for [Factual's public API](http://developer.factual.com/display/docs/Factual+Developer+APIs+Version+3).
+
+# Installation
+
+    gem 'factual-api'
+    require 'factual_api'
+    factual = Factual::Api.new(YOUR_KEY, YOUR_SECRET)
+  
+# Examples
+
+## Quick Sample 
+
+    # Returns Places with names beginning with "Star"
+    factual.table("places").filters("name" => {"$bw" => "Star"}).rows
+
+## Read (with all features)
+
+    # 1. Specify the table Global
+    query = factual.table("global")
+
+    # 2. Filter results in country US (For more filters syntax, refer to [Core API - Row Filters](http://developer.factual.com/display/docs/Core+API+-+Row+Filters))
+    query = query.filters("country" => "US")
+
+    # 3. Search for "sushi" or "sashimi" (For more search syntax, refer to [Core API - Search Filters](http://developer.factual.com/display/docs/Core+API+-+Search+Filters))
+    query = query.search("sushi", "sashimi")
+
+    # 4. Filter by Geo (For more geo syntax, refer to [Core API - Geo Filters](http://developer.factual.com/display/docs/Core+API+-+Geo+Filters))
+    query = query.geo("$circle" => {"$center" => [34.06021, -118.41828], "$meters" => 5000})
+
+    # 5. Sort it 
+    query = query.sort("name")            # ascending 
+    query = query.sort_desc("name")       # descending
+    query = query.sort("address", "name") # sort by multiple columns
+
+    # 6. Page it
+    query = query.page(2, :per => 10)
+
+    # 7. Finally, get response in Factual::Row objects
+    query.first    # return one row
+    query.rows     # return many rows
+
+    # 8. Returns total row counts that matches the criteria
+    query.total_count
+
+    # You can chain the query methods, like this
+    factual.table("places").filters("region" => "CA").search("sushi", "sashimi").geo("$circle" => {"$center" => [34.06021, -118.41828], "$meters" => 5000}).sort("name").page(2, :per => 10).rows
+
+## Crosswalk
+
+    # Concordance information of a place
+    FACTUAL_ID = "110ace9f-80a7-47d3-9170-e9317624ebd9"
+    factual.crosswalk(FACTUAL_ID)
+
+## Resolve
+
+    # Returns resolved entities as Factual::Row objects
+    factual.resolve("name" => "McDonalds",
+                    "address" => "10451 Santa Monica Blvd",
+                    "region" => "CA",
+                    "postcode" => "90025")
+
+## Schema
+
+    # Returns a Factual::Table object whose fields are an array of Factual::Field objects
+    factual.table("global").schema()
+
+## Facets
+
+    # Returns number of starbucks in regions thoughout the world
+    factual.table("global").select("country", "region").search("starbucks").min_count(2).facets()
+

data/lib/factual_api.rb

@@ -0,0 +1,229 @@
+require 'oauth'
+require 'json'
+require 'uri'
+require 'ostruct'
+
+module Factual
+  class Api
+    API_V3_HOST = "http://api.v3.factual.com"
+    DRIVER_VERSION_TAG = "factual-ruby-driver-1.0"
+
+    DEFAULT_LIMIT = 20
+    PARAM_ALIASES = { :search => :q }
+
+    VALID_PARAMS = {
+      :read      => [ :filters, :search, :geo, :sort, :select, :limit, :offset ],
+      :resolve   => [ :values ],
+      :crosswalk => [ :factual_id ],
+      :facets    => [ :filters, :search, :geo, :limit, :select, :min_count ],
+      :schema    => [ ],
+      :any       => [ :include_count ]
+    }
+
+    attr_accessor :access_token, :path, :params, :action, :format
+
+    # initializers
+    # ----------------
+    def initialize(key, secret, format = :object)
+      @access_token = OAuth::AccessToken.new(
+        OAuth::Consumer.new(key, secret))
+
+      @format = format
+      @params = Hash.new
+    end
+    
+    # helper functions
+    # ----------------
+    def self.clone(api)
+      new_api = self.new(nil, nil)
+
+      new_api.access_token = api.access_token
+      new_api.path         = api.path
+      new_api.action       = api.action
+      new_api.format       = api.format
+      new_api.params       = api.params.clone
+
+      return new_api
+    end
+
+    def set_param(key, value)
+      @params[key] = value
+    end
+
+    # attributes, after 'get'
+    # ----------------
+    def first
+      row_data = response["data"].first 
+
+      if (@format == :json) # or :hash ?
+        return row_data
+      else
+        return Row.new(row_data)
+      end
+    end
+
+    def schema
+      @path  += "/schema"
+      @action = :schema
+
+      view   = response["view"]
+      fields = view["fields"]
+
+      schema = Table.new(view)
+      if schema && fields
+        schema.fields = fields.collect do |f|
+          Field.new(f)
+        end
+      end
+
+      return schema
+    end
+
+    def facets
+      @path  += "/facets"
+      @action = :facets
+      columns = response["data"]
+      
+      return Facet.new(columns)
+    end
+
+    def total_count
+      response["total_row_count"]
+    end
+
+    def rows
+      return response["data"] if (@format == :json)
+
+      return response["data"].collect do |row_data|
+        Row.new(row_data)
+      end
+    end
+
+    # query builder, returns immutable ojbects
+    # ----------------
+    VALID_PARAMS.values.flatten.uniq.each do |param|
+      define_method(param) do |*args|
+        api = self.class.clone(self)
+        val = (args.length == 1) ? args.first : args.join(',')
+
+        api.set_param(param, val)
+
+        return api
+      end
+    end
+    
+    # sugers
+    # ----------------
+    def sort_desc(*args)
+      api = self.class.clone(self)
+      columns = args.collect{ |col|"#{col}:desc" }
+      api.set_param(:sort, columns.join(','))
+
+      return api
+    end
+
+    def page(page_num, paging_opts = {})
+      limit = (paging_opts[:per] || paging_opts["per"]).to_i
+      limit = DEFAULT_LIMIT if limit < 1
+
+      page_num = page_num.to_i
+      page_num = 1 if page_num < 1
+      offset   = (page_num - 1) * limit
+
+      api = self.class.clone(self)
+      api.set_param(:limit, limit)
+      api.set_param(:offset, offset)
+
+      return api
+    end
+
+    # actions
+    # ----------------
+    def crosswalk(factual_id)
+      api = self
+
+      api.path   = "places/crosswalk"
+      api.action = :crosswalk
+      api.params = { :factual_id => factual_id }
+
+      return api
+    end
+
+    def resolve(values)
+      api = self
+
+      api.action = :resolve
+      api.path   = "places/resolve"
+      api.params = { :values => values }
+
+      return api
+    end
+
+    def table(table_id_or_alias)
+      api = self
+      if @response
+        api = self.class.clone(self)
+      end
+
+      api.path   = "t/#{table_id_or_alias}"
+      api.action = :read
+
+      return api
+    end
+
+    private
+
+    # real requesting
+    # ----------------
+    def response
+      @response ||= {}
+      return @response[@action] if @response[@action]
+      
+      # always include count for reads
+      @params[:include_count] = true unless @action == :schema
+
+      res = request()
+
+      code    = res.code
+      json    = res.body
+      payload = JSON.parse(json)
+
+      if payload["status"] == "ok"
+        @response[@action] = payload["response"]
+      else
+        raise StandardError.new(payload["message"])
+      end
+      
+      return @response[@action]
+    end
+
+    def request
+      url     = "#{API_V3_HOST}/#{@path}?#{query_string}" 
+      headers = {"X-Factual-Lib" => DRIVER_VERSION_TAG}
+
+      return @access_token.get(url, headers)
+    end
+
+    def query_string()
+      arr = []
+      @params.each do |param, v|
+        unless (VALID_PARAMS[@action] + VALID_PARAMS[:any]).include?(param)
+          raise StandardError.new("InvalidArgument #{param} for #{@action}") 
+        end
+        param_alias = PARAM_ALIASES[param.to_sym] || param.to_sym
+
+        v = v.to_json if v.class == Hash
+        arr << "#{param_alias}=#{URI.escape(v.to_s)}"
+      end
+      return arr.join("&")
+    end
+
+  end
+
+  # response classes
+  # ----------------
+  class Row < OpenStruct; end
+  class Facet < OpenStruct; end
+  class Table < OpenStruct; end
+  class Field < OpenStruct; end
+end

metadata

@@ -0,0 +1,70 @@
+--- !ruby/object:Gem::Specification 
+name: factual-api
+version: !ruby/object:Gem::Version 
+  prerelease: 
+  version: "0.1"
+platform: ruby
+authors: 
+- Forrest Cao
+- Aaron Crow
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2012-01-12 00:00:00 +08:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: rspec
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+  type: :development
+  version_requirements: *id001
+description: Factual's official Ruby driver for the Factual public API.
+email: 
+- aaron@factual.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- lib/factual_api.rb
+- README.md
+- CHANGELOG.md
+has_rdoc: true
+homepage: http://github.com/Factual/factual-ruby-driver
+licenses: []
+
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: 1.3.6
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.6.2
+signing_key: 
+specification_version: 3
+summary: Ruby driver for Factual
+test_files: []
+