Skip to content

HTTPS clone URL

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.
factual
tests
.gitignore
LICENSE.txt
MANIFEST.in
README.md
example.py
setup.py

README.md

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

This driver is supported via the Factual Developer Group

Overview

Dependencies

Requests

requests-oauth

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.

Tables

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

Setup

Obtain an OAuth key and secret from Factual

example.py 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"
factual.table("places").filters({"name":{"$bw":"starbucks"}}).data()
# Return entity names and non-blank websites from the Global dataset, for entities located in Thailand
factual.table("global").select("name,website").filters(
    {"$and":[{"country":"TH"}, {"website":{"$blank":"false"}}]}).data()
# Return highly rated U.S. restaurants in Los Angeles with WiFi
factual.table("restaurants-us").filters(
  {"$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)
query.data()
# Or specify a place with its namespace_id and namespace
SIMPLEGEO_ID = "SG_6XIEi3qehN44LH8m8i86v0"
query = factual.crosswalk().namespace('simplegeo',SIMPLEGEO_ID)
query.data()

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"})
query.data()[1]["resolved"]  # true or false
query.data()

Full Documentation

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

Something went wrong with that request. Please try again.