factualR: common functions in the factualR package
In factualR: thin wrapper for the Factual.com server API

Description Usage Arguments Details Author(s) References Examples

This document describes the end-user functions for the factualR package.

Please note: as this package is a thin wrapper around the Factual.com API, you will need a Factual API Key. You can sign up for one at http://www.factual.com/.

For now, this package supports read-only requests ("read" and "schema"); a future revision may support modification of Factual.com data ("input" API calls).

createFactualConnection( apiKey = NULL , apiVersion = NULL , baseURL = NULL )

factualGetSchema( connection , tableID , verbose = FALSE )

factualRead(connection , tableID , sort = NULL , limit = NULL , offset = NULL , filters = NULL , subject_key = NULL , reformatNames , verbose = FALSE )

`apiKey`	your "Factual API key" as acquired from `http://www.factual.com/`.
`apiVersion`	the version of the Factual.com API. Unless you are a developer on factualR, you needn't specify this parameter.
`baseURL`	the base URL for calls to Factual.com. Unless you are a developer on factualR, you needn't specify this parameter.
`connection`	a connection as returned from `createFactualConnection()`.
`tableID`	the table's unique identifier, sometimes called "table reference," from Factual.com.
`sort`	sort field(s), using JSON syntax. factualR will URL-encode this string for you.
`limit`	maximum number of records (rows) to pull from this table.
`offset`	start pulling records (rows) from this numeric offset.
`filters`	limit records (rows) based on these criteria, in JSON format. factualR will URL-encode this string for you.
`subject_key`	unique identifier for a row. (If you're exporting several rows, e.g. for an analysis, you probably won't use this.)
`reformatNames`	whether to reformat column names to be more R-friendly (e.g., remove all but alphanumeric characters).
`verbose`	should we show debugging information, such as the URL, during processing? (Useful for debugging.)

For a description of the filters and sort filters, please refer to the Factual.com developer documentation at: http://wiki.developer.factual.com/w/page/29670788/Server-API.

Note that factualR will URL-encode all parameters for you; please don't URL-encode any of the values passed to factualGetSchema or factualRead.

Under some circumstances, a call to factualRead() or factualGetSchema() will fail in a way that does not return an object. When that happens, please rerun the call using verbose=TRUE to print the target URL. If you paste that into a browser or a commandline tool such as curl, you can determine whether there is a connectivity problem to Factual.com.

Ethan McCallum

The main http://www.factual.com/ website explains Factual's mission.

http://www.factual.com/devtools/serverAPI explains the REST API used by factualR, including the (optional) filters and sort parameters used by factualRead.

Finally, http://wiki.developer.factual.com/w/page/12298839/Basics explains more about the elements common to all responses from the API, such as status and message.

## Not run: 
## make sure you have signed up for a developer API key at http://www.factual.com/

myAPIKey <- " ... YOUR Factual.com API KEY"

factual <- createFactualConnection( myAPIKey )

## Skim http://www.factual.com/topics for an interesting table.  Click the table's
## link and then click the "develop" tab.  Note the "table reference."
tableID <- "... table reference from the table's 'Develop' tab ..."

## now, let's get an idea of the table's schema and metadata:
table.meta <- factualGetSchema( factual , tableID )

str(table.meta)

## with that in mind, get the table's data
table.data <- factualRead( factual , tableID )

## get an idea of the result object
str(table.data)

## that's great, but we really want to play with the table data
## (it's a data frame)
table.data@results


## hm, let's get 60 rows so we can explore
table.data.small <- factualRead( factual , tableID , limit=60 )

str(table.data.small@results)


## let's use some filters to limit the data we pull.
## pretend the table of interest has colums named "state"
## and "city"
filters <- '{"city":"New York","state":"NY"}'

table.data.filtered <- factualRead( factual , tableID , filters = filters )
str(table.data.small@filtered)

## End(Not run)