Skip to content


Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Factual's official Python driver for the Factual public API
tree: 3550f2060d

Fetching latest commit…

Cannot retrieve the latest commit at this time

Failed to load latest commit information.


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 and match it against Factual's

This driver is supported via the Factual Developer Group





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.


The Factual API is a generic API that sits over all tables available via the Factual v3 API. Some popular ones:

  • Table global for international places
  • Table restaurants-us for US restaurants only
  • Table places for US places only


Obtain an OAuth key and secret from Factual is provided with the driver as a reference.

To get started, import the Factual python driver module and create a Factual object using your OAuth key and secret.

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

Simple Read Examples

# Return entities from the Places dataset with names beginning with "starbucks"
# Return entity names and non-blank websites from the Global dataset, for entities located in Thailand
    {"$and":[{"country":"TH"}, {"website":{"$blank":"false"}}]}).data()
# Return highly rated U.S. restaurants in Los Angeles with WiFi
  {"$and":[{"locality":"los angeles"},{"rating":{"$gte":4}},{"wifi":"true"}]}).data()

Simple Crosswalk Example

# Concordance information of a place
FACTUAL_ID = "110ace9f-80a7-47d3-9170-e9317624ebd9"
query = factual.crosswalk().factual_id(FACTUAL_ID)
# Or specify a place with its namespace_id and namespace
SIMPLEGEO_ID = "SG_6XIEi3qehN44LH8m8i86v0"
query = factual.crosswalk().namespace('simplegeo',SIMPLEGEO_ID)

Simple Resolve Example

# Returns resolved entities as an array of hashes
query = factual.resolve({"name":"McDonalds","address":"10451 Santa Monica Blvd","region":"CA","postcode":"90025"})[1]["resolved"]  # true or false

Full Documentation

Full documentation is available at

Something went wrong with that request. Please try again.