Retrieve data from SUSR (Slovak Statistical Office) open data API as data frames

This function constructs and calls the dataset endpoint for one or more tables, including their dimension selections, and returns each as a data frame (tibble). Internally, it fetches JSON-stat and parses it using the rjstat package.

fetch_susr_data(
  params,
  lang = "en",
  base_url = "https://data.statistics.sk/api/v2/dataset"
)

Arguments

params

A list structured in pairs:

  1. A character string with the table code (e.g. "np3106rs").

  2. A list (or vector) of dimension "segments" in the order they should appear in the URL. Each segment can be:

    • A character scalar (e.g. "SK021"), or

    • A character vector (e.g. c("2016","2017","2018")) which we join by commas ("2016,2017,2018"),

    • Special keywords like "all", "last5", "LAU1", etc. (passed as-is).

For multiple tables, just keep repeating those pairs in the same list.

lang

The language code. Defaults to "en". Can also be "sk".

base_url

The base SUSR dataset endpoint. Defaults to "https://data.statistics.sk/api/v2/dataset".

Value

A named list of data frames, keyed by the table codes.

Error & Warning Handling We use tryCatch() blocks around both network calls and JSON parsing. While we know some specific issues that could occur (like an invalid URL, or invalid JSON structure), there may be other rare/unexpected problems. If an error occurs, we issue a warning and store NULL for that table.

Dimension Count Check Before constructing the URL, we call susr_tables() (in "long" format) to retrieve a list of the dimension codes for the table. We then check if the user-supplied dimension specs have the same length as the number of distinct dimension_code. If not, we warn the user. (This ensures at least the total dimension count is valid.)

Details

The order of dimension segments is crucial. For example, if the official URL pattern is:


  https://data.statistics.sk/api/v2/dataset/<table_code>/<param1>/<param2>/<param3>?lang=en&type=json

then pass list("param1", "param2", "param3") in that exact order.

Internally, each JSON-stat response is converted to a data frame (tibble) using rjstat::fromJSONstat(). If the JSON structure is invalid or the API call fails, the corresponding table is stored as NULL (with a warning).