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",
...
)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.
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.
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
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'))
}