factual-api 1.2 → 1.3

data/CHANGELOG.md

@@ -1,3 +1,13 @@
+## v1.3
+* added diffs
+* changed raw read to get 
+* added raw post
+* moved README to wiki
+* added match
+
+## v1.2.1
+* crosswalk endpoint change
+
 ## v1.2
 * releasing geo features, facets, writes, multi and monetize
 

data/README.md

@@ -3,8 +3,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 driver is supported via the [Factual Developer Group](https://groups.google.com/group/factual_developers)
-
 # Overview
 
 ## Basic Design
@@ -24,11 +22,19 @@ Results are returned as Ruby Arrays of Hashes, where each Hash is a result recor
 
 ## Setup
 
-The driver's gems are hosted at [Rubygems.org](http://rubygems.org). You can install the factual-api gem as follows:
+The driver's gems are hosted at [Rubygems.org](http://rubygems.org). 
+
+You can install the factual-api gem as follows:
 
-`````bash
+````bash
 $ gem install factual-api
-`````
+````
+
+Or add one line to the Gemfile of your Rails project, and run `bundle`:
+
+````ruby
+gem 'factual-api'
+````
 
 Once the gem is installed, you can use it in your Ruby project like:
 
@@ -138,616 +144,6 @@ query.rows     # return many rows
 query.total_count
 ````
 
-# Read API
-
-## All Top Level Query Parameters
-
-<table>
-  <col width="33%"/>
-  <col width="33%"/>
-  <col width="33%"/>
-  <tr>
-    <th>Parameter</th>
-    <th>Description</th>
-    <th>Example</th>
-  </tr>
-  <tr>
-    <td>filters</td>
-    <td>Restrict the data returned to conform to specific conditions.</td>
-    <td><tt>query = query.filters("name" => {"$bw" => "starbucks"})</tt></td>
-  </tr>
-  <tr>
-    <td>get total row count</td>
-    <td>returns the total count of the number of rows in the dataset that conform to the query.</td>
-    <td><tt>query.total_count</tt></td>
-  </tr>
-  <tr>
-    <td>geo</td>
-    <td>Restrict data to be returned to be within a geographical range based.</td>
-    <td>(See the section on Geo Filters)</td>
-  </tr>
-  <tr>
-    <td>limit</td>
-    <td>Limit the results</td>
-    <td><tt>query = query.limit(12)</tt></td>
-  </tr>
-  <tr>
-    <td>page</td>
-    <td>Limit the results to a specific "page".</td>
-    <td><tt>query = query.page(2, :per => 10)</tt></td>
-  </tr>
-  <tr>
-    <td>search (across entity)</td>
-    <td>Full text search across entity</td>
-    <td>
-      Find "sushi":<br><tt>query = query.search("sushi")</tt><p>
-      Find "sushi" or "sashimi":<br><tt>query = query.search("sushi", "sashimi")</tt><p>
-      Find "sushi" and "santa" and "monica":<br><tt>query.search("sushi santa monica")</tt>
-    </td>
-  </tr>
-  <tr>
-    <td>search (across field)</td>
-    <td>Full text search on specific field</td>
-    <td><tt>query = query.filters({"name" => {"$search" => "cafe"}})</tt></td>
-  </tr>
-  <tr>
-    <td>select</td>
-    <td>Specifiy which fields to include in the query results.  Note that the order of fields will not necessarily be preserved in the resulting response due to the nature Hashes.</td>
-    <td><tt>query = query.select(:name, :address, :locality, :region)</tt></td>
-  </tr>
-  <tr>
-    <td>sort</td>
-    <td>The field (or fields) to sort data on, as well as the direction of sort.<p>
-        Sorts ascending by default, but supports both explicitly sorting ascending and descending, by using <tt>sort_asc</tt> or <tt>sort_desc</tt>.
-        Supports $distance as a sort option if a geo-filter is specified.<p>
-        Supports $relevance as a sort option if a full text search is specified either using the q parameter or using the $search operator in the filter parameter.<p>
-        By default, any query with a full text search will be sorted by relevance.<p>
-        Any query with a geo filter will be sorted by distance from the reference point.  If both a geo filter and full text search are present, the default will be relevance followed by distance.</td>
-    <td><tt>query = query.sort("name")</tt><br>
-    <tt>query = query.sort_desc("$distance")</tt>
-    <tt>query = query.sort_asc("name").sort_desc("rating")</tt></td>
-  </tr>
-</table>
-
-## Row Filters
-
-The driver supports various row filter logic. For example:
-
-`````ruby
-# Returns records from the Places dataset with names beginning with "starbucks"
-factual.table("places").filters("name" => {"$bw" => "starbucks"}).rows
-````
-
-### Supported row filter logic
-
-<table>
-  <tr>
-    <th>Predicate</th>
-    <th width="25%">Description</th>
-    <th>Example</th>
-  </tr>
-  <tr>
-    <td>$eq</td>
-    <td>equal to</td>
-    <td><tt>query = query.filters("region" => {"$eq" => "CA"})</tt></td>
-  </tr>
-  <tr>
-    <td>$neq</td>
-    <td>not equal to</td>
-    <td><tt>query = query.filters("region" => {"$neq" => "CA"})</tt></td>
-  </tr>
-  <tr>
-    <td>search</td>
-    <td>full text search</td>
-    <td><tt>query = query.search("sushi")</tt></td>
-  </tr>
-  <tr>
-    <td>$in</td>
-    <td>equals any of</td>
-    <td><tt>query = query.filters("region" => {"$in" => ["CA", "NM", "NY"]})</tt></td>
-  </tr>
-  <tr>
-    <td>$nin</td>
-    <td>does not equal any of</td>
-    <td><tt>query = query.filters("region" => {"$nin" => ["CA", "NM", "NY"]})</tt></td>
-  </tr>
-  <tr>
-    <td>$bw</td>
-    <td>begins with</td>
-    <td><tt>query = query.filters("name" => {"$bw" => "starbucks"})</tt></td>
-  </tr>
-  <tr>
-    <td>$nbw</td>
-    <td>does not begin with</td>
-    <td><tt>query = query.filters("name" => {"$nbw" => "starbucks"})</tt></td>
-  </tr>
-  <tr>
-    <td>$bwin</td>
-    <td>begins with any of</td>
-    <td><tt>query = query.filters("name" => {"$bwin" => ["starbucks", "coffee", "tea"]})</tt></td>
-  </tr>
-  <tr>
-    <td>$nbwin</td>
-    <td>does not begin with any of</td>
-    <td><tt>query = query.filters("name" => {"$nbwin" => ["starbucks", "coffee", "tea"]})</tt></td>
-  </tr>
-  <tr>
-    <td>$blank</td>
-    <td>test to see if a value is (or is not) blank or null</td>
-    <td><tt>query = query.filters("tel" => {"$blank" => true})</tt><br>
-        <tt>query = query.filters("website" => {"$blank" => false})</tt></td>
-  </tr>
-  <tr>
-    <td>$gt</td>
-    <td>greater than</td>
-    <td><tt>query = query.filters("rating" => {"$gt" => 7.5})</tt></td>
-  </tr>
-  <tr>
-    <td>$gte</td>
-    <td>greater than or equal</td>
-    <td><tt>query = query.filters("rating" => {"$gte" => 7.5})</tt></td>
-  </tr>
-  <tr>
-    <td>$lt</td>
-    <td>less than</td>
-    <td><tt>query = query.filters("rating" => {"$lt" => 7.5})</tt></td>
-  </tr>
-  <tr>
-    <td>$lte</td>
-    <td>less than or equal</td>
-    <td><tt>query = query.filters("rating" => {"$lte" => 7.5})</tt></td>
-  </tr>
-</table>
-
-### AND
-
-Filters can be logically AND'd together. For example:
-
-````ruby
-# name begins with "coffee" AND tel is not blank
-query = query.filters({ "$and" => [{"name" => {"$bw" => "coffee"}}, {"tel" => {"$blank" => false}}] })
-````
-
-### OR
-
-Filters can be logically OR'd. For example:
-
-````ruby
-# name begins with "coffee" OR tel is not blank
-query = query.filters({ "$or" => [{"name" => {"$bw" => "coffee"}}, {"tel" => {"$blank" => false}}] })
-````
-
-### Combined ANDs and ORs
-
-You can nest AND and OR logic to whatever level of complexity you need. For example:
-
-````ruby
-# (name begins with "Starbucks") OR (name begins with "Coffee")
-# OR
-# (name full text search matches on "tea" AND tel is not blank)
-query = query.filters({ "$or" => [ {"$or" => [ {"name" => {"$bw" => "starbucks"}},
-                                               {"name" => {"$bw" => "coffee"}}]},
-                                   {"$and" => [ {"name" => {"$search" => "tea"}},
-                                                {"tel" => {"$blank" => false}} ]} ]})
-````
-
-# Crosswalk
-
-The driver fully supports Factual's Crosswalk feature, which lets you "crosswalk" the web and relate entities between Factual's data and that of other web authorities.
-
-(See [the Crosswalk Blog](http://blog.factual.com/crosswalk-api) for more background.)
-
-## Simple Crosswalk Example
-
-````ruby
-# Get all Crosswalk data for a Place with a specific FactualID
-factual.crosswalk("110ace9f-80a7-47d3-9170-e9317624ebd9").rows
-````
-
-## Supported Crosswalk Options
-
-### only
-
-You can specify which namespaces you want, like this:
-
-````ruby
-# Get Crosswalk data for only yelp and facebook for a Place with a specific FactualID
-factual.crosswalk("110ace9f-80a7-47d3-9170-e9317624ebd9").only(:yelp, :facebook).rows
-````
-
-This will generally return 1 record per requested namespace.
-
-### limit
-
-You can limit the amount of Crosswalk results you get back, like this:
-
-````ruby
-# Get only 3 Crosswalk results for a Place with a specific FactualID
-factual.crosswalk("110ace9f-80a7-47d3-9170-e9317624ebd9").limit(3).rows
-````
-
-# Resolve
-
-The driver fully supports Factual's Resolve feature, which lets you start with incomplete data you may have for an entity, and get potential entity matches back from Factual.
-
-Each result record will include a confidence score (<tt>"similarity"</tt>), and a flag indicating whether Factual decided the entity is the correct resolved match with a high degree of accuracy (<tt>"resolved"</tt>).
-
-For any Resolve query, there will be 0 or 1 entities returned with <tt>"resolved"=true</tt>. If there was a full match, it is guaranteed to be the first record in the response Array.
-
-(See [the Resolve Blog](http://blog.factual.com/factual-resolve) for more background.)
-
-## Simple Resolve Examples
-
-````ruby
-# Returns resolved entities as an array of hashes
-query = factual.resolve("name" => "McDonalds",
-                        "address" => "10451 Santa Monica Blvd",
-                        "region" => "CA",
-                        "postcode" => "90025")
-
-query.first["resolved"] # true or false
-query.rows              # all candidate rows
-````
-
-# Geo Filters
-
-You can query Factual for entities located within a geographic area. For example:
-
-````ruby
-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:
-
-````ruby
-# Returns a hash of metadata for the table named "global", including an array of fields
-factual.table("global").schema
-````
-
-# Raw Read Queries
-
-You can perform any read queries documented in the Factual API using the
-raw read query. Just supply the full path (including the first
-forward-slash) and the request will be made using your OAuth token:
-
-````ruby
-# Find rows in the restaurant database whose name begins with "Star" and return both the data and a total count of the matched rows
-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 :debug => true as
-the third argument of the Factual constructor. Here is an example in irb:
-
-
-````ruby
-> 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:
@@ -758,3 +154,6 @@ If you think you've identified a specific bug in this driver, please file an iss
   * 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).
+
+# Ruby Driver Wiki
+https://github.com/Factual/factual-ruby-driver/wiki

data/lib/factual.rb

@@ -2,6 +2,7 @@ require 'oauth'
 require 'factual/api'
 require 'factual/query/table'
 require 'factual/query/facets'
+require 'factual/query/match'
 require 'factual/query/resolve'
 require 'factual/query/crosswalk'
 require 'factual/query/monetize'
@@ -28,9 +29,10 @@ class Factual
 
   def crosswalk(namespace_id, namespace = nil)
     if namespace
-      Query::Crosswalk.new(@api, :namespace_id => namespace_id, :namespace => namespace)
+      raise "DEPRECATED. For more information, please visit http://developer.factual.com/display/docs/Places+API+-+Crosswalk"
+      Query::Crosswalk.new(@api, :filters => {:namespace_id => namespace_id, :namespace => namespace})
     else
-      Query::Crosswalk.new(@api, :factual_id => namespace_id)
+      Query::Crosswalk.new(@api, :filters => {:factual_id => namespace_id})
     end
   end
 
@@ -38,6 +40,10 @@ class Factual
     Query::Monetize.new(@api)
   end
 
+  def match(values)
+    Query::Match.new(@api, :values => values)
+  end
+
   def resolve(values)
     Query::Resolve.new(@api, :values => values)
   end
@@ -50,8 +56,16 @@ class Factual
     Query::Geopulse.new(@api, lat, lng)
   end
 
-  def read(path)
-    @api.raw_read(path)
+  def get(path, query={})
+    @api.raw_get(path, query)
+  end
+
+  def post(path, body={})
+    @api.raw_post(path, body)
+  end
+
+  def diffs(view, params = {})
+    @api.diffs(view, params)
   end
 
   def multi(queries)

data/lib/factual/api.rb

@@ -3,7 +3,7 @@ require 'cgi'
 
 class Factual
   class API
-    VERSION = "1.2"
+    VERSION = "1.3"
     API_V3_HOST = "api.v3.factual.com"
     DRIVER_VERSION_TAG = "factual-ruby-driver-v" + VERSION
     PARAM_ALIASES = { :search => :q, :sort_asc => :sort }
@@ -29,11 +29,35 @@ class Factual
       handle_request(:schema, query.path, query.params)["view"]
     end
 
-    def raw_read(path)
-      payload = JSON.parse(make_request("http://#{@host}#{path}").body)
+    def raw_get(path, query)
+      path = '/' + path unless path =~ /^\//
+      url = "http://#{@host}#{path}?#{query_string(query)}"
+      resp = make_request(url)
+      payload = JSON.parse(resp.body)
       handle_payload(payload)
     end
 
+    def raw_post(path, body)
+      path = '/' + path unless path =~ /^\//
+      url = "http://#{@host}#{path}"
+      resp = make_request(url, query_string(body), :post)
+      payload = JSON.parse(resp.body)
+      handle_payload(payload)
+    end
+
+    def diffs(view_id, params = {})
+      start_date = (params[:start] || params["start"] || 0).to_i * 1000
+      end_date = (params[:end] || params["end"] || Time.now).to_i * 1000
+
+      path = "/t/#{view_id}/diffs?start=#{start_date}&end=#{end_date}"
+      url = "http://#{@host}#{path}"
+      resp = make_request(url)
+
+      resp.body.split("\n").collect do |rowJson|
+        row = JSON.parse(rowJson)
+      end
+    end
+
     def full_path(action, path, params)
       fp = "/#{path}"
       fp += "/#{action}" unless action == :read

data/lib/factual/query/crosswalk.rb

@@ -4,12 +4,24 @@ class Factual
   module Query
     class Crosswalk < Base
       def initialize(api, params = {})
-        @path = "places/crosswalk"
+        @path = "t/crosswalk"
         @action = :read
         super(api, params)
       end
 
-      [:factual_id, :only, :limit, :include_count].each do |param|
+      def only(*namespaces)
+        filters = @params[:filters] ? @params[:filters].dup : {}
+
+        if (namespaces.length == 1)
+          filters.merge!(:namespace => namespaces.first)
+        else
+          filters.merge!(:namespace => {"$in" => namespaces})
+        end
+
+        self.class.new(@api, @params.merge(:filters => filters))
+      end
+
+      [:limit, :include_count].each do |param|
         define_method(param) do |*args|
           self.class.new(@api, @params.merge(param => form_value(args)))
         end

data/lib/factual/query/match.rb

@@ -0,0 +1,19 @@
+require 'factual/query/base'
+
+class Factual
+  module Query
+    class Match < Base
+      def initialize(api, params = {})
+        @path = "places/match"
+        @action = :read
+        super(api, params)
+      end
+
+      [:values].each do |param|
+        define_method(param) do |*args|
+          self.class.new(@api, @params.merge(param => form_value(args)))
+        end
+      end
+    end
+  end
+end

metadata

@@ -1,62 +1,73 @@
---- !ruby/object:Gem::Specification 
+--- !ruby/object:Gem::Specification
 name: factual-api
-version: !ruby/object:Gem::Version 
+version: !ruby/object:Gem::Version
+  version: '1.3'
   prerelease: 
-  version: "1.2"
 platform: ruby
-authors: 
+authors:
 - Rudiger Lippert
 - Forrest Cao
 autorequire: 
 bindir: bin
 cert_chain: []
-
-date: 2012-06-21 00:00:00 Z
-dependencies: 
-- !ruby/object:Gem::Dependency 
+date: 2012-08-08 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
   name: oauth
-  prerelease: false
-  requirement: &id001 !ruby/object:Gem::Requirement 
+  requirement: !ruby/object:Gem::Requirement
     none: false
-    requirements: 
-    - - ">="
-      - !ruby/object:Gem::Version 
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
         version: 0.4.4
   type: :runtime
-  version_requirements: *id001
-- !ruby/object:Gem::Dependency 
-  name: json
   prerelease: false
-  requirement: &id002 !ruby/object:Gem::Requirement 
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: 0.4.4
+- !ruby/object:Gem::Dependency
+  name: json
+  requirement: !ruby/object:Gem::Requirement
     none: false
-    requirements: 
-    - - ">="
-      - !ruby/object:Gem::Version 
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
         version: 1.2.0
   type: :runtime
-  version_requirements: *id002
-- !ruby/object:Gem::Dependency 
-  name: rspec
   prerelease: false
-  requirement: &id003 !ruby/object:Gem::Requirement 
+  version_requirements: !ruby/object:Gem::Requirement
     none: false
-    requirements: 
-    - - ">="
-      - !ruby/object:Gem::Version 
-        version: "0"
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: 1.2.0
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
   type: :development
-  version_requirements: *id003
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
 description: Factual's official Ruby driver for the Factual public API.
-email: 
+email:
 - rudy@factual.com
 - forrest@factual.com
 executables: []
-
 extensions: []
-
 extra_rdoc_files: []
-
-files: 
+files:
 - lib/factual/api.rb
 - lib/factual/multi.rb
 - lib/factual/query/base.rb
@@ -64,6 +75,7 @@ files:
 - lib/factual/query/facets.rb
 - lib/factual/query/geocode.rb
 - lib/factual/query/geopulse.rb
+- lib/factual/query/match.rb
 - lib/factual/query/monetize.rb
 - lib/factual/query/resolve.rb
 - lib/factual/query/table.rb
@@ -75,30 +87,26 @@ files:
 - CHANGELOG.md
 homepage: http://github.com/Factual/factual-ruby-driver
 licenses: []
-
 post_install_message: 
 rdoc_options: []
-
-require_paths: 
+require_paths:
 - lib
-required_ruby_version: !ruby/object:Gem::Requirement 
+required_ruby_version: !ruby/object:Gem::Requirement
   none: false
-  requirements: 
-  - - ">="
-    - !ruby/object:Gem::Version 
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
       version: 1.8.6
-required_rubygems_version: !ruby/object:Gem::Requirement 
+required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
-  requirements: 
-  - - ">="
-    - !ruby/object:Gem::Version 
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
       version: 1.3.6
 requirements: []
-
 rubyforge_project: 
 rubygems_version: 1.8.24
 signing_key: 
 specification_version: 3
 summary: Ruby driver for Factual
 test_files: []
-