Learn R Programming
googlesheets (version 0.3.0)

googlesheet: Register a Google Sheet

Description

The googlesheets package must gather information on a Google Sheet from the API prior to any requests to read or write data. We call this registering the sheet and store the result in a googlesheet object. Note this object does not contain any sheet data, but rather contains metadata about the sheet. We populate a googlesheet object with information from the worksheets feed and, if available, also from the spreadsheets feed. Choose from the functions below depending on the type of sheet-identifying input you will provide. Is it a sheet title, key, browser URL, or worksheets feed (another URL, mostly used internally)?

Usage

gs_title(x, verbose = TRUE)
gs_key(x, lookup = NULL, visibility = NULL, verbose = TRUE)
gs_url(x, lookup = NULL, visibility = NULL, verbose = TRUE)
gs_ws_feed(x, lookup = NULL, verbose = TRUE)
gs_gs(x, visibility = NULL, verbose = TRUE)

Arguments

x

sheet-identifying information; a character vector of length one holding sheet title, key, browser URL or worksheets feed OR, in the case of gs_gs only, a googlesheet object

verbose

logical; do you want informative messages?

lookup

logical, optional. Controls whether googlesheets will place authorized API requests during registration. If unspecified, will be set to TRUE if authorization has previously been used in this R session, if working directory contains a file named .httr-oauth, or if x is a worksheets feed or googlesheet object that specifies "public" visibility.

visibility

character, either "public" or "private". Consulted during explicit construction of a worksheets feed from a key, which happens only when lookup = FALSE and googlesheets is prevented from looking up information in the spreadsheets feed. If unspecified, will be set to "public" if lookup = FALSE and "private" if lookup = TRUE. Consult the API docs for more info about visibility

Value

a googlesheet object

Details

A registered googlesheet will contain information on:

  • sheet_key the key of the spreadsheet

  • sheet_title the title of the spreadsheet

  • n_ws the number of worksheets contained in the spreadsheet

  • ws_feed the "worksheets feed" of the spreadsheet

  • updated the time of last update (at time of registration)

  • reg_date the time of registration

  • visibility visibility of spreadsheet (Google's confusing vocabulary); actually, does not describe a property of spreadsheet itself but rather whether requests will be made with or without authorization

  • is_public logical indicating visibility is "public" (meaning unauthenticated requests will be sent), as opposed to "private" (meaning authenticated requests will be sent)

  • author the name of the owner

  • email the email of the owner

  • links data.frame of links specific to the spreadsheet

  • ws a data.frame about the worksheets contained in the spreadsheet

A googlesheet object will contain this information from the spreadsheets feed if it was available at the time of registration:

  • alt_key alternate key; applies only to "old" sheets

Since the spreadsheets feed contains private user data, googlesheets must be properly authorized to access it. So a googlesheet object will only contain info from the spreadsheets feed if lookup = TRUE, which directs us to look up sheet-identifying information in the spreadsheets feed.