---
title: "Get started"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Get started}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
# The examples call the BFS APIs: they run on the pkgdown site only, not on
# CRAN, where the APIs can be unavailable or rate-limit the check machines.
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  message = FALSE,
  warning = FALSE,
  eval = identical(Sys.getenv("IN_PKGDOWN"), "true")
)
```

BFS gives you the open data of the
[Swiss Federal Statistical Office](https://www.bfs.admin.ch/bfs/en/home/statistics/catalogue.html)
(BFS, *Bundesamt für Statistik*) in R. You get tidy data frames, in German,
French, Italian or English.

On this page, you learn:

- which API to use for which data,
- why the BFS is moving its data to a new platform,
- how to make a first download.

## Which API for which data

The BFS publishes its data with four APIs. The package has functions for
each of them:

| You want | Use | API |
|---|---|---|
| Statistics of the Swiss Stats Explorer | `bfs_sse_datasets()`, `bfs_sse_dimensions()`, `bfs_sse_data()` | [Swiss Stats Explorer](https://stats.swiss/) (SDMX) |
| Datasets of the BFS data catalog | `bfs_get_catalog_data()`, `bfs_get_metadata()`, `bfs_get_data()` | [STAT-TAB](https://www.pxweb.bfs.admin.ch/pxweb/en/) (PXWeb) |
| Tables and files (Excel, CSV, PX, ...) | `bfs_get_catalog_tables()`, `bfs_download_asset()` | DAM |
| Maps and geodata | `bfs_get_base_maps()`, `bfs_get_catalog_geodata()`, `bfs_download_geodata()` | ThemaKart, STAC |

- The **Swiss Stats Explorer** (SSE) is the new data platform of the BFS.
  Each dataset has an id, for example `DF_LWZ_1`.
- **STAT-TAB** is the old platform. Each dataset (data cube) has a BFS
  number, for example `px-x-1502040100_131`.
- The **DAM** API gives you all the files of the BFS, for example the Excel
  tables of the website.
- The **geodata** come from the Swiss geo-portal and from the base maps of
  the BFS.

## From STAT-TAB to the Swiss Stats Explorer

The BFS is replacing STAT-TAB with the Swiss Stats Explorer. It moves its
data cubes to the new platform, one statistic at a time. Then it will
switch off STAT-TAB. The
[BFS announcement](https://www.bfs.admin.ch/bfs/en/home/services/research/stat-tab-online-data-search.html)
gives the dates.

What this means for your code:

- `bfs_get_data()`, `bfs_get_metadata()` and `bfs_get_data_comments()` use
  STAT-TAB. They will stop working when STAT-TAB is switched off.
- During the move, a statistic can be on STAT-TAB only, on both platforms,
  or on the Swiss Stats Explorer only.
- If a BFS number does not work anymore, search the statistic by its name
  on [stats.swiss](https://stats.swiss/).
- The functions for tables, files and geodata do not change.

::: {.callout .callout-tip}
For new code, use the Swiss Stats Explorer if the statistic is there. Use
STAT-TAB only for the data that is not there yet.
:::

## A first download

```{r}
library(BFS)
```

### Swiss Stats Explorer

Let's get the vacancy rate (the share of empty homes, in %) of the cantons
of Geneva, Zurich and Bern. The dataset is `DF_LWZ_1`, the vacant
dwellings. You find this id with `bfs_sse_datasets()`, or in the URL of the
dataset on [stats.swiss](https://stats.swiss/).

First, see the dimensions of the dataset and the codes of their values:

```{r}
dimensions <- bfs_sse_dimensions("DF_LWZ_1", language = "en")
dimensions
```

Then download the data. In `filters`, give the codes you want for each
dimension:

```{r}
bfs_sse_data(
  "DF_LWZ_1",
  filters = list(
    GR_KT_GDE = c("GE", "ZH", "BE"), # the cantons of Geneva, Zurich and Bern
    WOHN_ANZAHL = "_T",              # all numbers of rooms
    LEERWOHN_TYP = "_T",             # all types of vacant dwellings
    MEASURE_DIMENSION = "RATE"       # the vacancy rate, in %
  ),
  start_period = "2020",
  language = "en"
)
```

The article [Swiss Stats Explorer](https://felixluginbuhl.com/BFS/articles/swiss-stats-explorer.html)
explains each step of this example.

### STAT-TAB

Search the BFS data catalog. Then download a dataset with its BFS number:

```{r}
bfs_get_catalog_data(language = "en", extended_search = "university students")

bfs_get_data(number_bfs = "px-x-1502040100_131", language = "en")
```

The article [Data catalog and PXWeb datasets](https://felixluginbuhl.com/BFS/articles/pxweb.html)
shows how to search the catalog and download only a part of a dataset.

## Next steps

- [Swiss Stats Explorer](https://felixluginbuhl.com/BFS/articles/swiss-stats-explorer.html): find a
  dataset, choose the data and download it, step by step.
- [Data catalog and PXWeb datasets](https://felixluginbuhl.com/BFS/articles/pxweb.html): search the catalog
  and download all or part of a dataset.
- [Tables and files](https://felixluginbuhl.com/BFS/articles/tables-and-files.html): download any BFS file.
- [Geodata and base maps](https://felixluginbuhl.com/BFS/articles/geodata.html): maps of Switzerland and
  geodata of the Swiss geo-portal.
- [API errors and rate limits](https://felixluginbuhl.com/BFS/articles/troubleshooting.html): what to do
  when an API is not available.