The main change: new functions for the Swiss Stats Explorer (SSE), which replaces STAT-TAB. The old SSE functions are deprecated, but they still work. Please read "Breaking changes" before you update.
SSE labels (data change). bfs_get_sse_metadata() and
bfs_get_sse_data() gave wrong labels, or failed, when some codes of a
codelist have no name in the requested language:
DF_SSV_POL_LEG with language = "de", "fr" or "it", all 181
cities were labelled "Gesamtwert für Schweizer Städte" / "Total des
villes suisses";Each code now gets its own label, with a fallback to another language. The
values don't change. But if you filter, group, pivot or join on these
labels (variable_value_type = "text", the default of bfs_get_sse_data()),
your results can change.
bfs_get_asset_metadata() accepts only one language. An error is
given for several languages, e.g. language = c("fr", "de"). Before, the
API used only the first one. The default value c("de", "fr", "it", "en"),
e.g. forwarded by a wrapper function, still works and uses "de".
New class and message for API errors. See "Errors when an API is not
available" below. If your code tests class(e)[1], use inherits()
instead.
R >= 4.0.0 is required (needed by tools::R_user_dir() and httr2), as
well as httr2 >= 1.0.0 and purrr >= 1.0.0.
bfs_sse_datasets() lists the datasets of the Swiss Stats Explorer,
bfs_sse_dimensions() gives their dimensions and values, and
bfs_sse_data() downloads their data. They are a thin wrapper of the SDMX
REST API: they use only what the SDMX standard defines and leave the rest
to the API (latest version, labels in a language, checks of the codes), so
they keep working if the API changes its internals.bfs_get_sse_metadata() and bfs_get_sse_data(), they:
TIME_PERIOD, a dimension given twice,
an empty vector of codes or NA;version (by default the
latest, chosen by the API), so a data pipeline keeps the same structure.
The data always has the same version as the dimensions used to build the
query;first_n and
last_n (the SDMX parameters firstNObservations and
lastNObservations), e.g. last_n = 1 for the latest value;labels = "both", the default, as two codes can have the
same label), only the codes or only the labels, and optionally the
attributes such as OBS_STATUS (attributes = TRUE);description column of
bfs_sse_datasets()), to search the datasets by their content;parent column of
bfs_sse_dimensions()), e.g. the district of a commune and the canton
of a district, to select all the communes of a canton;TIME_PERIOD as text, as given by the API;bfs_no_records, bfs_sse_filter_error,
bfs_sse_argument_error, bfs_sse_dataset_error, bfs_sse_query_error
(a query refused by the API, with its message, e.g. a wrong period or a
too long URL), bfs_sse_format_error and bfs_http_error;dataset to be named. An argument of the
old functions gives an error that names the new argument (e.g.
number_bfs is now dataset, query is now filters).bfs_get_sse_metadata() and bfs_get_sse_data() are deprecated
(lifecycle::deprecate_soft()). They warn when called from your code or
from the tests of a package, not when called inside another package. They
are kept for the data pipelines using them and get only bug fixes (see
"Breaking changes" and "Bug fixes and improvements"). The new article
"Moving to the new Swiss Stats Explorer functions" explains the
differences and how to move your code.bfs_http_error if the API is not available (e.g. HTTP 429 Too Many
Requests, timeout, server error). This includes the data downloads of
bfs_get_data() and bfs_get_data_comments() and the file download of
bfs_download_asset().
httr2_http_429,
http_429 or curl_error_couldnt_connect), so existing error handlers
still work, e.g.
tryCatch(..., httr2_http_429 = function(e) httr2::resp_retry_after(e$resp)).bfs_http_error: test the class with inherits()
instead of class(e)[1]. conditionCall(e) is NULL, the original call
is in conditionCall(e$parent).bfs_get_sse_data() gives a bfs_http_error only for HTTP 429 and server
errors. A query refused by the API (other HTTP 4xx, e.g. a wrong period)
gives the same error as before, "HTTP error: bfs_get_sse_data() no longer fails with the error "Tibble columns must
have compatible sizes" if an observation has fewer dimensions than the
others.bfs_get_sse_data() and bfs_get_sse_metadata() send one request fewer
after the first call. If a dataset is not in the cached list, the list is
downloaded again, so a dataset published since the first call is found.
But a long-running R session (e.g. a Shiny app) keeps using the version of
a dataset it saw first: call bfs_clear_cache() to use a new version, or
use the new functions, which cache nothing.
bfs_get_sse_data() also sends one request fewer for the metadata.bfs_get_catalog_data() and bfs_get_catalog_tables():
prodima = c(900210, 900212), as documented;limit, as more
results may be available. Use suppressMessages() if you don't want
this message;bfs_get_catalog_data() no
longer has the columns url_structure_json and damId. In the empty
result of bfs_get_catalog_tables(), the column number_asset now comes
before publication_date.bfs_get_asset_metadata() sends only one language to the API (by default
"de", which returns the same metadata as before).bfs_get_catalog_tables().bfs_clear_cache() to delete the cached base maps and SSE dataflows.bfs_get_base_maps():
geom is missing.bfs_download_geodata() creates the output_dir folder correctly and gives
a clear error if collection_id is missing.bfs_get_catalog_geodata() retries the metadata requests of the
collections. It gives a message listing the collections whose metadata
could not be retrieved (NA metadata), instead of hiding them.bfs_get_data(), bfs_get_metadata() and
bfs_get_data_comments().register_kt_seeanteile (41 rows, 3 columns) in its
documentation.bfs_get_sse_url() and get_xml_name() no longer
have help pages.llms.txt. It is built and published
by GitHub Actions on each release, and the built site (docs/) is no
longer tracked in git.skip_on_cran()), as the
PXWeb API can rate-limit the CRAN check machines.bfs_get_sse_data() and
bfs_get_sse_metadata() in \donttest{} to avoid CRAN/CI check failures
when the Swiss Stats Explorer API is unreachable or times out.bfs_get_sse_data() on Debian-clang.bfs_get_base_maps() with new return_sf argument,
which allows to return all file path available (see README).bfs_get_base_maps()orderNr returned by bfs_get_catalog() renamed
as number_bfs for more clarity. Unnecessary new variables also removed in
profit of the return_raw argument.return_raw in bfs_get_catalog() and bfs_get_tables(), which returns
all metadata in an raw / unstructured tibble.bfs_get_base_maps()
bfs_get_catalog(),
bfs_get_catalog_data() and bfs_get_catalog_tables()bfs_get_catalog(), bfs_get_catalog_data() and bfs_get_catalog_tables()bfs_get_data() and bfs_get_data_comments()
Sys.sleep() of 10 seconds to avoid reaching API limitsbfs_get_data() and
bfs_get_data_comments()
bfs_get_catalog_data() and bfs_get_asset_metadata()bfs_get_catalog()bfs_get_base_maps() #12bfs_get_catalog_*()bfs_get_base_maps().bfs_download_geodata() and
bfs_get_base_maps(), the user will be asked to install "rstac" and "sf" if
they are not installed locally. Tests using these dependencies are skipped
in CRAN and CI.bfs_download_geodata() automated tests will reduce API calls on
"data.geo.admin.ch" server.bfs_get_catalog_data() and bfs_get_catalog_tables() return now in the dataframe "number_asset" instead of "guid" as variables.bfs_download_asset()bfs_get_asset_metadata()bfs_get_metadata()bfs_get_data(). Fix now #10 by removing "all" default argument to query.bfs_get_catalog_geodata()bfs_download_geodata()bfs_get_catalog_tables() now gets full catalog, fixing #5bfs_get_catalog_tables() has new functions to filter datasets directlybfs_get_metadata()as_tibble(. .name_repair = "minimal")bfs_get_data_comments() #8.query argument in bfs_get_data()bfs_get_metadata() and bfs_get_dataset()bfs_get_catalog_data() and bfs_get_catalog_tables() bug #6.bfs_get_catalog_* functions.bfs_get_catalog_data() and bfs_get_catalog_tables() bug #6.clean_names of bfs_get_data() is now FALSE by default.bfs_get_data() uses BFS API v1.bfs_get_metadata() deprecated. Please use only bfs_get_catalog_data().bfs_get_catalog_tables().bfs_get_catalog().bfs_get_dataset()bfs_get_catalog()NEWS.md file to track changes to the package.bfs_get_catalog() function, that scraps the RSS feed