restatis

{restatis} is a wrapper around the RESTful APIs that provide accessto the three main databases of German official statistics:

• TheGENESIS database of the Federal Statistical Office of Germany(Destatis),
• regionalstatistik.de which is the database of the German Länder(Regionaldatenbank),
• Thedatabase of theGerman 2022 Census (Zensus2022).

Almost all functions work on either one of them, on all of them or juston a selection.

Current (known) performance issues

• The functiongen_download_job currently does not work in the CRANrelease version for the GENESIS database. This is because the mode ofdownloading the tables has changed. A fix has been deployed to thedevelopment version and will be coming with the next CRAN update.
• It might be that the creation of jobs withgen_table is currentlybuggy in the release version (jobs not being created despite ofjob = TRUE). A fix has been deployed to the development version andwill be coming with the next CRAN update.

Installation

You can install the released version of{restatis} from CRAN:

install.packages("restatis")

Or install a development version of{restatis} fromGitHub with:

# install.packages("devtools")devtools::install_github("CorrelAid/restatis")

Usage

Authentication

To access each one of the APIs, you need to have an account that you cancreate on the homepage (see links to them above) and store your usernameand password for use in R withrestatis::gen_auth_save() (see?gen_auth_save for more details).

Note: The GENESIS and Zensus 2022 databases do supportauthentication with an API token as well. You can set the token ascredential by using setting the parameteruse_token = TRUE forrestatis::gen_auth_save(). The token itself can be found when logginginto the respective webpage with your account and by clicking onWebservice (API) (EN) orWebservice-Schnittstelle (API) (DE) in thebottom left corner.Important: The GENESIS database will not let youcreate jobs when using API tokens to authenticate. This is why{restatis} will check your credential type once you setjob = TRUEforgen_table() and error in case a token is used. To enable the useof jobs, usegen_auth_save() and input your username and password (bysettinguse_token = FALSE).

Main features

{restatis} provides functions (prefixed withgen_) for finding,exploring, and retrieving data from the three supported APIs. See the“Basic restatis workflow”vignettefor an overview of the main features of the package.

In short, there are functions divided in two main parts, searching for(meta)data and retrieving data:

Searching for (meta)data

• gen_catalogue(): Search the API’s catalogue of data
• gen_find(): Find objects related to a search term
• gen_metadata(): Find meta data to an objects
• gen_alternative_terms(): Find alternative terms to a search term
• gen_modified_data(): Find out when an object has last beenmodified
• gen_objects2stat(),gen_objects2var(),gen_var2stat(),gen_val2var(),gen_val2var2stat() andgen_search_vars():Find objects, statistics, variables and values related to each other

Retrieving data

• gen_cube(): Using this function, you can download ‘cube’ objects
• gen_table(): Using this function, you can download ‘table’ objects
• gen_list_jobs() andgen_download_job(): Using this function,you can find and download previously created jobs (large tables)

Other functions

• gen_logincheck(): Perform a logincheck to test your credentials
• gen_signs(): Get a list of quality signs (special characters)found in the API’s tables
• gen_update_evas(): Manually scrape a newer version of the EVASnumbers (official statistic IDs)

Caching

{restatis} usesmemoisation tocache query results. This means that if you call a function multipletimes with the same exact input, the values returned the first time arestored and reused from the second time on. Cached objects are stored inmemory and do not persist across R sessions. With version 0.3.0, we haveenabled users to turn off caching. The caching option is set to TRUE bydefault and can be changed by settingoptions(restatis.use_cache = TRUE) (orFALSE, respectively). You canget the current state of the option by usinggetOption("restatis.use_cache").Note: Memoisation isnever usedfor the functionsgen_list_jobs() andgen_logincheck() because thereis no use-case for a cached version of the results of these functions(e.g., login checks should always be executed when called).

Disclaimer

This package is in no way affiliated with the German Federal StatisticalOffice (Destatis) or the ‘Verbund Statistische Ämter des Bundes und derLänder’. It is a simple wrapper providing R functions to accessdifferent official statistics APIs. The package authors are in no wayresponsible for the data that can be retrieved using its functions anddo not provide support for any problems arising from the APIs’functionality itself. Conversely, support for problems related to thispackage isexclusively provided by the package authors. The licenseof this package solely applies to its source code.