Merge 0.4.0 dev into main

.github/workflows/test-coverage.yaml

@@ -2,7 +2,7 @@
 # Need help debugging build failures? Start at https://github.com/r-lib/actions#where-to-find-help
 on:
   push:
-    branches: [main, master]
+    branches: [main, dev]
   pull_request:
 
 name: test-coverage.yaml
@@ -29,20 +29,22 @@ jobs:
 
       - name: Test coverage
         run: |
+          Sys.setenv(NOT_CRAN = "true")
           cov <- covr::package_coverage(
             quiet = FALSE,
             clean = FALSE,
             install_path = file.path(normalizePath(Sys.getenv("RUNNER_TEMP"), winslash = "/"), "package")
           )
+          print(cov)
           covr::to_cobertura(cov)
         shell: Rscript {0}
 
-      - uses: codecov/codecov-action@v4
+      - uses: codecov/codecov-action@v5
         with:
           # Fail if error if not on PR, or if on PR and token is given
           fail_ci_if_error: ${{ github.event_name != 'pull_request' || secrets.CODECOV_TOKEN }}
-          file: ./cobertura.xml
-          plugin: noop
+          files: ./cobertura.xml
+          plugins: noop
           disable_search: true
           token: ${{ secrets.CODECOV_TOKEN }}
 

DESCRIPTION

@@ -2,19 +2,19 @@ Package: restatis
 Title: R Wrapper to Access a Wide Range of Germany's Federal Statistical System 
     Databases Based on the GENESIS Web Service RESTful API of the German Federal 
     Statistical Office (Statistisches Bundesamt/Destatis)
-Version: 0.3.0
+Version: 0.4.0
 Authors@R: c(
     person("Yannik", "Buhl", , "ybuhl@posteo.de", role = c("aut", "cre")),
     person("Zoran", "Kovacevic", role = "aut",
            comment = c(ORCID = "0009-0002-0156-0862")),
     person("Dorian", "Le Jeune", role = "aut"),
     person("Long", "Nguyen", , "long.nguyen@uni-bielefeld.de", role = "aut",
            comment = c(ORCID = "0000-0001-8878-7386")),
-    person("Johannes", "Ritter", , "ritter.johannes@gmail.com", role = "aut")
+    person("Johannes", "Ritter", , "ritter.johannes@gmail.com", role = "aut"),
+    person("Stefan", "Linner", , "stefan@linnerprogramming.com", role = "ctb")
   )
-Description: A RESTful API wrapper for accessing the GENESIS database of
-    the German Federal Statistical Office (Destatis) as well as its Census 
-    Database and the database of Germany's regional statistics. Supports data 
+Description: A RESTful API wrapper for accessing the main databases of
+    Germany's Federal Statistical System. Supports data 
     search functions, credential management, result caching, and handling 
     remote background jobs for large datasets.
 License: MIT + file LICENSE
@@ -34,16 +34,16 @@ Imports:
     purrr
 Suggests: 
     httptest2,
-    knitr,
+    quarto,
     rmarkdown,
     testthat (>= 3.0.0),
     rvest,
     usethis,
     withr
 VignetteBuilder: 
-    knitr
+    quarto
 Config/testthat/edition: 3
 Encoding: UTF-8
 LazyData: true
 Roxygen: list(markdown = TRUE)
-RoxygenNote: 7.3.2
+RoxygenNote: 7.3.3

LICENSE

@@ -1,2 +1,2 @@
-YEAR: 2025
+YEAR: 2026
 COPYRIGHT HOLDER: restatis authors

NEWS.md

@@ -1,3 +1,8 @@
+# restatis 0.4.0
+* Added support for four more GENESIS-like databases
+* Added the option to specify credentials in the function call
+* Fixed some bugs, optimised documentation
+
 # restatis 0.3.0
 
 * Added the feature that users can now adjust the API URLs via environment variables 

R/gen_alternative_terms.R

@@ -1,10 +1,11 @@
-#' Find similar search terms
+#' Find Similar Search Terms
 #'
-#' @description Function to find search terms that are similar or related to one another in spelling and also represented in the GENESIS, Zensus 2022 or regionalstatistik.de databases. Important note: The API call is searching for terms with the same characters. To be useful in searching for related terms it is highly recommended to work with "*" placeholders (see examples). The placeholder can be placed before and/or after the search term.
+#' @description Function to find search terms that are similar or related to one another in spelling and also represented in the databases supported by \pkg{restatis}. Important note: The API call is searching for terms with the same characters. To be useful in searching for related terms it is highly recommended to work with \code{*} placeholders (see examples). The placeholder can be placed before and/or after the search term.
 #'
-#' @param term Character string. Maximum length of 15 characters. Term or word for which you are searching for alternative or related terms. Use of '*' as a placeholder is possible to generate broader search areas.
+#' @param term Character string. Maximum length of 15 characters. Term or word for which you are searching for alternative or related terms. Use of \code{*} as a placeholder is possible to generate broader search areas.
 #' @param similarity Boolean. Indicator if the output of the function should be sorted based on a Levenshtein edit distance based on the \code{adist()} function. Default is 'TRUE'.
-#' @param database Character string. Indicator if the GENESIS ('genesis'), Zensus 2022 ('zensus') or regionalstatistik.de ('regio') database is called. Default option is 'all'.
+#' @param database Character string. Indicator if the GENESIS ('genesis'), Zensus 2022 ('zensus'), regionalstatistik.de ('regio'), statistikdaten.bayern.de ('bayern'), landesdatenbank.nrw.de ('nrw'), bildungsmonitoring.de ('bildung') or genesis.sachsen-anhalt.de ('st') database is called. If all databases should be checked, use 'all'. Default option is 'all'.
+#' @param credential_list A list containing the credentials for the databases to be accessed. If 'NULL' (default), the function will use the stored credentials from \code{gen_auth_get()}.
 #' @param pagelength Integer. Maximum length of results or objects (e.g., number of tables). Defaults to 500. Maximum of the databases is 25,000 objects.
 #' @param verbose Boolean. Indicator if the output of the function should include detailed messages and warnings. Default option is 'TRUE'. Set the parameter to 'FALSE' to suppress additional messages and warnings.
 #' @param ... Additional parameters for the API call. These parameters are only affecting the call itself, no further processing. For more details see `vignette("additional_parameter")`.
@@ -27,7 +28,8 @@
 #'
 gen_alternative_terms <- function(term = NULL,
                                   similarity = TRUE,
-                                  database = c("all", "genesis", "zensus", "regio"),
+                                  database = c("all", "genesis", "zensus", "regio", "bayern", "nrw", "bildung", "st"),
+                                  credential_list = NULL,
                                   pagelength = 500,
                                   verbose = TRUE,
                                   ...) {
@@ -44,13 +46,14 @@ gen_alternative_terms <- function(term = NULL,
 
   # Check availability of credentials for the database(s) selected
   database_vector <- test_database_function(database,
+                                            credential_list = credential_list,
                                             error.input = TRUE,
                                             text = verbose)
 
   #-----------------------------------------------------------------------------
 
   # Loop over databases in database_vector and make respective API calls
-  res <- lapply(database_vector, function(db){
+  res <- lapply(database_vector, function(db) {
 
     if (isTRUE(verbose)) {
 
@@ -63,8 +66,7 @@ gen_alternative_terms <- function(term = NULL,
     # Make API call
     results_raw <- gen_api(endpoint = "catalogue/terms",
                            database = db,
-                           username = gen_auth_get(database = db)$username,
-                           password = gen_auth_get(database = db)$password,
+                           credential_list = credential_list,
                            selection = term,
                            pagelength = pagelength,
                            ...)

R/gen_api.R

@@ -37,12 +37,14 @@ gen_api <- function(...,
 #'
 #' @param endpoint Character string. The endpoint of the API that is to be queried.
 #' @param database The database the query should be sent to.
+#' @param credential_list A named list including username and password for the database(s) to be queried. If NULL (default), the function will try to get credentials from the environment variables.
 #' @param ... Further parameters passed on to the final API call.
 #'
 #' @importFrom httr2 `%>%`
 #'
 .gen_api_core <- function(endpoint,
                           database,
+                          credential_list = NULL,
                           ...) {
 
   #-----------------------------------------------------------------------------
@@ -61,16 +63,51 @@ gen_api <- function(...,
 
     url <- Sys.getenv("RESTATIS_REGIO_URL")
 
+  } else if (database == "bayern") {
+
+    url <- Sys.getenv("RESTATIS_BAYERN_URL")
+
+  } else if (database == "nrw") {
+
+    url <- Sys.getenv("RESTATIS_NRW_URL")
+
+  } else if (database == "bildung") {
+
+    url <- Sys.getenv("RESTATIS_BILDUNG_URL")
+
+  } else if (database == "st") {
+
+    url <- Sys.getenv("RESTATIS_ST_URL")
+
+  } else {
+
+    stop(paste0("The database '", database, "' is not supported. Please check the documentation."),
+         call. = FALSE)
+
   }
 
   # Set user agent
   user_agent <- "https://github.com/CorrelAid/restatis"
 
+  # Set custom credentials
+  if (!is.null(credential_list)) {
+
+    username <- credential_list[[database]]["username"]
+    password <- credential_list[[database]]["password"]
+
+  } else {
+
+    username <- gen_auth_get(database = database)$username
+    password <- gen_auth_get(database = database)$password
+
+  }
+
   #-----------------------------------------------------------------------------
 
   # First try to request with POST
   # If POST errors, try GET
   # This allows flexibility across different database instances
+  # However, GET is deprecated in many instances after V5
 
   tryCatch( # tryCatch to try POST
 
@@ -98,8 +135,8 @@ gen_api <- function(...,
         httr2::req_user_agent(user_agent) %>%
         httr2::req_url_path_append(endpoint) %>%
         httr2::req_headers("Content-Type" = "application/x-www-form-urlencoded",
-                           "username" = gen_auth_get(database = database)$username,
-                           "password" = gen_auth_get(database = database)$password) %>%
+                           "username" = username,
+                           "password" = password) %>%
         httr2::req_retry(max_tries = 3) %>%
         httr2::req_perform()
 
@@ -109,11 +146,11 @@ gen_api <- function(...,
 
         expr = {
 
-          # Perform API call with GET (deprecated in GENESIS and Zensus 2022)
           httr2::request(url) %>%
             httr2::req_user_agent(user_agent) %>%
             httr2::req_url_path_append(endpoint) %>%
-            httr2::req_url_query(!!!gen_auth_get(database = database), ...) %>%
+            httr2::req_url_query("username" = username,
+                                 "password" = password, ...) %>%
             httr2::req_retry(max_tries = 3) %>%
             httr2::req_perform()
 
@@ -122,7 +159,7 @@ gen_api <- function(...,
           stop(paste0("The API call(s) have been tried with GET and POST methods, but were unsuccessful (error message: '", e$message, "'). Check your specifications or try again later."),
                call. = FALSE)
 
-      })
+        })
 
     })