enigma_fetch: Download a gzipped csv file of a dataset.

In ropengov/enigma: Client for the 'Enigma' 'API'

Description

Download a gzipped csv file of a dataset.

Usage

enigma_fetch(dataset = NULL, select = NULL, search = NULL, where = NULL,
  conjunction = NULL, sort = NULL, path = NULL, key = NULL,
  poll_sleep = 0, ...)

enigma_read(input)

Arguments

dataset	Dataset name. Required.
select	(character) Vector of columns to be returned with each row. Default is to return all columns.
search	(character) Filter results by only returning rows that match a search query. By default this searches the entire table for matching text. To search particular fields only, use the query format "@fieldname query". To match multiple queries, the | (or) operator can be used eg. "query1|query2".
where	(character) Filter results with a SQL-style "where" clause. Only applies to numerical columns - use the search parameter for strings. Valid operators are >, < and =. Only one where clause per request is currently supported.
conjunction	one of "and" or "or". Only applicable when more than one search or where parameter is provided. Default: "and"
sort	(character) Sort rows by a particular column in a given direction. + denotes ascending order, - denotes descending. See examples.
path	File name and path of output zip file. Defaults to write a zip file to your home directory with name of the dataset, and file extension .csv.gz.
key	(character) Required. An Enigma API key. Supply in the function call, or store in your .Renviron file like ENIGMA_KEY=your key), or in your .Rprofile file as options(enigmaKey = "<your key>"), Obtain an API key by creating an account with Enigma at http://enigma.io, then obtain an API key from your account page.
poll_sleep	(integer) Time to sleep between polling events to fetch data. For very large datasets, it could take a while to be ready. By default, we poll continuously. If you are requesting a large dataset and/or have not much left on your allowed requests with Enigam (see rate_limit) you may want to insert some sleep time between pollings.
...	Named curl options passed on to HttpClient
input	The output from enigma_fetch or a path to a file d ownloaded from Enigma.io

Details

Note that enigma_fetch downloads the file, and gives back a path to the file. In a separte function, enigma_read, you can read in the data. enigma_fetch doesn't read in data in case the file is very large which may make your R session crash or slow down significantly.

This function makes a request to ask Enigma to get a download ready. We then poll the provided URL from Enigma until it is ready. Once ready we fetch it and write it to disk.

If file exists already, we overwrite it.

Value

A (character) path to the file on your machine

References

https://app.enigma.io/api#exporting

Examples

## Not run: 
## After obtaining an API key from Enigma's website, pass in your key to 
## the function call or set in your options (see above instructions for the 
## key parameter) If you pass in your key to the function call use the 
## key parameter

# Fetch a dataset
res <- enigma_fetch('org.un.comtrade.1')
enigma_read(res)

# Use the select parameter to limit fields returned
res <- enigma_fetch('org.un.comtrade.1',
   select = c("country_area", "year", "flow", "trade_usd"))
enigma_read(res)

# Use the search parameter to query entire table or particular fields
res <- enigma_fetch('org.un.comtrade.1', search = "export")
enigma_read(res)

# Use the search parameter to query entire table or particular fields
res <- enigma_fetch(dataset = 'org.un.comtrade.1',
   where = "trade_usd > 90000000", 
   select = c("country_area", "year", "trade_usd"))
enigma_read(res)

## End(Not run)

ropengov/enigma documentation built on May 27, 2019, 1:51 p.m.