Skip to content
Infrastructure for calling Google APIs from R, including auth
R
Branch: master
Clone or download
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.github Refresh github community stuff Jan 30, 2019
R Continuing to truly resolve #122 Nov 14, 2019
cran-correspondence v0.3.1 accepted Jul 27, 2019
inst Secret management (#69) Apr 24, 2019
man Back to CRAN roxygen2 Oct 4, 2019
revdep use_revdep() Oct 3, 2019
tests Bump version, fortify a test Nov 14, 2019
vignettes Make clear you need to successfully authenticate interactively once Oct 14, 2019
.Rbuildignore use_revdep() Oct 3, 2019
.gitignore Secret management (#69) Apr 24, 2019
.travis.yml List R 3.4 now that 3.6 is release Apr 29, 2019
DESCRIPTION Bump version, fortify a test Nov 14, 2019
LICENSE Update year Jul 26, 2019
LICENSE.md Redo MIT license Feb 28, 2018
NAMESPACE Back to CRAN roxygen2 Oct 4, 2019
NEWS.md Fix default application credentials path (#116) Oct 27, 2019
README.Rmd Link to privacy policy Jun 8, 2019
README.md Link to privacy policy Jun 8, 2019
_pkgdown.yml Don't set pkgdown's development mode Jul 1, 2019
appveyor.yml Refactor OAuth token class and the caching strategy (#40) Nov 7, 2018
codecov.yml use_tidy_ci(), use_tidy_description() Feb 28, 2018
cran-comments.md Update cran-comments Oct 4, 2019
gargle.Rproj

README.md

gargle

CRAN status Build Status AppVeyor Build Status codecov.io lifecycle

The goal of gargle is to take some of the agonizing pain out of working with Google APIs. This includes functions and classes for handling common credential types and for preparing, executing, and processing HTTP requests.

The target user of gargle is an R package author who is wrapping one of the ~250 Google APIs listed in the APIs Explorer. gargle aims to play roughly the same role as Google’s official client libraries, but for R. gargle may also be useful to useRs making direct calls to Google APIs, who are prepared to navigate the details of low-level API access.

gargle’s functionality falls into two main domains:

  • Auth. The token_fetch() function calls a series of concrete credential-fetching functions to obtain a valid access token (or it quietly dies trying).
    • This covers explicit service accounts, application default credentials, Google Compute Engine, and the standard OAuth2 browser flow.
    • gargle offers the Gargle2.0 class, which extends httr::Token2.0. It is the default class for user OAuth 2.0 credentials. There are two main differences from httr::Token2.0: greater emphasis on the user’s email (e.g. Google identity) and default token caching is at the user level.
  • Requests and responses. A family of functions helps to prepare HTTP requests, (possibly with reference to an API spec derived from a Discovery Document), make requests, and process the response.

See the articles for holistic advice on how to use gargle.

Installation

You can install the released version of gargle from CRAN with:

install.packages("gargle")

And the development version from GitHub with:

# install.packages("devtools")
devtools::install_github("r-lib/gargle")

Basic usage

gargle is a low-level package and does not do anything visibly exciting on its own. But here’s a bit of usage in an interactive scenario where a user confirms they want to use a specific Google identity and loads an OAuth2 token.

library(gargle)

token <- token_fetch()
#> The gargle package is requesting access to your Google account. Select a
#> pre-authorised account or enter '0' to obtain a new token. Press
#> Esc/Ctrl + C to abort.

#> 1: janedoe_personal@gmail.com
#> 2: janedoe@example.com

#> Selection: 1

token
#> <Token (via gargle)>
#>   <oauth_endpoint> google
#>              <app> gargle-demo
#>            <email> janedoe_personal@gmail.com
#>           <scopes> ...userinfo.email
#>      <credentials> access_token, expires_in, refresh_token, scope, ...

Here’s an example of using request and response helpers to make a one-off request to the Web Fonts Developer API. We show the most popular web font families served by Google Fonts.

library(gargle)

req <- request_build(
  method = "GET",
  path = "webfonts/v1/webfonts",
  params = list(
    sort = "popularity"
  ),
  key = gargle_api_key(),
  base_url = "https://www.googleapis.com"
)
resp <- request_make(req)
out <- response_process(resp)

out <- out[["items"]][1:8]
vapply(out, function(x) x[["family"]], character(1))
#> [1] "Roboto"           "Open Sans"        "Lato"            
#> [4] "Montserrat"       "Roboto Condensed" "Source Sans Pro" 
#> [7] "Oswald"           "Raleway"

Please note that the ‘gargle’ project is released with a Contributor Code of Conduct. By contributing to this project, you agree to abide by its terms.

Privacy policy

You can’t perform that action at this time.