Not Logged In

factual-api 1.6.1

This is the Factual-supported Python driver for [Factual's public API]http://developer.factual.com).

# Install

```bashpip install factual-api```

# Get Started

Include this driver in your project:```pythonfrom factual import Factualfactual = Factual('YOUR_KEY', 'YOUR_SECRET')```If you don't have a Factual API key yet, [it's free and easy to get one]https://www.factual.com/api-keys/request)

## SchemaUse the schema API call to determine which fields are available, the datatypes of those fields, and which operations (sorting, searching, writing, facetting) can be performed on each field.

# Get a row by factual id:data = factual.get_row('places', '03c26917-5d66-4de9-96bc-b13066173c65')print(data)```

## FacetsUse the facets call to get summarized counts, grouped by specified fields.

Full documentation: http://developer.factual.com/api-docs/#Facets```python# show top 5 cities that have more than 20 Starbucks in Californiadata = factual.facets('places').search('starbucks').filters({'region':'CA'}).select('locality').min_count(20).limit(5).data()print(data)```

## ResolveUse resolve to generate a confidence-based match to an existing set of place attributes.

## SubmitSubmit new data, or update existing data. Submit behaves as an "upsert", meaning that Factual will attempt to match the provided data against any existing places first. Note: you should ALWAYS store the *commit ID* returned from the response for any future support requests.

Flag a place that is a duplicate of another. The *preferred* entity that should persist is passed as a GET parameter.```pythonresp = factual.flag('us-sandbox', '4e4a14fe-988c-4f03-a8e7-0efc806d0a7f').duplicate(preferred='9d676355-6c74-4cf6-8c4a-03fdaaa2d66a').user('a_user_id').write()print(resp)```

Flag a place that is closed.```pythonresp = factual.flag('us-sandbox', '4e4a14fe-988c-4f03-a8e7-0efc806d0a7f').problem('closed').comment('was shut down when I went there yesterday.').user('a_user_id').write()print(resp)```

Flag a place that has been relocated, so that it will redirect to the new location. The *preferred* entity (the current location) is passed as a GET parameter. The old location is identified in the URL.```pythonresp = factual.flag('us-sandbox', '4e4a14fe-988c-4f03-a8e7-0efc806d0a7f').relocated(preferred='9d676355-6c74-4cf6-8c4a-03fdaaa2d66a').user('a_user_id').write()print(resp)```

## ClearThe clear API is used to signal that an existing attribute's value should be reset.

## MultiMake up to three simultaneous requests over a single HTTP connection. Note: while the requests are performed in parallel, the final response is not returned until all contained requests are complete. As such, you shouldn't use multi if you want non-blocking behavior. Also note that a contained response may include an API error message, if appropriate.

## Error HandlingThe driver may throw a `factual.api.APIException` exception for invalid requests or a more generic exception for network errors or other problems.

## Debug ModeTo see debug information about the requests being sent to Factual, you can get the url created by a query:```pythonq = factual.table('places').search('starbucks').filters({'region':'CA'}).limit(10)print(q.get_url())```

## Custom timeoutsYou can set the request timeout (in seconds):```python# set the timeout as 1 secondfactual = Factual('YOUR_KEY', 'YOUR_SECRET', timeout=1.0)````Timeout` exceptions are raised when the server does not issue a response within the specified time.

# 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 the [Factual support site]http://support.factual.com/factual)