Metadata-Version: 1.0
Name: factual-api
Version: 1.1.0
Summary: Official Python driver for the Factual public API
Home-page: http://github.com/Factual/factual-python-driver
Author: Factual Driver Team
Author-email: UNKNOWN
License: Apache License
Description: # About
        
        This is the Factual supported Python driver for [Factual's public API](http://developer.factual.com/display/docs/Factual+Developer+APIs+Version+3).
        
        
        This API supports queries to Factual's Read, Schema, Crosswalk, and Resolve APIs. Full documentation is available on the Factual website:
        
        *   [Read](http://developer.factual.com/display/docs/Factual+Developer+APIs+Version+3): Search the data
        *   [Schema](http://developer.factual.com/display/docs/Core+API+-+Schema): Get table metadata
        *   [Crosswalk](http://developer.factual.com/display/docs/Places+API+-+Crosswalk): Get third-party IDs
        *   [Resolve](http://developer.factual.com/display/docs/Places+API+-+Resolve): Enrich your data and match it against Factual's
        
        This driver is supported via the [Factual Developer Group](https://groups.google.com/group/factual_developers)
        
        ### Warning
        The driver also contains support for Contribute and Flag requests which are not yet available through the Factual public API.  These API features will be enabled in the near future.
        
        # Overview
        
        
        ## Dependencies
        [Requests](http://docs.python-requests.org/en/v0.10.7/index.html)
        
        [requests-oauth](https://github.com/maraujop/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 <tt>global</tt> for international places
        *   Table <tt>restaurants-us</tt> for US restaurants only
        *   Table <tt>places</tt> for US places only
        
        ## Setup
        Obtain an OAuth key and secret from [Factual](http://www.factual.com/devtools/beta)
        
        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.
        
        ````python
        from factual import *
        factual = Factual(KEY, SECRET)
        ````
        
        
        ## Simple Read Examples
        
        `````python
        # Return entities from the Places dataset with names beginning with "starbucks"
        factual.table("places").filters({"name":{"$bw":"starbucks"}}).data()
        ````
        
        `````python
        # 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()
        ````
        
        `````python
        # 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
        
        ````python
        # Concordance information of a place
        FACTUAL_ID = "110ace9f-80a7-47d3-9170-e9317624ebd9"
        query = factual.crosswalk().factual_id(FACTUAL_ID)
        query.data()
        ````
        
        ````python
        # 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
        
        ````python
        # 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
        
Keywords: factual
Platform: UNKNOWN
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python
Classifier: Operating System :: OS Independent
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Software Development :: Libraries :: Python Modules
