Get Data From Trello API

Fetch resources using Trello API.

Usage

get_resource(
  parent = NULL,
  child = NULL,
  id = NULL,
  token = NULL,
  query = NULL,
  url = NULL,
  filter = NULL,
  limit = 100,
  on.error = c("stop", "warn", "message"),
  retry.times = 1,
  handle = NULL,
  verbose = FALSE,
  response,
  paging,
  bind.rows
)

Arguments

parent

Parent resource, e.g. "board" or NULL.

child

Child resource, eg. "card" or NULL.

id

Resource ID or NULL.

token

An object of class "Trello_API_token", a path or NULL.

If a Token, it is passed as is.
If NULL and a cache file called ".httr-oauth" exists, the newest token is read from it. If the file is not found, an error is thrown.
If a character vector of length 1, it will be used as an alternative path to the cache file.

query

Named list of key-value pairs, see httr::GET() for details.

url

Url for the GET request. Can be NULL if parent is specified, or a combination of parent, child and id is provided.

filter

Defaults to "all" which includes both open and archived cards or all action types, depending on what resource is requested.

limit

Defaults to 100. Set to Inf to get everything.

on.error

Whether to "stop", "warn" or "message" on API error.

retry.times

How many times to re-try when a request fails. Defaults to 1.

handle

The handle to use with this request, see httr::RETRY().

verbose

Set to TRUE for verbose output.

response, paging, bind.rows

Deprecated.

Value

A data frame with API responses.

Request limits

At maximum, the API can retrieve 1000 results in a single call. Setting limit > 1000 will activate paging. When paging is used, the request will be issued repeatedly, retrieving new batch of results each time until the limit is reached or there is nothing else to fetch. Results are fetched chronologically, ie. newest results are retrieved first (eg. newest cards). Use limit = Inf to make sure you get all.

Errors

If the request fails, server error messages are reprinted on the console. Depending on the value of on.error, the request call can throw an error in R (this is the default), or can issue a warning/message. If the latter, the function returns a data frame containing the failed URL, HTTP status and an informative message (produced by the server).

Results

The API returns JSON objects which are parsed using jsonlite::fromJSON(). Non-JSON results throw an error, but these should never happen anyway. The result is always a data frame, or a tibble if the package is installed.

Filter

Both filter and limit exist as explicitly defined arguments, but you can ignore them in favor of supplying their values as query parameters, eg. query = list(filter = "filter_value", limit = "limit_value").

Examples


# Public boards can be accessed without authorization, so there is no need
# to create a token, just the board id:
url = "https://trello.com/b/wVWPK9I4/r-client-for-the-trello-api"
bid = get_id_board(url)
#> GET: https://api.trello.com/1/board/wVWPK9I4?fields=name&limit=100
#> 
  |                                                                            
  |                                                                      |   0%
  |                                                                            
  |======================================================================| 100%
#> OK (HTTP 200).

# Getting resources from the whole board. `filter="all"` fetches archived
# cards as well.
labels = get_board_labels(bid)
#> GET: https://api.trello.com/1/board/600f54e86a3733550971ed4a/labels?limit=100
#> 
  |                                                                            
  |                                                                      |   0%
  |                                                                            
  |======================================================================| 100%
#> OK (HTTP 200).
#> 
#> Fetched 6 results
#> 
#> Request complete: 6 results.
cards = get_board_cards(bid, filter = "all")
#> GET: https://api.trello.com/1/board/600f54e86a3733550971ed4a/cards?limit=100&filter=all
#> 
Downloading: 3 kB     
Downloading: 3 kB     
Downloading: 3 kB     
Downloading: 3 kB     
#> OK (HTTP 200).
#> 
#> Fetched 11 results
#> 
#> Request complete: 11 results.

# It is possible to call `get_resource()` directly:
lists = get_resource(parent = "board", child = "lists", id = bid)
#> GET: https://api.trello.com/1/board/600f54e86a3733550971ed4a/lists?limit=100
#> 
  |                                                                            
  |                                                                      |   0%
  |                                                                            
  |======================================================================| 100%
#> OK (HTTP 200).
#> 
#> Fetched 3 results
#> 
#> Request complete: 3 results.

# As with boards, cards can be queried for particular resources, in this case
# to obtain custom fields:
card = cards$id[5]
acts = get_card_fields(card)
#> GET: https://api.trello.com/1/card/600f54e86a3733550971ed69/customFields?limit=100
#> 
  |                                                                            
  |                                                                      |   0%
  |                                                                            
  |======================================================================| 100%
#> OK (HTTP 200).
#> 
#> Fetched 5 results
#> 
#> Request complete: 5 results.

# Set `limit` to specify the number of results. Pagination will be used
# whenever limit exceeds 1000. Use `limit=Inf` to make sure you get all.

if (FALSE) {
all_actions = get_board_actions(bid, limit = Inf)
}

# For private and team boards, a secure token is required:

if (FALSE) {
key = Sys.getenv("MY_TRELLO_KEY")
secret = Sys.getenv("MY_TRELLO_SECRET")

token = get_token("my_app", key = key, secret = secret,
                  scope = c("read", "write"))

# Token is now cached, no need to pass it explicitly.
cards_open = get_board_cards(board_id, filter = "open")
}