Package 'BFS'

Title: Get Data from the Swiss Federal Statistical Office
Description: Search and download data from the Swiss Federal Statistical Office (BFS) APIs <https://www.bfs.admin.ch/>.
Authors: Felix Luginbuhl [aut, cre, cph] (ORCID: <https://orcid.org/0009-0008-6625-2899>), Marius Hodel [ctb] (ORCID: <https://orcid.org/0000-0001-8789-506X>), Janosch Brenzel-Weiss [ctb], Joao Martins [ctb], Philipp Baumann [ctb] (ORCID: <https://orcid.org/0000-0002-3194-8975>)
Maintainer: Felix Luginbuhl <[email protected]>
License: GPL (>= 3)
Version: 0.7.1
Built: 2026-06-05 07:08:09 UTC
Source: https://github.com/lgnbhl/BFS

Help Index

Download a BFS asset file

Description

This function uses the DAM API https://dam-api.bfs.admin.ch/hub/swagger-ui/index.html to download a BFS file by asset number or BFS number. The file is downloaded using 'curl::curl_download()' under the hood.

Usage

bfs_download_asset(
  number_asset = NULL,
  number_bfs = NULL,
  destfile,
  quiet = TRUE,
  mode = "wb",
  handle = curl::new_handle()
)

Arguments

number_asset

The asset number of a dataset
number_bfs

The BFS number of a dataset.
destfile

A character string with the name where the downloaded file is saved. Tilde-expansion is performed.
quiet

If TRUE, suppress status messages (if any), and the progress bar.
mode

A character string specifying the mode with which to write the file. Useful values are "w", "wb" (binary), "a" (append) and "ab".
handle

a curl handle object

Value

Returns the file path where the file has been downloaded. Returns NULL if no connection.

Download a geographic file from the Swiss geo-portal

Description

Download assets from the STAC API on the geodata catalog of the Swiss Confederation (https://data.geo.admin.ch/api/stac/v0.9/).

Usage

bfs_download_geodata(
  collection_id = collection_id,
  output_dir = tempdir(),
  overwrite = FALSE,
  create_json = FALSE,
  bbox = NULL,
  asset_names = NULL,
  datetime = NULL,
  feature_id = NULL
)

Arguments

collection_id

collection_id
output_dir

output_dir
overwrite

overwrite
create_json

create_json
bbox

bbox
asset_names

asset_names
datetime

datetime
feature_id

feature_id

Details

The use of the data and services is free but subject to the provisions on fair use (see https://www.geo.admin.ch/terms-of-use).

Value

Returns the file path where the file has been downloaded. Returns NULL if no connection.

Get asset metadata in a given language

Description

This function uses the DAM API https://dam-api.bfs.admin.ch/hub/swagger-ui/index.html to get the metadata of a BFS file by asset number or BFS number in a given language.

Usage

bfs_get_asset_metadata(
  number_asset = NULL,
  number_bfs = NULL,
  language = c("de", "fr", "it", "en")
)

Arguments

number_asset

The asset number of a dataset
number_bfs

The BFS number of a dataset.
language

character The language of a BFS catalog, i.e. "de", "fr", "it" or "en".

Value

list Returns a list containing asset metadata information. Returns NULL if no connection.

See Also

[bfs_download_asset()]

Get Switzerland base maps data

Description

This functions helps to get base maps data from the ThemaKart project as an sf object. The geom names and the general structure of the files can be found in the offical BFS documentation, see https://www.bfs.admin.ch/bfs/en/home/statistics/regional-statistics/base-maps/cartographic-bases.html. When using this data, please read the condition of use and copyright mentions.

Usage

bfs_get_base_maps(
  geom = NULL,
  category = "gf",
  type = "Poly",
  date = NULL,
  most_recent = TRUE,
  format = "shp",
  asset_number = "30566934",
  return_sf = TRUE
)

Arguments

geom

Geometry such as "suis", "kant", "bezk", "polg", "voge", etc.
category

Category such as 'total_area' ("gf" for "Gesamtflaeche") or 'vegetation_area' ("vf" for "Vegetationsflaeche").
type

The type of data, i.e. "Poly" or "Pnts".
date

Date (yyyymmdd) of reference / validity. If not specified, the 'most_recent' argument is used.
most_recent

Get the most recent by sorting the files in decreasing order, if FALSE then read the first file available.
format

Format of the file, by default SHP format.
asset_number

Asset number of the base maps zip file.
return_sf

if TRUE, read file path and return sf object. If FALSE, return file path

Details

If you want to get ThemaKart data from previous years, you can change the 'asset_number' for the related zip file. For example, for the map set of year 2020, the asset number is "11927607".

This function is caching the base map data using 'tools::R_user_dir(package = "BFS")'.

Value

sf object with geometries. Returns NULL if no connection.

Get the BFS data or table catalog

Description

This function scraps a given RSS Feed of the Swiss Federal Statistical Office.

Usage

bfs_get_catalog(language = "de", type = "data")

Arguments

language

character The language of a BFS catalog.
type

character A BFS catalog

Value

A data frame. Returns NULL if no connection.

See Also

bfs_get_data

Get the BFS data catalog

Description

Get the list of the data available in the official DAM-API of the Swiss Federal Statistical Office asset catalog.

Usage

bfs_get_catalog_data(
  language = "de",
  title = NULL,
  extended_search = NULL,
  spatial_division = NULL,
  prodima = NULL,
  inquiry = NULL,
  institution = NULL,
  publishing_year_start = NULL,
  publishing_year_end = NULL,
  order_nr = NULL,
  limit = 1000,
  article_model = 900033,
  article_model_group = 900029,
  return_raw = FALSE
)

Arguments

language

character The language of a BFS catalog, i.e. "de", "fr", "it" or "en".
title

character String to search in (sub/super)title
extended_search

character String for an extended search in (sub/super)title, orderNr, summary, shortSummary, shortTextGNP
spatial_division

BFS datasets by spatial division, choose between "Switzerland", "Cantons", "Districts", "Communes", "Other spatial divisions" or "International"
prodima

numeric Get only specific BFS themes using one or multiple prodima numbers
inquiry

character BFS datasets for an inquiry
institution

character BFS datasets for an institution
publishing_year_start

character BFS datasets for a publishing year start
publishing_year_end

character BFS datasets for a publishing year end
order_nr

character Filter by BFS Number (FSO number)
limit

integer limit of query results (1000 by default)
article_model

integer articleModel parameter query
article_model_group

integer articleModel parameter query
return_raw

boolean Return raw data from json structure as a tibble data.frame

Value

A data frame. Returns NULL if no connection.

A tbl_df (a type of data frame; see tibble or dplyr packages). Returns NULL if no connection.

See Also

bfs_get_data

title

A character column with the title of the BFS dataset

language

A character column with the language of the BFS dataset

number_asset

The BFS asset number

number_bfs

The BFS number (FSO number), named orderNr in the API

publication_date

The published date of the BFS dataset, named embargo in the API

language_available

A list The list of all languages available for the BFS dataset

url_px

A character column with the URL of the PX file

url_structure_json

A character column with the URL of the json structure of the BFS dataset

damId

DAM API unique ID

Examples

bfs_get_catalog_data(language = "en", title = "students", prodima = c(900212))

Get the geodata catalog of the Swiss Confederation

Description

Display geo-information catalog of the Swiss Confederation (https://data.geo.admin.ch/), including some geographic datasets provided by the Swiss Federal Statistical Office. Note that this geodata catalog is not hosted by the Swiss Federal Statistical Office.

Usage

bfs_get_catalog_geodata(include_metadata = TRUE)

Arguments

include_metadata

boolean TRUE to loop on each geodata to add metadata.

Details

For now only Stac API datasets are accessible.

Value

A tbl_df (a type of data frame; see tibble or dplyr packages). Returns NULL if no connection.

Get the BFS tables catalog

Description

Get the list of the tables available in the official DAM-API of the Swiss Federal Statistical Office asset catalog.

Usage

bfs_get_catalog_tables(
  language = "de",
  title = NULL,
  extended_search = NULL,
  spatial_division = NULL,
  prodima = NULL,
  inquiry = NULL,
  institution = NULL,
  publishing_year_start = NULL,
  publishing_year_end = NULL,
  order_nr = NULL,
  limit = 1000,
  article_model = 900030,
  article_model_group = 900029,
  return_raw = FALSE
)

Arguments

language

character The language of a BFS catalog, i.e. "de", "fr", "it" or "en".
title

character String to search in (sub/super)title
extended_search

character String for an extended search in (sub/super)title, orderNr, summary, shortSummary, shortTextGNP
spatial_division

BFS datasets by spatial division, choose between "Switzerland", "Cantons", "Districts", "Communes", "Other spatial divisions" or "International"
prodima

numeric Get only specific BFS themes using one or multiple prodima numbers
inquiry

character BFS datasets for an inquiry
institution

character BFS datasets for an institution
publishing_year_start

character BFS datasets for a publishing year start
publishing_year_end

character BFS datasets for a publishing year end
order_nr

character Filter by BFS Number (FSO number)
limit

integer limit of query results (1000 by default)
article_model

integer articleModel parameter query
article_model_group

integer articleModel parameter query
return_raw

boolean Return raw data from json structure as a tibble data.frame

Value

A data frame. Returns NULL if no connection.

A tbl_df (a type of data frame; see tibble or dplyr packages). Returns NULL if no connection.

See Also

bfs_get_data

title

A character column with the title of the BFS dataset

language

A character column with the language of the BFS dataset

publication_date

The published date of the BFS dataset in the data catalog

number_asset

The BFS asset number

Examples

bfs_get_catalog_data(language = "en", title = "students", prodima = c(900212))

Get BFS data in a given language

Description

Get a dataset using the PXWEB API v1. You should choose either the BFS number (FSO number) of the BFS offical url of a given dataset. You can query particulary variables using the 'query' argument.

Usage

bfs_get_data(
  number_bfs,
  language = "de",
  query = NULL,
  column_name_type = "text",
  variable_value_type = "text",
  clean_names = FALSE,
  delay = NULL
)

Arguments

number_bfs

The BFS number (FSO number) of a dataset.
language

Language of the dataset to be translated if exists, i.e. "de", "fr", "it" or "en".
query

A list with named values, a json query file or json query string using pxweb::pxweb_query().
column_name_type

Column name type as "text" or as "code".
variable_value_type

Variable value type as "text" or as "code".
clean_names

Clean column names using janitor::clean_names().
delay

Integer Number of seconds to wait before query using Sys.sleep().

Value

A tbl_df (a type of data frame; see tibble or dplyr packages). Returns NULL if no connection.

See Also

bfs_get_data_comments

Get the comments/footnotes of a BFS dataset in a given language

Description

Get the comments/footnotes of a BFS dataset using PXWEB BFS API v1.

Usage

bfs_get_data_comments(
  number_bfs,
  language = "de",
  query = NULL,
  clean_names = FALSE,
  delay = NULL
)

Arguments

number_bfs

The BFS number of a dataset.
language

Language of the dataset to be translated if exists, i.e. "de", "fr", "it" or "en".
query

a list with named values, a json query file or json query string using pxweb::pxweb_query().
clean_names

Clean column names using janitor::clean_names()
delay

Integer Number of seconds to wait before query using Sys.sleep().

Value

A tbl_df (a type of data frame; see tibble or dplyr packages). Returns NULL if no connection.

See Also

bfs_get_data

Get metadata of a BFS data in a given language

Description

Get the metadata of a BFS dataset using the PXWEB API v1. You should choose either the bfs number of the bfs offical url of a given dataset.

Usage

bfs_get_metadata(number_bfs, language = "de")

Arguments

number_bfs

The BFS number of a dataset.
language

Language of the dataset to be translated if exists.

Value

A tbl_df (a type of data frame; see tibble or dplyr packages). Returns NULL if no connection.

Get Data from Swiss Stats Explorer (SSE) API

Description

Get Data from Swiss Stats Explorer (SSE) API

Usage

bfs_get_sse_data(
  number_bfs,
  language = "de",
  start_period = NULL,
  end_period = NULL,
  query = NULL,
  column_name_type = "code",
  variable_value_type = "text",
  clean_names = FALSE
)

Arguments

number_bfs

The BFS number (FSO number) of a dataset.
language

Language of the dataset to be translated if exists, i.e. "de", "fr", "it" or "en".
start_period

Start year of the requested data
end_period

End year of the requested data
query

A named list with dimension codes as names and desired values as values.
column_name_type

Column name type as "text" or as "code".
variable_value_type

Variable value type as "text" or as "code".
clean_names

Logical, if TRUE, the column names are cleaned using janitor::clean_names().

Value

A tibble with the requested data.

Examples

bfs_get_sse_data(
  number_bfs = "DF_PASTA_552_MONTHLY", 
  language = "en", 
  query =  list("FREQ" = "M", "ACCOMMODATION_TYPE" = c("552001"), 
                "COUNTRY_ORIGIN" = c("CH", "AUSL")),
  start_period = "2020",
  end_period = "2023"
  )

Get Metadata (Codelists) from Swiss Stats Explorer (SSE) API

Description

Retrieve metadata codelists for a specified BFS dataset from the Swiss Stats Explorer (SSE) API. This function is required to built queries for bfs_get_sse_data.

Usage

bfs_get_sse_metadata(number_bfs, language = "de")

Arguments

number_bfs

The BFS number (FSO number) of a dataset.
language

Language of the codelists ("de", "fr", "it", "en").

Value

A tibble containing the codelists of the specified BFS dataset.

Examples

bfs_get_sse_metadata("DF_SSV_POL_LEG", language = "de")

Get the URL for the Swiss Stats Explorer (SSE) API based on the BFS number

Description

Get the URL for the Swiss Stats Explorer (SSE) API based on the BFS number

Usage

bfs_get_sse_url(number_bfs, metadata = FALSE)

Arguments

number_bfs

The BFS number (FSO number) of a dataset.
metadata

Logical; if TRUE, returns the URL for metadata instead of data.

Value

A character string containing the URL for the API of the specified BFS number.

Get the name from an XML node for a specified language, with fallback

Description

If the specified language is not found, it falls back to the first available name.

Usage

get_xml_name(node, language)

Arguments

node

An XML node from which to extract the name.
language

The desired language code ("de", "fr", "it", "en").

Value

A character string containing the name in the specified language or the first available name.

Swiss official commune register BZN

Description

The official commune register is structured according to cantons and districts or comparable administrative entities. Various federal, cantonal and communal governments and private businesses use this register when identifying and referring to communes.

Usage

register_bzn

Format

## 'register_bzn' A data frame with 143 rows and 3 columns:

GDEKT

Kantonskuerzel

GDEBZNR

Bezirksnummer

GDEBZNA

Bezirksname

Details

The Federal Statistical Office assigns a number to each commune and creates, administers and publishes the Swiss official commune register.

Source

<https://www.bfs.admin.ch/bfs/fr/home/bases-statistiques/repertoire-officiel-communes-suisse.html>

Swiss official commune register Dictionary

Description

The official commune register is structured according to cantons and districts or comparable administrative entities. Various federal, cantonal and communal governments and private businesses use this register when identifying and referring to communes.

Usage

register_dic

Format

## 'register_dic' A data frame with 27 rows and 5 columns:

language

Language

abbreviation

Abbreviation

title

Title

spec

Specifications

notes

General notes

Details

The Federal Statistical Office assigns a number to each commune and creates, administers and publishes the Swiss official commune register.

Source

<https://www.bfs.admin.ch/bfs/fr/home/bases-statistiques/repertoire-officiel-communes-suisse.html>

Swiss official commune register GDE

Description

The official commune register is structured according to cantons and districts or comparable administrative entities. Various federal, cantonal and communal governments and private businesses use this register when identifying and referring to communes.

Usage

register_gde

Format

## 'register_gde' A data frame with 2,136 rows and 8 columns:

GDEKT

Kantonskuerzel

GDEBZNR

Bezirksnummer

GDENR

BFS-Gemeindenummer

GDENAME

Amtlicher Gemeindename

GDENAMK

Gemeindename, kurz

GDEBZNA

Bezirksname

GDEKTNA

Kantonsname

GDEMUTDAT

Datum der letzten Anderung

Details

The Federal Statistical Office assigns a number to each commune and creates, administers and publishes the Swiss official commune register.

Source

<https://www.bfs.admin.ch/bfs/fr/home/bases-statistiques/repertoire-officiel-communes-suisse.html>

Swiss official commune register GDE Other

Description

The official commune register is structured according to cantons and districts or comparable administrative entities. Various federal, cantonal and communal governments and private businesses use this register when identifying and referring to communes.

Usage

register_gde_other

Format

## 'register_gde_other' A data frame with 3 rows and 4 columns:

GDENR

BFS-Gemeindenummer

GDENAME

Amtlicher Gemeindename

KTNR

Kantonsnummer

GDEBZNR

Bezirksnummer

Details

The Federal Statistical Office assigns a number to each commune and creates, administers and publishes the Swiss official commune register.

Source

<https://www.bfs.admin.ch/bfs/fr/home/bases-statistiques/repertoire-officiel-communes-suisse.html>

Swiss official commune register KT

Description

The official commune register is structured according to cantons and districts or comparable administrative entities. Various federal, cantonal and communal governments and private businesses use this register when identifying and referring to communes.

Usage

register_kt

Format

## 'register_kt' A data frame with 26 rows and 3 columns:

KTNR

Kantonsnummer

GDEKT

Kantonskuerzel

GDEKTNA

Kantonsname

Details

The Federal Statistical Office assigns a number to each commune and creates, administers and publishes the Swiss official commune register.

Source

<https://www.bfs.admin.ch/bfs/fr/home/bases-statistiques/repertoire-officiel-communes-suisse.html>

Swiss official commune register KT Seeanteile

Description

The official commune register is structured according to cantons and districts or comparable administrative entities. Various federal, cantonal and communal governments and private businesses use this register when identifying and referring to communes.

Usage

register_kt_seeanteile

Format

## 'register_kt_seeanteile' A data frame with 9 rows and 5 columns:

GDENR

BFS-Gemeindenummer

GDENAME

Amtlicher Gemeindename

KTNR

Kantonsnummer

Details

The Federal Statistical Office assigns a number to each commune and creates, administers and publishes the Swiss official commune register.

Source

<https://www.bfs.admin.ch/bfs/fr/home/bases-statistiques/repertoire-officiel-communes-suisse.html>