Repository files navigation

The goal of gargle is to take some of the agonizing pain out of workingwith Google APIs. This includes functions and classes for handlingcommon credential types and for preparing, executing, and processingHTTP requests.

The target user of gargle is anR package author who is wrapping oneof the ~250 Google APIs listed in theAPIsExplorer. gargle aims toplay roughly the same role asGoogle’s official clientlibraries, but forR. gargle may also be useful to useRs making direct calls to GoogleAPIs, who are prepared to navigate the details of low-level API access.

gargle’s functionality falls into two main domains:

• Auth. Thetoken_fetch() function calls a series of concretecredential-fetching functions to obtain a valid access token (or itquietly dies trying).
  • This covers explicit service accounts, application defaultcredentials, Google Compute Engine, (experimentally) workloadidentity federation, and the standard OAuth2 browser flow.
  • gargle offers theGargle2.0 class, which extendshttr::Token2.0.It is the default class for user OAuth 2.0 credentials. There aretwo main differences fromhttr::Token2.0: greater emphasis on theuser’s email (e.g. Google identity) and default token caching is atthe user level.
• Requests and responses. A family of functions helps to prepareHTTP requests, (possibly with reference to an API spec derived from aDiscovery Document), make requests, and process the response.

See thearticles for holisticadvice on how to use gargle.

You can install the released version of gargle fromCRAN with:

install.packages("gargle")

And the development version fromGitHub with:

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

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

library(gargle)token<- token_fetch()#> The gargle package is requesting access to your Google account.#> Enter '1' to start a new auth process or select a pre-authorized account.#> 1: Send me to the browser for a new auth process.#> 2: janedoe_personal@gmail.com#> 3: janedoe@example.com#> Selection: 2token#> ── <Token (via gargle)> ─────────────────────────────────────────────────────#> oauth_endpoint: google#>            app: gargle-clio#>          email: janedoe_personal@gmail.com#>         scopes: ...userinfo.email#>    credentials: access_token, expires_in, refresh_token, scope, token_type, id_token

Here’s an example of using request and response helpers to make aone-off request to theWeb Fonts DeveloperAPI. We showthe 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]sort(vapply(out,function(x)x[["family"]],character(1)))#> [1] "Inter"          "Lato"           "Material Icons" "Montserrat"#> [5] "Noto Sans JP"   "Open Sans"      "Poppins"        "Roboto"

Please note that the ‘gargle’ project is released with aContributorCode of Conduct. Bycontributing to this project, you agree to abide by its terms.

Privacy policy