| Title: | Interface to the Italian National Institute of Statistics ('ISTAT') API |
|---|---|
| Description: | Provides an interface to the 'ISTAT' 'SDMX' RESTful API <https://esploradati.istat.it/SDMXWS/rest/>. Allows users to discover available datasets, explore their structure and dimensions, and retrieve statistical data from the Italian National Institute of Statistics. Based on the Python 'istatapi' package by Jacopo Attolini. |
| Authors: | Juan Ignacio Fulponi [aut, cre] |
| Maintainer: | Juan Ignacio Fulponi <[email protected]> |
| License: | Apache License (>= 2) |
| Version: | 0.1.0 |
| Built: | 2026-06-03 08:45:59 UTC |
| Source: | https://github.com/jfulponi/istatr |
Retrieves a list of all available datasets (dataflows) from the ISTAT API.
all_available()all_available()
A tibble with the following columns:
Dataflow ID
Dataset version
English description of the dataset
Data structure definition ID
## Not run: # Get all available datasets datasets <- all_available() head(datasets) ## End(Not run)## Not run: # Get all available datasets datasets <- all_available() head(datasets) ## End(Not run)
Returns information about the dimensions of a dataset, including their positions and associated codelists.
dimensions_info(dataset, include_descriptions = TRUE)dimensions_info(dataset, include_descriptions = TRUE)
dataset |
An istat_dataset object |
include_descriptions |
Logical; whether to include dimension descriptions (default: TRUE) |
A tibble with dimension information
## Not run: ds <- istat_dataset("139_176") dimensions_info(ds) ## End(Not run)## Not run: ds <- istat_dataset("139_176") dimensions_info(ds) ## End(Not run)
Functions for discovering and exploring ISTAT datasets
Uses the availableconstraint endpoint to get all valid values for each dimension. This is more accurate than getting values from codelists as it reflects actual data availability.
get_available_values(dataset)get_available_values(dataset)
dataset |
An istat_dataset object |
A named list where each element contains a tibble of available values for that dimension
## Not run: ds <- istat_dataset("139_176") available <- get_available_values(ds) available$FREQ # Available frequency values ## End(Not run)## Not run: ds <- istat_dataset("139_176") available <- get_available_values(ds) available$FREQ # Available frequency values ## End(Not run)
Fetches data from an ISTAT dataset using the currently set filters. The data is returned as a tibble with the TIME_PERIOD column converted to Date format and sorted in ascending order.
get_data( dataset, start_period = NULL, end_period = NULL, last_n_observations = NULL )get_data( dataset, start_period = NULL, end_period = NULL, last_n_observations = NULL )
dataset |
An istat_dataset object with filters set |
start_period |
Optional start date for filtering (format: YYYY-MM-DD or YYYY) |
end_period |
Optional end date for filtering (format: YYYY-MM-DD or YYYY) |
last_n_observations |
Optional integer to get only the last N observations |
A tibble containing the requested data with columns including:
Dataset identifier
Frequency
Time period (as Date)
Observation value
Additional dimension and metadata columns
## Not run: # Create and configure dataset ds <- istat_dataset("139_176") ds <- set_filters(ds, FREQ = "M", TIPO_DATO = c("ISAV", "ESAV"), PAESE_PARTNER = "WORLD" ) # Get all data data <- get_data(ds) # Get data for a specific time range data <- get_data(ds, start_period = "2020-01-01", end_period = "2023-12-31") # Get only the last 12 observations data <- get_data(ds, last_n_observations = 12) ## End(Not run)## Not run: # Create and configure dataset ds <- istat_dataset("139_176") ds <- set_filters(ds, FREQ = "M", TIPO_DATO = c("ISAV", "ESAV"), PAESE_PARTNER = "WORLD" ) # Get all data data <- get_data(ds) # Get data for a specific time range data <- get_data(ds, start_period = "2020-01-01", end_period = "2023-12-31") # Get only the last 12 observations data <- get_data(ds, last_n_observations = 12) ## End(Not run)
Retrieves all available values for a specific dimension of a dataset.
get_dimension_values(dataset, dimension_id)get_dimension_values(dataset, dimension_id)
dataset |
An istat_dataset object |
dimension_id |
The ID of the dimension |
A tibble with columns:
Value ID/code
Human-readable name (English)
## Not run: ds <- istat_dataset("139_176") get_dimension_values(ds, "TIPO_DATO") ## End(Not run)## Not run: ds <- istat_dataset("139_176") get_dimension_values(ds, "TIPO_DATO") ## End(Not run)
Creates a dataset object for a specific ISTAT dataflow. This object can be used to explore the dataset's structure, dimensions, and available values, and to set filters before retrieving data.
istat_dataset(dataflow_identifier)istat_dataset(dataflow_identifier)
dataflow_identifier |
Either a dataflow ID (e.g., "139_176"), a structure ID, or an exact dataset description |
A list with class "istat_dataset" containing:
Dataflow ID
Dataset version
Dataset description
Data structure definition ID
Named list of dimension information
Named list of current filters (initialized to "." for all)
## Not run: # Create dataset by ID ds <- istat_dataset("139_176") # View dimensions dimensions_info(ds) # Get available values for a dimension get_dimension_values(ds, "TIPO_DATO") # Set filters ds <- set_filters(ds, FREQ = "M", TIPO_DATO = c("ISAV", "ESAV")) ## End(Not run)## Not run: # Create dataset by ID ds <- istat_dataset("139_176") # View dimensions dimensions_info(ds) # Get available values for a dimension get_dimension_values(ds, "TIPO_DATO") # Set filters ds <- set_filters(ds, FREQ = "M", TIPO_DATO = c("ISAV", "ESAV")) ## End(Not run)
A convenience function that combines creating a dataset, setting filters, and retrieving data in one call.
istat_get( dataflow_id, ..., start_period = NULL, end_period = NULL, last_n_observations = NULL )istat_get( dataflow_id, ..., start_period = NULL, end_period = NULL, last_n_observations = NULL )
dataflow_id |
Dataflow ID (e.g., "139_176") |
... |
Named filter arguments (dimension_id = value) |
start_period |
Optional start date |
end_period |
Optional end date |
last_n_observations |
Optional integer to get only the last N observations |
A tibble containing the requested data
## Not run: # Quick retrieval with filters data <- istat_get( "139_176", FREQ = "M", TIPO_DATO = "ISAV", PAESE_PARTNER = "WORLD", start_period = "2020-01-01" ) ## End(Not run)## Not run: # Quick retrieval with filters data <- istat_get( "139_176", FREQ = "M", TIPO_DATO = "ISAV", PAESE_PARTNER = "WORLD", start_period = "2020-01-01" ) ## End(Not run)
The ISTAT API can be slow to respond, especially for large queries. This function allows you to get or set the timeout value in seconds. The default timeout is 300 seconds (5 minutes).
istat_timeout(seconds = NULL)istat_timeout(seconds = NULL)
seconds |
Optional. If provided, sets the timeout to this value in seconds. If NULL (default), returns the current timeout value. |
If seconds is NULL, returns the current timeout value.
If seconds is provided, invisibly returns the previous timeout value.
# Get current timeout istat_timeout() # Set timeout to 10 minutes istat_timeout(600) # Set timeout back to default istat_timeout(300)# Get current timeout istat_timeout() # Set timeout to 10 minutes istat_timeout(600) # Set timeout back to default istat_timeout(300)
Print method for istat_dataset
## S3 method for class 'istat_dataset' print(x, ...)## S3 method for class 'istat_dataset' print(x, ...)
x |
An istat_dataset object |
... |
Additional arguments (ignored) |
Invisibly returns the input
Reset all filters to default (all values)
reset_filters(dataset)reset_filters(dataset)
dataset |
An istat_dataset object |
The modified istat_dataset object with all filters reset to "."
## Not run: ds <- istat_dataset("139_176") ds <- set_filters(ds, FREQ = "M") ds <- reset_filters(ds) # All filters back to "." ## End(Not run)## Not run: ds <- istat_dataset("139_176") ds <- set_filters(ds, FREQ = "M") ds <- reset_filters(ds) # All filters back to "." ## End(Not run)
Searches available ISTAT datasets by keyword in their description. The search is case-insensitive.
search_dataset(keyword)search_dataset(keyword)
keyword |
Character string to search for in dataset descriptions |
A tibble with matching datasets (same columns as all_available())
## Not run: # Search for datasets related to imports import_datasets <- search_dataset("import") # Search for population datasets pop_datasets <- search_dataset("population") ## End(Not run)## Not run: # Search for datasets related to imports import_datasets <- search_dataset("import") # Search for population datasets pop_datasets <- search_dataset("population") ## End(Not run)
Sets dimension filters that will be used when retrieving data. Filter names should match dimension IDs (case-insensitive).
set_filters(dataset, ...)set_filters(dataset, ...)
dataset |
An istat_dataset object |
... |
Named arguments where names are dimension IDs and values are either single values or character vectors for multiple values. Use "." to select all values for a dimension. |
The modified istat_dataset object
## Not run: ds <- istat_dataset("139_176") # Set single values ds <- set_filters(ds, FREQ = "M", PAESE_PARTNER = "WORLD") # Set multiple values ds <- set_filters(ds, TIPO_DATO = c("ISAV", "ESAV")) ## End(Not run)## Not run: ds <- istat_dataset("139_176") # Set single values ds <- set_filters(ds, FREQ = "M", PAESE_PARTNER = "WORLD") # Set multiple values ds <- set_filters(ds, TIPO_DATO = c("ISAV", "ESAV")) ## End(Not run)