retrieve_data: Retrieves Data from GENESIS Databases

Description

retrieve_data retrieves a single data table.

Usage

retrieve_data(
  tablename,
  startyear = "",
  endyear = "",
  regionalmerkmal = "",
  regionalschluessel = "",
  sachmerkmal = "",
  sachschluessel = "",
  sachmerkmal2 = "",
  sachschluessel2 = "",
  sachmerkmal3 = "",
  sachschluessel3 = "",
  inhalte = "",
  genesis = NULL,
  language = "de",
  ...
)

Value

a data.frame. Value variables (_val) come with three additional variables (_qual, _lock, _err). The exact nature of these variables is unknown, but _qual appears to indicate if _val is a valid value. If _qual=="e" the value in _val is valid while if _qual!="e" (then _qual = ("-","/", ".", "x", ... ) ) it is typically zero should/might be set to NA.

Arguments

tablename: name of the table to retrieve.
startyear: only retrieve values for years equal or larger to startyear. Default: "".
endyear: only retrieve values for years smaller or equal to endyear. Default: "".
regionalmerkmal: key for Regionalklassifikation. See details for more information. Default: "".
regionalschluessel: only retrieve values for particular regional units. See details for more information. Default: "".
sachmerkmal, sachmerkmal2, sachmerkmal3: key for Sachklassifikation. Default: "".
sachschluessel, sachschluessel2, sachschluessel3: value for Sachklassifikation. Default: "".
inhalte: retrieve only selected variables. Default is to retrieve all.
genesis: to authenticate a user and set the database (see below).
language: retrieve information in German "de" (default) or in English "en" if available.
...: other arguments send to the httr::GET request.

Details

Use retrieve_datalist to find the tablename based on the table series you are interested in. See the package description (wiesbaden) for details about setting the login and database.

The parameter regionalschluessel can either be a single value (a single Amtlicher Gemeindeschlüssel) or a comma-separated list of values supplied as string (no whitespaces). Wildcard character "*" is allowed. If regionalschluessel is set, the parameter regionalmerkmal must also be set to GEMEIN, KREISE, REGBEZ, or DLAND. The same logic applies to the parameter combination sachmerkmal and sachschluessel*. The parameter inhalte takes a 1-6 character long name of a variable in the table. If choosing multiple variables, delimit by ",", e.g. "STNW01,STNW02" (no whitespaces).

Limiting the data request to particular years (via the *year parameters), geographical units (via the regional* parameters) attributes (via the sach* parameters) or selected variables (via the inhalte parameter) is necessary if the API request fails to return any data. If you are not able to download the table because of size, inspect the metadata first (using retrieve_metadata or retrieve_valuelabel) and then limit the data request accordingly. See also examples below.

Examples

Run this code


 if (FALSE) {
 # Retrieve values for the table 14111KJ002 which contains the 
 # federal election results on the county level. 
 # Assumes that user/password are stored via save_credentials()

 data <- retrieve_data(tablename="14111KJ002", genesis=c(db="regio") )

 # ... only the values for the AfD. 

 data <- retrieve_data(tablename="14111KJ002", sachmerkmal="PART04", 
   sachschluessel="AFD", genesis=c(db="regio") )

# ... or only values from Saxony

 data <- retrieve_data(tablename="14111KJ002", regionalmerkmal="KREISE", 
   regionalschluessel="14*", genesis=c(db="regio") )

# Limiting the number of data points is in particular important for 
# large tables. For example, this data request fails: 

data <- retrieve_data(tablename="33111GJ005", genesis=c(db='regio'))

# But after limiting the request to one year, the data is returned:

data <- retrieve_data(tablename="33111GJ005", genesis=c(db='regio'), startyear=2019, endyear=2019)

# An alternative strategy is to only request a subset of the variables. 
# For example, this data request fails: 

data <- retrieve_data("12711GJ002", genesis=c(db="regio"))

# But when requesting only one instead of all variables, the data is returned: 

data <- retrieve_data("12711GJ002", inhalte="BEV081", genesis=c(db="regio"))

# Example using the sachschluessel: Number of refugees from Afghanistan (ST423) 
# and Egypt (ST287) by district (Kreis) in 2022. 

data <- retrieve_data("12531KJ003", startyear = 2022, endyear = 2022, 
		sachmerkmal="STAAG5", sachschluessel = "ST423, ST287", genesis=c(db='de'))

}