Factual Blog /

Factual Ruby Driver

Factual is pleased to announce the release of a new Ruby driver for our API. The driver supports Factual’s API features, including Crosswalk, Resolve, and geo location functionality around the Factual Places API.

We put a priority on making this driver easy to use, and designed it “The Ruby Way”. It lets you focus on building your Factual queries and using the results in Ruby. It handles details like OAuth and url encoding, so you don’t have to.

The driver and its associated gems are hosted at Rubygems.org. Install the driver as a gem in your project as follows:

$ gem install factual-api

Once you have the driver installed in your Ruby project, here’s how you create an authenticated handle to Factual:

>require 'factual'
factual = Factual.new("YOUR_KEY", "YOUR_SECRET")

The driver provides a fluent interface to build Factual queries. For example, here’s how you build a query to use full text search and a geo filter to find cafes within 5,000 meters of your location, using your latitude and longitude:

search = factual.table("places").search("cafe")
places = search.geo("$circle" => {"$center" => [34.06021, -118.41828], "$meters" => 5000}).rows

A small sample of the results looks like:

 "name"=>"Gateway Cafe",
 "address"=>"1801 Avenue Of The Stars",
 "address_extended"=>"Ste B1",
 "locality"=>"Los Angeles",
 "tel"=>"(310) 551-0051",
 "category"=>"Food & Beverage",
 "name"=>"Corner Cafe and Bakery",
 "address"=>"10250 Santa Monica Blvd",
 "locality"=>"Los Angeles",
 "tel"=>"(310) 201-9648",
 "category"=>"Food & Beverage > Restaurants",
 "name"=>"Hot Oven Cafe",
 "address"=>"9705 Santa Monica Blvd",
 "locality"=>"Beverly Hills",
 "tel"=>"(310) 777-0040",
 "category"=>"Food & Beverage > Restaurants",

Some tasty data in there!

Crosswalk The Web

The driver supports Crosswalk, which makes it super easy for you to translate how Place entities are represented by 3rd party APIs and websites.

For example, here’s how you build a query to get full Crosswalk data for a specific entity in Factual’s Places dataset. Let’s say the Factual ID for a certain California Pizza Kitchen is “110ace9f-80a7-47d3-9170-e9317624ebd9”, and we want all Crosswalk data for that restaurant:


A small sample of the results looks like:


That’s a sample of 3 Crosswalk records, one per “namespace” like Yelp and Foursquare. Of course, the actual results size is much greater than what’s shown above, since Factual’s Crosswalk supports over 40 namespaces.


Resolve lets you start with incomplete data you may have for an entity, and get out the full entity data, assuming Factual is able to make a high confidence match.

For example, say you know the name of a place and some imprecise location. The Ruby driver lets you use Factual’s Resolve to get a single, high-quality match, like this:

# 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


We hope you’ll find new and interesting uses for Factual, including Crosswalk and Resolve. If you end up releasing something interesting, please let us know so we can give you a shout-out.

Complete docs on how to install and use the Ruby driver are here. The driver itself is open source. The test suite includes integration tests as well as simple demos to illustrate usage. If you have any questions or suggestions, we hope you’ll contact us through the driver’s github project.

Factual’s service is currently in Beta, and you can obtain an API key here.

Go do something great!

-Forrest, Rudy, and Aaron
Software Developers