Read data

This function reads data from a worksheet and returns a data frame. It wraps up the most common usage of other, lower-level functions for data consumption and transformation, but you can call always call them directly for finer control.

gs_read(ss, ws = 1, range = NULL, literal = TRUE, ..., verbose = TRUE)

a registered Google spreadsheet, i.e. a googlesheet object


positive integer or character string specifying index or title, respectively, of the worksheet


a cell range, as described in cell-specification


logical, indicating whether to work only with literal values returned by the API or to consult alternate cell contents


Optional arguments to control data download, parsing, and reshaping; for most purposes, the defaults should be fine. Anything that is not listed here will be silently ignored.


Logical. Whether to display download progress if in an interactive session.


Seize control of type conversion for variables. Passed straight through to readr::read_csv or readr::type_convert. Follow those links or read the vignette("column-types") for details.

locale, trim_ws, na

Specify locale, the fate of leading or trailing whitespace, or a character vector of strings that should become missing values. Passed straight through to readr::read_csv or readr::type_convert.

comment, skip, n_max

Specify a string used to identify comments, request to skip lines before reading data, or specify the maximum number of data rows to read.


Either TRUE, FALSE or a character vector of column names. If TRUE, the first row of the data rectangle will be used for names. If FALSE, column names will be X1, X2, etc. If a character vector, it will be used as column names. If the sheet contains column names and you just don't like them, specify skip = 1 so they don't show up in your data.


Logical. Whether to run column names through make.names with unique = TRUE, just like read.table does. By default, googlesheets implements the readr data ingest philosophy, which leaves column names "as is", with one exception: data frames returned by googlesheets will have a name for each variable, even if we have to create one.


logical; do you want informative messages?


If the range argument is not specified and literal = TRUE, all data will be read via gs_read_csv. Don't worry -- no intermediate *.csv files are written! We just request the data from the Sheets API via the exportcsv link.

If the range argument is specified or if literal = FALSE, data will be read for the targetted cells via gs_read_cellfeed, then reshaped and type converted with gs_reshape_cellfeed. See gs_reshape_cellfeed for details.


a data.frame or, if dplyr is loaded, a tbl_df

See Also

The cell-specification topic for more about targetting specific cells.

Other data consumption functions: gs_read_cellfeed, gs_read_csv, gs_read_listfeed, gs_reshape_cellfeed, gs_simplify_cellfeed

  • gs_read
gap_ss <- gs_gap()
oceania_csv <- gs_read(gap_ss, ws = "Oceania")

gs_read(gap_ss, ws = "Europe", n_max = 4, col_types = c("cccccc"))

gs_read(gap_ss, ws = "Oceania", range = "A1:C4")
gs_read(gap_ss, ws = "Oceania", range = "R1C1:R4C3")
gs_read(gap_ss, ws = "Oceania", range = "R2C1:R4C3", col_names = FALSE)
gs_read(gap_ss, ws = "Oceania", range = "R2C5:R4C6",
        col_names = c("thing_one", "thing_two"))
gs_read(gap_ss, ws = "Oceania", range = cell_limits(c(1, 3), c(1, 4)),
        col_names = FALSE)
gs_read(gap_ss, ws = "Oceania", range = cell_rows(1:5))
gs_read(gap_ss, ws = "Oceania", range = cell_cols(4:6))
gs_read(gap_ss, ws = "Oceania", range = cell_cols("A:D"))

ff_ss <- gs_ff() # register example sheet with formulas and formatted nums
gs_read(ff_ss)                  # almost all vars are character
gs_read(ff_ss, literal = FALSE) # more vars are properly numeric
# }
# }
Documentation reproduced from package googlesheets, version 0.3.0, License: MIT + file LICENSE

Community examples

Looks like there are no examples yet.