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
The easiest way to get started with the driver is to install it from the Python Package Index.
pip install factual-apiObtain 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.
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")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 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
The Python driver handles URL encoding, therefore all parameters passed to the driver should be in their un-encoded form.
# 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()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()# Count the number of Starbucks per country
query = factual.facets("global").search("starbucks").select("country")
query.data()# 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")| 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":
Find "sushi" and "santa" and "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") |
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()| 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}}) |
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}}] })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}}] })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}} ]} ]})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"}})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.
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 is available at http://developer.factual.com
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.