About

This is the Factual supported Python driver for Factual's public API.

This API supports queries to Factual's Read, Schema, Crosswalk, and Resolve APIs. Full documentation is available on the Factual website:

• Read: Search the data
• Schema: Get table metadata
• Crosswalk: Get third-party IDs
• Resolve: Enrich your data with Factual places
• Match: Map your data to Factual places
• Facets: Get counts of data by facet
• Monetize: Access third-party offers
• Geopulse: Geographic context
• Geocode: Translate coordinates into addresses
• World Geographies: Administrative and natural geographies
• Submit: Submit edits to Factual's data
• Flag: Flag rows as problematic
• Diffs: Get the latest data updates

Full documentation is available at http://developer.factual.com

If you need additional support, please visit http://support.factual.com

Overview

Setup

The easiest way to get started with the driver is to install it from the Python Package Index.

pip install factual-api

Obtain an OAuth key and secret from Factual.

To use the driver in a python program, just create a Factual object using your OAuth key and secret.

from factual import Factual
factual = Factual(KEY, SECRET)

example.py is provided with the driver as a reference.

Dependencies

requests

requests_oauthlib

Basic Design

The driver allows you to create an authenticated handle to Factual. With a Factual handle, you can send queries and get results back.

Queries are created using the Factual handle, which provides a fluent interface to constructing your queries. One thing to be aware of is the behavior of the query modifier functions. These return new query instances, so base queries can be set up and then modified in different ways to produce new queries.

# Create a base search query
q = factual.table("places").search("sushi")

# Use this query with a filter
filter_query = q.filters({"website":{"$blank":False}})

# Use the same base query with select parameters (will not have website filter applied)
select_name = q.select("name")

Tables

The Factual API is a generic API that sits over all tables available via the Factual v3 API, such as places and restaurants.

Unit Tests

Unit Tests are provided to ensure the driver and OAuth are functioning as expected.
Add your Oauth credentials to tests/test_settings.py From the command line, run: python -m tests.api_test

URL Encoding

The Python driver handles URL encoding, therefore all parameters passed to the driver should be in their un-encoded form.

Simple Read Examples

# Return entities from the Places dataset where name equals "starbucks"
factual.table("places").filters({"name":"starbucks"}).data()

# Full text search for "sushi santa monica"
factual.table("places").search("sushi santa monica").data()

# Filter based on category"
factual.table("places").filters({"category":"Food & Beverage > Restaurants > Italian"}).data()

# Return entity names and non-blank websites from the Global dataset, for entities located in Thailand
factual.table("global").select("name,website").filters(
	{"country":"TH","website":{"$blank":False}}).data()

# Return highly rated restaurants in Los Angeles with WiFi
factual.table("restaurants").filters(
  {"$and":[{"locality":"los angeles"},{"rating":{"$gte":4}},{"wifi":"true"}]}).data()

Simple Crosswalk Example

Crosswalk is just a table like places or restaurants, so all of the normal table read features can be used with it.

# Get Crosswalk data using a Factual ID
FACTUAL_ID = "110ace9f-80a7-47d3-9170-e9317624ebd9"
query = factual.crosswalk().filters({'factual_id':FACTUAL_ID})
query.data()

# Get Crosswalk data using a third party namespace and namespace_id
SIMPLEGEO_ID = "SG_6XIEi3qehN44LH8m8i86v0"
query = factual.crosswalk()
namespace_query = query.filters({'namespace':'simplegeo','namespace_id':SIMPLEGEO_ID})
factual_id = namespace_query.data()[0]['factual_id']
query.filters({'factual_id':factual_id}).data()

Simple Facets Example

# Count the number of Starbucks per country
query = factual.facets("global").search("starbucks").select("country")
query.data()

More Read Examples

# 1. Specify the table Global
query = factual.table("global")

# 2. Filter results in country US
query = query.filters({"country":"US"})

# 3. Search for "sushi" or "sashimi"
query = query.search("sushi, sashimi")

# 4. Filter by geolocation
query = query.geo({"$circle":{"$center":[34.06021, -118.41828], "$meters":5000}})
# Or
from factual.utils import circle
query = query.geo(circle(34.06021, -118.41828, 5000))

# 5. Sorting
query = query.sort("name:asc")       # ascending 
query = query.sort("name:desc")      # descending

# 6. Paging
query = query.offset("20")

Read API

All Top Level Query Parameters

Parameter	Description	Example
filters	Restrict the data returned to conform to specific conditions.	query = query.filters({"name":{"$bw":"starbucks"}})
include_count	returns the total count of the number of rows in the dataset that conform to the query.	query = query.include_count(True) count = query.total_row_count()
geo	Restrict data to be returned to be within a geographical range based.	query.geo({"$circle":{"$center":[34.06021, -118.41828], "$meters":5000}})
limit	Limit the results	query = query.limit(12)
page	Limit the results to a specific "page".	query = query.page(2, :per:10)
search (across entity)	Full text search across entity	Find "sushi": query = query.search("sushi") Find "sushi" or "sashimi": query = query.search("sushi, sashimi") Find "sushi" and "santa" and "monica": query.search("sushi santa monica")
search (across field)	Full text search on specific field	query = query.filters({"name":{"$search":"cafe"}})
select	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.	query = query.select("name,address,locality,region")
sort	The field (or fields) to sort data on, as well as the direction of sort. Sorts ascending by default, but supports both explicitly sorting ascending and descending, by using sort_asc or sort_desc. Supports $distance as a sort option if a geo-filter is specified. 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. By default, any query with a full text search will be sorted by relevance. 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.	query = query.sort("name:asc") query = query.sort("$distance:asc") query = query.sort("$distance:asc,name:desc")
user	Accepts arbitrary tokens for discriminating requests across clients.	query = query.user("my username")

Row Filters

The driver supports various row filter logic. For example:

# Returns records from the Places dataset with names beginning with "starbucks"
factual.table("places").filters({"name":{"$bw":"starbucks"}}).data()

Supported row filter logic

Predicate	Description	Example
$eq	equal to	query = query.filters({"region":{"$eq":"CA"}})
$neq	not equal to	query = query.filters({"region":{"$neq":"CA"}})
search	full text search	query = query.search("sushi")
$in	equals any of	query = query.filters({"region":{"$in":["CA", "NM", "NY"]}})
$nin	does not equal any of	query = query.filters({"region":{"$nin":["CA", "NM", "NY"]}})
$bw	begins with	query = query.filters({"name":{"$bw":"starbucks"}})
$nbw	does not begin with	query = query.filters({"name":{"$nbw":"starbucks"}})
$bwin	begins with any of	query = query.filters({"name":{"$bwin":["starbucks", "coffee", "tea"]}})
$nbwin	does not begin with any of	query = query.filters({"name":{"$nbwin":["starbucks", "coffee", "tea"]}})
$includes	array includes	query = query.filters({"category_ids":{"$includes":10}})
$includes_any	array includes any of	query = query.filters({"category_ids":{"$includes_any":[10,100]}})
$blank	test to see if a value is (or is not) blank or null	query = query.filters({"tel":{"$blank":true}}) query = query.filters({"website":{"$blank":False}})
$gt	greater than	query = query.filters({"rating":{"$gt":7.5}})
$gte	greater than or equal	query = query.filters({"rating":{"$gte":7.5}})
$lt	less than	query = query.filters({"rating":{"$lt":7.5}})
$lte	less than or equal	query = query.filters({"rating":{"$lte":7.5}})

AND

Filters can be logically AND'd together. For example:

# 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:

# 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:

# (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}} ]} ]})

Raw Read

The raw read feature allows you to perform arbitrary read queries against the Factual API. This includes API features which may not have explicit driver support yet. Raw read can be used with either a URL-encoded query string or parameter dict. For example:

# url-encoded query string
response = factual.raw_read('t/places/read', 'limit=15&filters=%7B%22name%22%3A%22Starbucks%22%7D')
# parameters in a dict
response = factual.raw_read('t/places/read', {'limit':15,'filters':{"name":"Starbucks"}})

Monetize

The driver fully supports Factual's Monetize feature, which enables you to find deals for places in Factual's Global Places database. Use the Query object to specify filters on which to run the monetize request.

Simple Monetize Example

The monetize feature can be used like a normal table read. Just create the monetize query and add filters, search terms, or other constraints:

monetize = factual.monetize()
result = monetize.filters({'place_locality':'Los Angeles'}).data()

Full Documentation

Full documentation is available at http://developer.factual.com

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.