Skip to contents

Download survey data

Source: R/gesis_data.R
gesis_data.Rd

Downloads survey data from GESIS given a record or a dataset ID. To download data, the session must be authenticated using gesis_auth.

Usage

gesis_data(
  record,
  download_purpose = NULL,
  path = tempdir(),
  type = "dataset",
  select = NULL,
  prompt = interactive()
)

Arguments

record

Object of class gesis_record as returned by gesis_search and gesis_get or dataset ID. If a dataset ID is passed, the function performs a call to gesis_get.

download_purpose

Purpose for the use of the research data as demanded by GESIS. Must be one of "final_thesis", "commercial_research", "non_scientific", "further_education", "scientific_research", "studies", or "lecturer".

path

Path where the downloaded file should be stored. Can be path to a directory or a file. If a directory path, it is attempted to infer the file name from the file to be downloaded. If this is not possible, the file is stored in a file called gesis with no file extension. If a file path is passed, the file is directly downloaded to this path. Defaults to a temporary directory path.

type

Type of data to download. Must be one of "dataset", "questionnaire", "codebook", "otherdocs", or "uncategorized". A file type is "uncategorized" if it is falls under none of the other file types. Defaults to "dataset". A list of available data types for a given record can be retrieved using gesis_file_types.

select

Character string to select a data file in case multiple files are available for the selected data type. The character string is matched against the file label using regular expressions. This argument can also be used to match explicitly for file extensions, e.g. "\\.sav" or "\\.dat". A list of file labels for a given record can be retrieved using gesis_files. If NULL, multiple files are detected, and the session is interactive, prompts the user to select a file. Defaults to NULL.

prompt

If TRUE, allows the function to open an interactive prompt in case multiple files are found and select is either NULL or fails to select a file unambiguously. If FALSE, throws an error in such a case. Defaults to TRUE if run in an interactive session.

Value

The path to the downloaded file. Depending on the selected file, there are different ways to read the file contents. Traditionally, data files are offered in Stata and SPSS file formats and can be read using the haven package.

Details

Access and refresh tokens are automatically attached to the requests sent if possible. This is done only for URLs pointing to the domain gesis.org to avoid sending authentication information to other domains.

Examples

if (FALSE) { # \dontrun{
# retrieve a search record to pass on to gesis_data()
record <- gesis_search(
  "allbus",
  publication_year = c(2019, 2020),
  type = "research_data"
)

# in interactive mode, the function can be run without arguments
path <- gesis_data(record[[1]])

# in other cases, certain arguments should be provided
path <- gesis_data(record[[1]], download_purpose = "non_scientific", select = "\\.sav")

# you can also simply pass a dataset ID
path <- gesis_data("ZA3753", select = "\\.por")

# data files must be read using other tools and packages, e.g. haven
haven::read_por(path)

# ... or pdftools
path <- gesis_data("ZA3753", select = "fb\\.pdf", type = "questionnaire")
pdftools::pdf_text(path)
} # }