factual-api 1.1 → 1.2

data/CHANGELOG.md

@@ -1,9 +1,20 @@
+## v1.2
+* releasing geo features, facets, writes, multi and monetize
+
+## v1.1.9
+* added geocode, geopulse and world-geographies
+* added facets
+* adding writes (submit, flag)
+* updated documents
+* added multi
+* added monetize
+
 ## v1.1
-* debug mode
-* raw read
+* added debug mode
+* added raw read
 
 ## v1.0.3
-* adding crosswalk(namespace_id, namespace)
+* added crosswalk(namespace_id, namespace)
 
 ## v1.0.2
 * lazy getting total_count of a query

data/README.md

@@ -2,12 +2,6 @@
 
 This is the Factual supported Ruby driver for [Factual's public API](http://developer.factual.com/display/docs/Factual+Developer+APIs+Version+3).
 
-This API supports queries to Factual's Read, Schema, Crosswalk, and Resolve APIs. Full documentation is available on the Factual website:
-
-*   [Read](http://developer.factual.com/display/docs/Factual+Developer+APIs+Version+3): Search the data
-*   [Schema](http://developer.factual.com/display/docs/Core+API+-+Schema): Get table metadata
-*   [Crosswalk](http://developer.factual.com/display/docs/Places+API+-+Crosswalk): Get third-party IDs
-*   [Resolve](http://developer.factual.com/display/docs/Places+API+-+Resolve): Enrich your data and match it against Factual's
 
 This driver is supported via the [Factual Developer Group](https://groups.google.com/group/factual_developers)
 
@@ -62,7 +56,7 @@ factual.table("restaurants-us")
   .filters({"locality" => "los angeles", "rating" => {"$gte" => 4}, "wifi" => true}).rows
 ````
 
-## Simple Crosswalk Example
+## Simple Places Example
 
 ````ruby
 # Concordance information of a place
@@ -76,8 +70,6 @@ query = factual.crosswalk(SIMPLEGEO_ID, :simplegeo)
 query.rows
 ````
 
-## Simple Resolve Example
-
 ````ruby
 # Returns resolved entities as an array of hashes
 query = factual.resolve("name" => "McDonalds",
@@ -89,6 +81,18 @@ query.first["resolved"]   # true or false
 query.rows                # all candidate rows
 ````
 
+````ruby
+# Returns the nearest valid address information
+query = factual.geocode(34.06021,-118.41828)
+query.first
+````
+
+````ruby
+# Returns georeferenced attributes generated by Factual
+query = factual.geopulse(34.06021,-118.41828).select("commercial_density", "commercial_profile", "income", "race")
+query.first["income"]
+````
+
 ## More Read Examples
 
 ````ruby
@@ -393,6 +397,299 @@ You can query Factual for entities located within a geographic area. For example
 query = query.geo("$circle" => {"$center" => [34.06021, -118.41828], "$meters" => 5000})
 ````
 
+# Facets
+
+The driver fully supports Factual's Facets feature, which lets you return row counts for Factual tables, grouped by facets of data.  For example, you may want to query all businesses within 1 mile of a location and for a count of those businesses by category.
+
+For example:
+
+````ruby
+# Returns a count of Starbucks by country
+factual.facets("global").select("country").search("starbucks").columns
+````
+
+## All Top Level Facets Parameters
+
+<table>
+  <col width="33%"/>
+  <col width="33%"/>
+  <col width="33%"/>
+  <tr>
+    <th>Parameter</th>
+    <th>Description</th>
+    <th>Example</th>
+  </tr>
+  <tr>
+    <td>select</td>
+    <td>The fields for which facets should be generated. The response will not be ordered identically to this list, nor will it reflect any nested relationships between fields.</td>
+    <td><tt>.select("region", "locality")</tt></td>
+  </tr>
+  <tr>
+    <td>limit</td>
+    <td>The maximum number of unique facet values that can be returned for a single field. Range is 1-250. The default is 25.</td>
+    <td><tt>.limit(10)</tt></td>
+  </tr>
+  <tr>
+    <td>filters</td>
+    <td>Restrict the data returned to conform to specific conditions.</td>
+    <td><tt>.filters("name" => {"$bw" => "starbucks"})</tt></td>
+  </tr>
+  <tr>
+    <td>include_count</td>
+    <td>Include a count of the total number of rows in the dataset that conform to the request based on included filters. Requesting the row count will increase the time required to return a response. The default behavior is to NOT include a row count. When the row count is requested, the Response object will contain a valid total row count via <tt>.getTotalRowCount()</tt>.</td>
+    <td><tt>.include_count</tt></td>
+  </tr>
+  <tr>
+    <td>geo</td>
+    <td>Restrict data to be returned to be within a geographical range.</td>
+    <td>(See the section on Geo Filters)</td>
+  </tr>
+  <tr>
+    <td>search</td>
+    <td>Full text search query string.</td>
+    <td>
+      Find "sushi":<br><tt>.search("sushi")</tt><p>
+      Find "sushi" or "sashimi":<br><tt>.search("sushi, sashimi")</tt><p>
+      Find "sushi" and "santa" and "monica":<br><tt>.search("sushi santa monica")</tt>
+    </td>
+  </tr>
+</table>  
+  
+</table>
+
+
+# Flag
+
+Factual's Flag feature enables flagging problematic rows in Factual tables. Use this feature if you are requesting for an entity to be deleted or merged into a duplicate record.
+
+## Simple Flag Example
+
+````ruby
+# User user123 flags row 0545b03f-9413-44ed-8882-3a9a461848da in the global dataset as inaccurate
+factual.flag("global", "0545b03f-9413-44ed-8882-3a9a461848da", :inaccurate, "user123").write
+````
+
+The reason for flagging must be one of the following:
+<ul>
+<li>:duplicate
+<li>:nonexistent
+<li>:inaccurate
+<li>:inappropriate
+<li>:spam
+<li>:other
+</ul>
+
+You can also create a Flag object and set it with optional parameters beforing writing it. For example:
+
+````ruby
+flag = factual.flag("global", "0545b03f-9413-44ed-8882-3a9a461848da", :inaccurate, "user123")
+flag = flag.comment("this row is outdated").reference("http://www.example.com/somepage.html")
+flag.write
+````
+
+## Optional Flag Parameters
+
+<table>
+  <tr>
+    <th>Parameter</th>
+    <th>Description</th>
+    <th>Example</th>
+  </tr>
+  <tr>
+    <td>comment</td>
+    <td>Any english text comment that may help explain your corrections.</td>
+    <td><tt>.comment("this row is outdated")</tt></td>
+  </tr>
+  <tr>
+    <td>reference</td>
+    <td>A reference to a URL, title, person, etc. that is the source of this data.</td>
+    <td><tt>.reference("http://www.example.com/somepage.html")</tt></td>
+  </tr>
+</table>  
+
+
+# Geopulse
+
+The driver fully supports Factual's <a href="http://developer.factual.com/display/DOCS/Places+API+-+Geopulse">Geopulse</a> feature, which provides point-based access to geographic attributes: you provide a long/lat coordinate pair, we provide everything we can know about that geography. 
+
+The Geopulse API is made up of several "pulses".  Pulses are georeferenced attributes generated by Factual, sourced from openly available content (such as the US Census), or provided to Factual by proprietary third-parties.
+
+## Simple Geopulse Example
+
+The <tt>geopulse</tt> method fetches results based on the given point:
+
+````ruby
+query = factual.geopulse(34.06021, -118.41828).select("commercial_density", "commercial_profile")
+query.first
+````
+
+
+## All Top Level Geopulse Parameters
+
+<table>
+  <tr>
+    <th>Parameter</th>
+    <th>Description</th>
+    <th>Example</th>
+  </tr>
+  <tr>
+    <td>geo</td>
+    <td>A geographic point around which information is retrieved.</td>
+    <td><tt>factual.geopulse(34.06021, -118.41828)</tt></td>
+  </tr>
+  <tr>
+    <td>select</td>
+    <td>What fields to include in the query results. Note that the order of fields will not necessarily be preserved in the resulting JSON response due to the nature of JSON hashes.</td>
+    <td><tt>.select("commercial_density", "commercial_profile")</tt></td>
+  </tr>
+</table>	
+
+Available pulses include commercial_density, commercial_profile, income, race, hispanic, and age_by_gender.
+
+You can see a full list of available Factual pulses and their possible return values, as well as full documentation, in [the Factual API docs for Geopulse](http://developer.factual.com/display/docs/Places+API+-+Geopulse).
+
+
+# Reverse Geocoder
+
+The driver fully supports Factual's <a href="http://developer.factual.com/display/DOCS/Places+API+-+Reverse+Geocoder">Reverse Geocoder</a> feature, which returns the nearest valid address given a longitude and latitude. 
+
+## Simple Reverse Geocoder Example
+	
+The <tt>geocode</tt> method fetches results based on the given point:
+
+````ruby
+query = factual.geocode(34.06021, -118.41828)
+query.first
+````
+
+## All Top Level Reverse Geocoder Parameters
+
+<table>
+  <tr>
+    <th>Parameter</th>
+    <th>Description</th>
+    <th>Example</th>
+  </tr>
+  <tr>
+    <td>geo</td>
+    <td>A valid geographic point for which the closest address is retrieved.</td>
+    <td><tt>factual.geocode(34.06021, -118.41828)</tt></td>
+  </tr>
+</table>
+
+
+# World Geographies
+
+World Geographies contains administrative geographies (states, counties, countries), natural geographies (rivers, oceans, continents), and assorted geographic miscallaney.  This resource is intended to complement Factual's Global Places and add utility to any geo-related content.
+
+Common use cases include:
+
+* Determining all cities within a state or all postal codes in a city
+* Creating a type-ahead placename lookup
+* Validating data against city, state, country and county names
+* A translation table to convert between the search key used by a user, i.e. '慕尼黑' or 'Munich' for the native 'München'
+
+You can use the <tt>query</tt> function to query World Geographies, supplying "world-geographies" as the table name.
+
+Examples:
+
+````ruby
+# Get all towns surrounding Philadelphia
+query = factual.table("world-geographies").select("neighbors").filters(:factual_id => "08ca0f62-8f76-11e1-848f-cfd5bf3ef515")
+query.rows
+````
+
+````ruby
+# Find the town zipcode 95008 belongs to
+query = factual.table("world-geographies").filters(
+    {"$and" => [ {:name => "95008"},
+                 {:country => "us"} ]} )
+query.rows
+````
+
+````ruby
+# Searching by placename, placetype, country and geographic hierarchy
+query = factual.table("world-geographies").filters(
+    {"$and" => [ {:name => "wayne"},
+                 {:country => "us"},
+                 {:placetype => "locality"},
+                 {:ancestors => {:"$search" => "08666f5c-8f76-11e1-848f-cfd5bf3ef515"}} ]} )
+
+query.rows
+````
+
+For more details about World Geographies, including schema, see [the main API docs for World Geographies](http://developer.factual.com/display/docs/World+Geographies).
+
+
+# Submit
+
+The driver fully supports Factual's Submit feature, which enables you to submit edits to existing rows and/or submit new rows of data in Factual tables. For information on deleting records, see Flag.
+
+
+## Simple Submit Examples
+
+The <tt>submit</tt> method is a contribution to edit an existing row or add a new row:
+
+````ruby
+# Submit a new row to Factual's global dataset
+factual.submit("global", "user123").values({"name" => "McDenny's", "address" => "1 Main St.", "locality" => "Bedrock", "region" => "BC"}).write
+````
+
+````ruby
+# Submit a correction to an existing row in Factual's places dataset.
+# Also set optional comment and reference
+submit = factual.submit("places", "user123").values({:name => "McDenny's"})
+submit = submit.comment("They changed their name last month").reference("http://www.example.com/mypage.html")
+submit.write
+````
+
+
+## Required Submit Parameters
+
+<table>
+  <tr>
+    <th>Parameter</th>
+    <th>Description</th>
+    <th>Example</th>
+  </tr>
+  <tr>
+    <td>values</td>
+    <td>A hash of names and values to be added to a Factual table</td>
+    <td><tt>{"name" => "McDenny's", "address" => "1 Main St.", "locality" => "Bedrock", "region" => "BC"}</tt></td>
+  </tr>
+  <tr>
+    <td>user</td>
+    <td>An arbitrary token representing the user contributing the data.</td>
+    <td><tt>user123</tt></td>
+  </tr>
+</table>
+
+## Optional Submit Parameters
+
+<table>
+  <tr>
+    <th>Parameter</th>
+    <th>Description</th>
+    <th>Example</th>
+  </tr>
+  <tr>
+    <td>factual_id</td>
+    <td>The factual_id of the row to which you want to submit a correction</td>
+    <td><tt>.factual_id("0545b03f-9413-44ed-8882-3a9a461848da")</tt></td>
+  </tr>
+  <tr>
+    <td>comment</td>
+    <td>Any english text comment that may help explain your corrections.</td>
+    <td><tt>.comment("They changed their name last month")</tt></td>
+  </tr>
+  <tr>
+    <td>reference</td>
+    <td>A reference to a URL, title, person, etc. that is the source of this data.</td>
+    <td><tt>.reference("http://www.example.com/mypage.html")</tt></td>
+  </tr>
+</table>	
+
+
 # Schema
 
 You can query Factual for the detailed schema of any specific table in Factual. For example:
@@ -413,15 +710,51 @@ forward-slash) and the request will be made using your OAuth token:
 factual.read('/t/restaurants-us?filters={"name":{"$bw":"Star"}}&include_count=true')
 ````
 
+# Monetize
+
+The <a href="http://developer.factual.com/display/docs/Places+API+-+Monetize">Monetize API</a> enables you to find deals for places in Factual's Global Places database.
+
+````ruby
+query = @factual.monetize.search('sushi').filters(:place_postcode => 90067)
+query.rows
+````
+
+# Multi
+
+The <a href="http://developer.factual.com/display/docs/Core+API+-+Multi">multi API call</a> enables making multiple API GET requests on the same connection. Multi supports the read, crosswalk, resolve, facets, geocode and geopulse API calls.
+
+````ruby
+places_query = @factual.table("places").search('sushi').filters(:postcode => 90067)
+geocode_query = @factual.geocode(34.06021,-118.41828)
+
+responses = @factual.multi(
+  :nearby_sushi => places_query,
+  :factual_inc => geocode_query)
+
+responses[:nearby_sushi].first
+responses[:factual_inc].first
+````
+
 # Debug Mode
 
-To see the query paths generated by the driver you can use it in debug mode by passing true as
+To see the query paths generated by the driver you can use it in debug mode by passing :debug => true as
 the third argument of the Factual constructor. Here is an example in irb:
 
 
 ````ruby
-> factual = Factual.new(key, secret, true)
+> factual = Factual.new(key, secret, :debug => true)
 > factual.table("places").filters("name" => {"$bw" => "starbucks"})
 Request: http://api.v3.factual.com/t/places?filters=%7B%22name%22%3A%7B%22%24bw%22%3A%22starbucks%22%7D%7D
  => [{"address"=>"11290 Donner Pass Rd", "category"=>"Food & Beverage > Cafes, Coffee Houses & Tea Houses", ...
 ````
+
+# Where to Get Help
+
+If you think you've identified a specific bug in this driver, please file an issue in the github repo. Please be as specific as you can, including:
+
+  * What you did to surface the bug
+  * What you expected to happen
+  * What actually happened
+  * Detailed stack trace and/or line numbers
+
+If you are having any other kind of issue, such as unexpected data or strange behaviour from Factual's API (or you're just not sure WHAT'S going on), please contact us through [GetSatisfaction](http://support.factual.com/factual).

data/lib/factual.rb

@@ -1,18 +1,31 @@
 require 'oauth'
 require 'factual/api'
 require 'factual/query/table'
+require 'factual/query/facets'
 require 'factual/query/resolve'
 require 'factual/query/crosswalk'
+require 'factual/query/monetize'
+require 'factual/query/geocode'
+require 'factual/query/geopulse'
+require 'factual/write/flag'
+require 'factual/write/submit'
+require 'factual/multi'
 
 class Factual
-  def initialize(key, secret, debug_mode = false)
-    @api = API.new(generate_token(key, secret), debug_mode)
+  def initialize(key, secret, options = {})
+    debug_mode = options[:debug].nil? ? false : options[:debug]
+    host = options[:host]
+    @api = API.new(generate_token(key, secret), debug_mode, host)
   end
 
   def table(table_id_or_alias)
     Query::Table.new(@api, "t/#{table_id_or_alias}")
   end
 
+  def facets(table_id_or_alias)
+    Query::Facets.new(@api, "t/#{table_id_or_alias}")
+  end
+
   def crosswalk(namespace_id, namespace = nil)
     if namespace
       Query::Crosswalk.new(@api, :namespace_id => namespace_id, :namespace => namespace)
@@ -21,14 +34,54 @@ class Factual
     end
   end
 
+  def monetize
+    Query::Monetize.new(@api)
+  end
+
   def resolve(values)
     Query::Resolve.new(@api, :values => values)
   end
 
+  def geocode(lat, lng)
+    Query::Geocode.new(@api, lat, lng)
+  end
+
+  def geopulse(lat, lng)
+    Query::Geopulse.new(@api, lat, lng)
+  end
+
   def read(path)
     @api.raw_read(path)
   end
 
+  def multi(queries)
+    multi = Multi.new(@api, queries)
+    multi.send
+  end
+
+  def flag(table, factual_id, problem, user)
+    flag_params = {
+      :table => table,
+      :factual_id => factual_id,
+      :problem => problem,
+      :user => user }
+
+    Write::Flag.new(@api, flag_params)
+  end
+
+  def submit(*params)
+    values = {}
+    values = params.last if params.last.is_a? Hash
+
+    table, user, factual_id = params
+    submit_params = {
+      :table => table,
+      :user => user,
+      :factual_id => factual_id,
+      :values => values }
+    Write::Submit.new(@api, submit_params)
+  end
+
   private
 
   def generate_token(key, secret)

data/lib/factual/api.rb

@@ -3,46 +3,82 @@ require 'cgi'
 
 class Factual
   class API
-    API_V3_HOST        = "http://api.v3.factual.com"
-    DRIVER_VERSION_TAG = "factual-ruby-driver-1.0"
-    PARAM_ALIASES      = { :search => :q, :sort_asc => :sort }
+    VERSION = "1.2"
+    API_V3_HOST = "api.v3.factual.com"
+    DRIVER_VERSION_TAG = "factual-ruby-driver-v" + VERSION
+    PARAM_ALIASES = { :search => :q, :sort_asc => :sort }
 
-    def initialize(access_token, debug_mode = false)
+    def initialize(access_token, debug_mode = false, host = nil)
       @access_token = access_token
       @debug_mode = debug_mode
+      @host = host || API_V3_HOST
     end
 
-    def execute(query, other_params={})
+    def get(query, other_params = {})
       merged_params = query.params.merge(other_params)
       handle_request(query.action || :read, query.path, merged_params)
     end
 
+    def post(request)
+      response = make_request("http://" + @host + request.path, request.body, :post)
+      payload = JSON.parse(response.body)
+      handle_payload(payload)
+    end
+
     def schema(query)
-      handle_request(:schema, query.path + "/schema", query.params)["view"]
+      handle_request(:schema, query.path, query.params)["view"]
     end
 
     def raw_read(path)
-      payload = JSON.parse(make_request("#{API_V3_HOST}#{path}").body)
+      payload = JSON.parse(make_request("http://#{@host}#{path}").body)
       handle_payload(payload)
     end
 
+    def full_path(action, path, params)
+      fp = "/#{path}"
+      fp += "/#{action}" unless action == :read
+      fp += "?#{query_string(params)}"
+    end
+
     private
 
     def handle_request(action, path, params)
-      url = "#{API_V3_HOST}/#{path}?#{query_string(params)}"
-      puts "Request: #{url}" if @debug_mode
+      url = "http://#{@host}" + full_path(action, path, params)
+
       payload = JSON.parse(make_request(url).body)
-      handle_payload(payload)
+
+      if (path == :multi)
+         payload.inject({}) do |res, item|
+           name, p = item
+           res[name] = handle_payload(p)
+         end
+      else
+        handle_payload(payload)
+      end
     end
 
     def handle_payload(payload)
-      raise StandardError.new(payload["message"]) unless payload["status"] == "ok"
+      raise StandardError.new(payload.to_json) unless payload["status"] == "ok"
       payload["response"]
     end
 
-    def make_request(url)
+    def make_request(url, body=nil, method=:get)
+      start_time = Time.now
+
       headers = { "X-Factual-Lib" => DRIVER_VERSION_TAG }
-      @access_token.get(url, headers)
+
+      res = if (method == :get)
+              @access_token.get(url, headers)
+            elsif (method == :post)
+              @access_token.post(url, body, headers)
+            else
+              raise StandardError.new("Unknown http method")
+            end
+
+      elapsed_time = (Time.now - start_time) * 1000
+      debug(url, method, headers, body, res, elapsed_time) if @debug_mode
+
+      res
     end
 
     def query_string(params)
@@ -54,5 +90,29 @@ class Factual
 
       query_array.join("&")
     end
+
+    def debug(url, method, headers, body, res, elapsed_time)
+      res_headers = res.to_hash.inject({}) do |h, kv|
+        k, v = kv
+        h[k] = v.join(',')
+        h
+      end
+
+      puts "--- Driver version: #{DRIVER_VERSION_TAG}"
+      puts "--- request debug ---"
+      puts "req url: #{url}"
+      puts "req method: #{method.upcase}"
+      puts "req headers: #{JSON.pretty_generate(headers)}"
+      puts "req body: #{body}" if body
+      puts "---------------------"
+      puts "--- response debug ---"
+      puts "resp status code: #{res.code}"
+      puts "resp status message: #{res.message}"
+      puts "resp headers: #{JSON.pretty_generate(res_headers)}"
+      puts "resp body: #{res.body}"
+      puts "---------------------"
+      puts "Elapsed time: #{elapsed_time} msecs"
+      puts
+    end
   end
 end

data/lib/factual/multi.rb

@@ -0,0 +1,38 @@
+class Factual
+  class Multi
+    attr_reader :action, :path, :params
+
+    def initialize(api, queries)
+      @api = api
+      @queries = queries
+
+      @action = nil
+      @path = :multi
+      @params = queries_param
+
+      @responses = {}
+    end
+
+    def send
+      res = @api.get(self)
+      @queries.each do |name, query|
+        query.populate(res[name])
+        @responses[name] = query
+      end
+
+      @responses
+    end
+
+    private
+
+    def queries_param
+      query_urls = {}
+      @queries.each do |name, query|
+        query_urls[name] = query.full_path
+      end
+
+      { :queries => query_urls }
+    end
+
+  end
+end

data/lib/factual/query/base.rb

@@ -27,7 +27,7 @@ class Factual
       end
 
       def total_count
-        resp = @api.execute(self, :include_count => true, :limit => 1)
+        resp = @api.get(self, :include_count => true, :limit => 1)
         resp["total_row_count"]
       end
 
@@ -35,6 +35,15 @@ class Factual
         @schema ||= @api.schema(self)
       end
 
+      # TODO move to Multiable module, and support multi writes
+      def full_path
+        @api.full_path(@action, @path, @params)
+      end
+
+      def populate(query_response)
+        @response = query_response
+      end
+
       private
 
       def form_value(args)
@@ -43,7 +52,7 @@ class Factual
       end
 
       def response
-        @response ||= @api.execute(self)
+        @response ||= @api.get(self)
       end
     end
   end

data/lib/factual/query/crosswalk.rb

@@ -5,7 +5,7 @@ class Factual
     class Crosswalk < Base
       def initialize(api, params = {})
         @path = "places/crosswalk"
-        @action = :crosswalk
+        @action = :read
         super(api, params)
       end
 

data/lib/factual/query/facets.rb

@@ -0,0 +1,41 @@
+require 'factual/query/base'
+
+class Factual
+  module Query
+    class Facets < Base
+      DEFAULT_LIMIT = 20
+      VALID_PARAMS  = [
+        :filters, :search, :geo, 
+        :select, 
+        :limit, :min_count,
+        :include_count
+      ] 
+
+      def initialize(api, path, params = {})
+        @path = path
+        @action = :facets
+        super(api, params)
+      end
+
+      VALID_PARAMS.each do |param|
+        define_method(param) do |*args|
+          Facets.new(@api, @path, @params.merge(param => form_value(args)))
+        end
+      end
+
+      def each(&block)
+        columns.each do |col, data|
+          block.call(col, data)
+        end
+      end
+
+      def [](col)
+        columns[col]
+      end
+
+      def columns
+        response["data"]
+      end
+    end
+  end
+end

data/lib/factual/query/geocode.rb

@@ -0,0 +1,15 @@
+require 'factual/query/base'
+
+class Factual
+  module Query
+    class Geocode < Base
+      def initialize(api, lat, lng)
+        @path = "places/geocode"
+        @action = :read
+        @params = {:geo => {"$point" => [lat, lng]}}
+
+        super(api, @params)
+      end
+    end
+  end
+end

data/lib/factual/query/geopulse.rb

@@ -0,0 +1,21 @@
+require 'factual/query/base'
+
+class Factual
+  module Query
+    class Geopulse < Base
+      def initialize(api, lat, lng, params={})
+        @path = "places/geopulse"
+        @action = :read
+        @lat = lat
+        @lng = lng
+
+        @params = {:geo => {"$point" => [lat, lng]}}.merge(params)
+        super(api, @params)
+      end
+
+      def select(*args)
+        self.class.new(@api, @lat, @lng, :select => form_value(args))
+      end
+    end
+  end
+end

data/lib/factual/query/monetize.rb

@@ -0,0 +1,24 @@
+require 'factual/query/base'
+
+class Factual
+  module Query
+    class Monetize < Base
+      VALID_PARAMS  = [
+        :filters, :search, :geo, 
+        :limit, :offset
+      ] 
+
+      def initialize(api, params = {})
+        @path = "places/monetize"
+        @action = :read
+        super(api, params)
+      end
+
+      VALID_PARAMS.each do |param|
+        define_method(param) do |*args|
+          self.class.new(@api, @params.merge(param => form_value(args)))
+        end
+      end
+    end
+  end
+end

data/lib/factual/query/resolve.rb

@@ -5,7 +5,7 @@ class Factual
     class Resolve < Base
       def initialize(api, params = {})
         @path = "places/resolve"
-        @action = :resolve
+        @action = :read
         super(api, params)
       end
 

data/lib/factual/query/table.rb

@@ -4,6 +4,12 @@ class Factual
   module Query
     class Table < Base
       DEFAULT_LIMIT = 20
+      VALID_PARAMS  = [
+        :filters, :search, :geo, 
+        :sort, :select, 
+        :limit, :offset, 
+        :include_count
+      ] 
 
       def initialize(api, path, params = {})
         @path = path
@@ -11,7 +17,7 @@ class Factual
         super(api, params)
       end
 
-      [:filters, :search, :geo, :sort, :select, :limit, :offset, :include_count].each do |param|
+      VALID_PARAMS.each do |param|
         define_method(param) do |*args|
           Table.new(@api, @path, @params.merge(param => form_value(args)))
         end

data/lib/factual/write/base.rb

@@ -0,0 +1,34 @@
+class Factual
+  module Write
+    class Base
+      def initialize(api, params)
+        @api = api
+        @params = params
+      end
+
+      def path
+        raise "Virtual method called"
+      end
+
+      def body
+        keys = @params.keys.reject { |key| [:table, :factual_id].include?(key) }
+        keys.map { |key| "#{key}=#{CGI.escape(stringify(@params[key]))}" }.join("&")
+      end
+
+      def write
+        @api.post(self)
+      end
+
+      private
+
+      def stringify(value)
+        value.class == Hash ? value.to_json : value.to_s
+      end
+
+      def form_value(args)
+        args = args.map { |arg| arg.is_a?(String) ? arg.strip : arg }
+        args.length == 1 ? args.first : args.join(',')
+      end
+    end
+  end
+end

data/lib/factual/write/flag.rb

@@ -0,0 +1,37 @@
+require 'factual/write/base'
+
+class Factual
+  module Write
+    class Flag < Base
+      PROBLEMS = [:duplicate, :nonexistent, :inaccurate, :inappropriate, :spam, :other]
+      VALID_KEYS = [:table, :factual_id, :problem, :user, :comment, :debug, :reference]
+
+      def initialize(api, params)
+        validate_params(params)
+        super(api, params)
+      end
+
+      VALID_KEYS.each do |key|
+        define_method(key) do |*args|
+          Flag.new(@api, @params.merge(key => form_value(args)))
+        end
+      end
+
+      def path
+        "/t/#{@params[:table]}/#{@params[:factual_id]}/flag"
+      end
+
+      private
+
+      def validate_params(params)
+        params.keys.each do |key|
+          raise "Invalid flag option: #{key}" unless VALID_KEYS.include?(key)
+        end
+
+        unless PROBLEMS.include?(params[:problem])
+          raise "Flag problem should be one of the following: #{PROBLEMS.join(", ")}"
+        end
+      end
+    end
+  end
+end

data/lib/factual/write/submit.rb

@@ -0,0 +1,40 @@
+require 'factual/write/base'
+
+class Factual
+  module Write
+    class Submit < Base
+      VALID_KEYS = [
+        :table, :user,
+        :factual_id, :values,
+        :comment, :reference
+      ]
+
+      def initialize(api, params)
+        validate_params(params)
+        super(api, params)
+      end
+
+      VALID_KEYS.each do |key|
+        define_method(key) do |*args|
+          Submit.new(@api, @params.merge(key => form_value(args)))
+        end
+      end
+
+      def path
+        if @params[:factual_id]
+          "/t/#{@params[:table]}/#{@params[:factual_id]}/submit"
+        else
+          "/t/#{@params[:table]}/submit"
+        end
+      end
+
+      private
+
+      def validate_params(params)
+        params.keys.each do |key|
+          raise "Invalid submit option: #{key}" unless VALID_KEYS.include?(key)
+        end
+      end
+    end
+  end
+end

metadata

@@ -2,7 +2,7 @@
 name: factual-api
 version: !ruby/object:Gem::Version 
   prerelease: 
-  version: "1.1"
+  version: "1.2"
 platform: ruby
 authors: 
 - Rudiger Lippert
@@ -11,8 +11,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2012-03-30 00:00:00 +08:00
-default_executable: 
+date: 2012-06-21 00:00:00 Z
 dependencies: 
 - !ruby/object:Gem::Dependency 
   name: oauth
@@ -59,14 +58,21 @@ extra_rdoc_files: []
 
 files: 
 - lib/factual/api.rb
+- lib/factual/multi.rb
 - lib/factual/query/base.rb
 - lib/factual/query/crosswalk.rb
+- lib/factual/query/facets.rb
+- lib/factual/query/geocode.rb
+- lib/factual/query/geopulse.rb
+- lib/factual/query/monetize.rb
 - lib/factual/query/resolve.rb
 - lib/factual/query/table.rb
+- lib/factual/write/base.rb
+- lib/factual/write/flag.rb
+- lib/factual/write/submit.rb
 - lib/factual.rb
 - README.md
 - CHANGELOG.md
-has_rdoc: true
 homepage: http://github.com/Factual/factual-ruby-driver
 licenses: []
 
@@ -90,7 +96,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 
 rubyforge_project: 
-rubygems_version: 1.6.2
+rubygems_version: 1.8.24
 signing_key: 
 specification_version: 3
 summary: Ruby driver for Factual