Package 'pxweb'

Interface to PX-WEB APIs from R

Description

PXWEB is a common web API used by many European Statistical agencies to disseminate official statistics. The pxweb package facilitates connections and usage of these APIs.

Author(s)

Maintainer: Mans Magnusson [email protected] (ORCID)

Authors:

• Markus Kainu

• Janne Huovari

• Leo Lahti (ORCID)

Other contributors:

• Love Hansson [contributor]

• Eydun Nielsen [contributor]

• Bo Werth [contributor]

• Thomas Runarsson [contributor]

• Torbjörn Lindquist [contributor]

• Palmar Thorsteinsson [contributor]

• Pyry Kantanen [contributor]

• Sebastian Ankargren [contributor]

References

The decription of the PXWEB API here: https://www.scb.se/en/About-us/about-the-website-and-terms-of-use/open-data-api/ The official home page of PXWEB can be found here: https://www.scb.se/en/services/statistical-programs-for-px-files/px-web/

See Also

Useful links:

• https://github.com/rOpenGov/pxweb/

• https://ropengov.github.io/pxweb/

• https://github.com/rOpenGov/pxweb

• Report bugs at https://github.com/rOpenGov/pxweb/issues

---

Defunct functions

Description

These function has as from version 0.10.0 become defunct. Call the functions to get information on new functions to use.

Usage

api_catalogue()

update_pxweb_apis()

api_parameters(url = NULL)

base_url(api, version = NULL, language = NULL)

get_pxweb_data(url, dims, clean = FALSE, encoding = NULL)

get_pxweb_dims(node, verbose = TRUE)

get_pxweb_levels(baseURL, descriptions = FALSE, quiet = FALSE, ...)

get_pxweb_metadata(
  path = NULL,
  node = NULL,
  topnodes = NULL,
  quiet = TRUE,
  baseURL = NULL,
  ...
)

pxweb_api

checkForLevels(url)

Arguments

url	Defunct argument.
api	Defunct argument.
version	Defunct argument.
language	Defunct argument.
dims	Defunct argument.
clean	Defunct argument.
encoding	Defunct argument.
node	Defunct argument.
verbose	Defunct argument.
baseURL	Defunct argument.
descriptions	Defunct argument.
quiet	Defunct argument.
...	Defunct argument.
path	Defunct argument.
topnodes	Defunct argument.

Format

An object of class list of length 1.

---

Assert that a given pxweb query can be split

Description

Assert that a given pxweb query can be split

Usage

assert_query_can_be_split_to_batches(pxq, pxmd, mxv)

Arguments

pxq	a [pxweb_query] object
pxmd	a [pxweb_metadata] object
mxv	maximum batch size

---

Do a GET call to PXWEB API for advanced users

Description

Do a GET call to PXWEB API for advanced users

Usage

pxweb_advanced_get(
  url,
  query = NULL,
  verbose = TRUE,
  log_http_calls = FALSE,
  pxmdo = NULL,
  output_format = "json-stat2",
  ...
)

Arguments

url	a pxweb object or url that can be coherced to a pxweb object.
query	a json string, json file or list object that can be coherced to a pxweb_query object.
verbose	should large queries print out progress.
log_http_calls	Should the http calls to the API be logged (for debugging reasons). If TRUE, all calls and responses are logged and written to "log_pxweb_api_http_calls.txt" in the working directory.
pxmdo	A pxweb_metadata object to use for query.
output_format	output format for PXWEB API v2 data requests. Defaults to "json-stat2".
...	Further arguments sent to httr::POST (for queries) or httr::GET (for query = NULL). If used with query, also supply a pxweb_metadata object. Otherwise the same parameters are sent to both httr::POST and httr::GET.

Details

This function is intended for more advanced users that want to supply specific arguments in httr calls or what to debug httr calls.

pxweb_get() is a wrapper for standard use.

---

Audit PXWEB API catalogue config endpoints

Description

Checks whether each version and language combination in a PXWEB API catalogue entry exposes a valid config endpoint.

Usage

pxweb_audit_api_catalogue_config(
  apis = pxweb_api_catalogue(),
  timeout = 10,
  verbose = TRUE
)

Arguments

apis	a list of pxweb_api_catalogue_entry elements
timeout	Time limit in seconds for each config endpoint request.
verbose	Print progress while auditing.

Value

A data.frame with one row per catalogue URL.

---

Cite a PXWEB data object

Description

Cite a PXWEB data object

Usage

pxweb_cite(x, style = "citation")

Arguments

x	a pxweb_data or pxweb_data_v2 object to cite.
style	see bibentry.

Details

Functionality to automatic cite PXWEB data objects.

---

List PXWEB API v2 codelists in metadata.

Description

Extracts aggregation and value set codelists from a PXWEB API v2 metadata object. Use the returned id values with pxweb_aggregation or pxweb_valueset.

Usage

pxweb_codelists(x, variable = NULL, type = NULL)

Arguments

x	a pxweb_metadata object created from PXWEB API v2 metadata, or a raw PXWEB API v2 metadata list.
variable	optional variable code or label to filter on.
type	optional codelist type to filter on, for example "Aggregation" or "Valueset".

Value

A data.frame with columns variable_code, variable_text, id, label, type, and href.

Examples

## Not run: 
meta <- pxweb_get("https://statistikdatabasen.scb.se/api/v2/tables/TAB5974/metadata?lang=sv")
pxweb_codelists(meta, variable = "Alder")

## End(Not run)

---

Do a GET call to PXWEB API

Description

Do a GET call to PXWEB API

Usage

pxweb_get(url, query = NULL, verbose = TRUE, output_format = "json-stat2")

Arguments

url	a pxweb object or url that can be coherced to a pxweb object.
query	a json string, json file or list object that can be coherced to a pxweb_query object.
verbose	should large queries print out progress.
output_format	output format for PXWEB API v2 data requests. Defaults to "json-stat2".

Value

If query = NULL, returns metadata about the API path: a pxweb_levels object for API branches or a pxweb_metadata object for data tables. If query is supplied, returns the parsed data response, typically a pxweb_data, pxweb_data_jsonstat, pxweb_data_jsonstat2, or pxweb_data_v2 object depending on the API version and response format. File-based response formats, such as "px" and "sdmx", are written to a temporary file and the file path is returned. Returns NULL if the URL host cannot be reached.

Examples

## Not run: 
url <- "https://api.scb.se/OV0104/v1/doris/sv/ssd/BE/BE0101/BE0101A/BefolkningNy"
px_meta_data <- pxweb_get(url)

url <- "https://api.scb.se/OV0104/v1/doris/sv/ssd/BE/BE0101"
px_levels <- pxweb_get(url)

url <- "https://api.scb.se/OV0104/v1/doris/sv"
px_levels <- pxweb_get(url)

url <- "https://api.scb.se/OV0104/v1/doris/sv/ssd/BE/BE0101/BE0101A/BefolkningNy"
query <- file.path(
  system.file(package = "pxweb"),
  "extdata", "examples", "json_query_example.json"
)
px_data <- pxweb_get(url = url, query = query)

# Convert to data.frame
as.data.frame(px_data, column.name.type = "text", variable.value.type = "text")

# Get raw data
as.matrix(px_data, column.name.type = "code", variable.value.type = "code")

# Get data comments
pxweb_data_comments(px_data)

# Get jsonstat data
jstat <- query <- file.path(
  system.file(package = "pxweb"),
  "extdata", "examples", "json-stat_query_example.json"
)
jstat_data <- pxweb_get(url = url, query = query)

# Get very large datasets (multiple downloads needed)
big_query <- file.path(
  system.file(package = "pxweb"),
  "extdata", "examples", "json_big_query_example.json"
)
px_data <- pxweb_get(url = url, query = big_query)

# Get json-stat2 data from StatFin using a downloaded json query
jstat2_url <- "https://pxdata.stat.fi/PxWeb/api/v1/en/StatFin/vaenn/139e.px"
jstat2_query <- file.path(
  system.file(package = "pxweb"),
  "extdata", "examples", "statfin_vaenn_139e_query.json"
)
jstat2_data <- pxweb_get(url = jstat2_url, query = jstat2_query)

## End(Not run)

---

Do a GET call to PXWEB API and return a data.frame

Description

Do a GET call to PXWEB API and return a data.frame

Usage

pxweb_get_data(
  url,
  query,
  verbose = TRUE,
  column.name.type = "text",
  variable.value.type = "text",
  output_format = "json-stat2"
)

Arguments

url	a pxweb object or url that can be coherced to a pxweb object.
query	a json string, json file or list object that can be coherced to a pxweb_query object.
verbose	should large queries print out progress.
column.name.type	character: should code or text be used as column names?
variable.value.type	character: should code or text be used as values in columns?
output_format	output format for PXWEB API v2 data requests. Defaults to "json-stat2".

Details

The functions use will do a pxweb_query to a PXWEB url and return a data.frame. This is a wrapper for the pxweb_get function.

See Also

See pxweb_get for mor general usage and pxweb_query for details on PXWEB queries.

Examples

## Not run: 
url <- "https://api.scb.se/OV0104/v1/doris/sv/ssd/BE/BE0101/BE0101A/BefolkningNy"
query <- file.path(
  system.file(package = "pxweb"),
  "extdata", "examples", "json_query_example.json"
)
df <- pxweb_get_data(url = url, query = query)

## End(Not run)

---

Find and download data interactively from a PXWEB API

Description

Wrapper function (for pxweb_get) to simply find and download data to the current R session. interactive_pxweb() is a deprecated alias for pxweb_interactive().

Usage

pxweb_interactive(x = NULL)

interactive_pxweb(x = NULL)

Arguments

x	The name or alias of the pxweb api to connect to, a pxweb object or an url.

Value

Invisibly returns a list with at least:

url

The URL to the selected data table.

query

A pxweb_query object that can be passed to pxweb_get.

If data is downloaded during the interactive session, the list also includes data, containing the downloaded data object returned by pxweb_get. This return value is not the same as calling pxweb_get() directly.

See Also

pxweb_get

Examples

pxweb_api_catalogue() # List apis

## The examples below can only be run in interactive mode
##  x <- pxweb_interactive()
##  x <- pxweb_interactive(x = "api.scb.se")
##  x <- pxweb_interactive(x = "https://api.scb.se/OV0104/v1/doris/en/ssd/BE/BE0101/")
##  x <- pxweb_interactive(x = "https://api.scb.se/OV0104/v1/doris/en/ssd/BE/BE0101/BE0101A/")

---

Parse the response from a PXWEB API (advanced)

Description

The function parses the response from a call made to a PXWEB API using the httr R package. In this way it is possible to parse the content of calls made outside the pxweb R package.

Usage

pxweb_parse_response(x)

is_pxweb_response(x)

Arguments

x	a httr response object from a PXWEB call.

---

Convert a pxweb_query object to a json string

Description

Convert a pxweb_query object to a json string

Usage

pxweb_query_as_json(pxq, ...)

Arguments

pxq	a pxweb_query object.
...	further argument to jsonlite::toJSON().

See Also

pxweb_query, pxweb_query_as_rcode

Examples

json_query <- file.path(
  system.file(package = "pxweb"),
  "extdata", "examples", "json_query_example.json"
)
pxq <- pxweb_query(json_query)
json <- pxweb_query_as_json(pxq, pretty = TRUE)

---

Print a pxweb_query object as R code

Description

Print a pxweb_query object as R code

Usage

pxweb_query_as_rcode(pxq)

Arguments

pxq	a pxweb_query object.

See Also

pxweb_query_as_json, pxweb_query

---

PXWEB API v2 query helpers

Description

Helper functions for expressing PXWEB API v2 query selections without relying on magic strings in user code.

Usage

pxweb_all()

pxweb_latest(code = "9999")

pxweb_aggregation(
  id,
  value_codes = "*",
  output_values = c("aggregated", "single")
)

pxweb_valueset(
  id,
  value_codes = "*",
  output_values = c("aggregated", "single")
)

pxweb_top(n)

pxweb_bottom(n)

Arguments

code	placeholder value used before the latest available value is resolved against table metadata. The default "9999" is replaced by the last metadata value before the v2 data request is sent.
id	codelist id, for example an aggregation id returned by a PXWEB API v2 metadata response.
value_codes	value codes to request from the selected codelist.
output_values	whether the API should return aggregated values or single values for the codelist.
n	number of values to request.

Value

A pxweb_query_selection object.

Examples

query <- list(
  Region = pxweb_all(),
  Alder = pxweb_aggregation("agg_Ålder5år_1"),
  Tid = pxweb_latest()
)

---

Search PXWEB API tables

Description

Search for tables in a PXWEB API. PXWEB API v2 search uses the standard /tables?query= endpoint. PXWEB API v1 search is supported for API database roots that expose search, such as Statistics Finland.

Usage

pxweb_search(
  query,
  api_url,
  lang = NULL,
  page_number = 1,
  page_size = NULL,
  past_days = NULL,
  include_discontinued = FALSE,
  ...
)

Arguments

query	a search string.
api_url	a PXWEB API root URL. For v2, use an API root such as "https://statistikdatabasen.scb.se/api/v2". For v1, use a searchable database root such as "https://pxdata.stat.fi/PxWeb/api/v1/en/StatFin".
lang	language code for PXWEB API v2. For v1, the language is part of api_url.
page_number	page number for PXWEB API v2 searches.
page_size	page size for PXWEB API v2 searches.
past_days	if supplied, restrict PXWEB API v2 searches to tables updated in the last past_days days.
include_discontinued	include discontinued PXWEB API v2 tables.
...	further arguments passed to httr::GET.

Value

a data.frame with search hits and table URLs.

Examples

## Not run: 
pxweb_search(
  "population",
  api_url = "https://statistikdatabasen.scb.se/api/v2",
  lang = "en"
)

pxweb_search(
  "population",
  api_url = "https://pxdata.stat.fi/PxWeb/api/v1/en/StatFin"
)

## End(Not run)

---

Create a PXWEB query selection

Description

Creates a query selection for use inside a named list passed to pxweb_query or pxweb_get. This is useful when a PXWEB table requires an explicit API filter such as an aggregation or value set filter.

Usage

pxweb_selection(filter = "item", values)

Arguments

filter	a PXWEB selection filter, for example "item", "all", "agg:_Regions 2026.agg", or "vs:Some valueset".
values	selected value codes for the filter.

Value

A pxweb_query_selection_filter object.

Examples

query <- list(
  alue_23_20260101 = pxweb_selection("agg:_Regions 2026.agg", "MK01"),
  timeperiod_y = "2025"
)

pxq <- pxweb_query(query)

---

Test a full or a part of a PXWEB api.

Description

The function can be used to test a whole pxweb api by using the api base url. By using a branch in a tree the api is tested below this branch.

Usage

pxweb_test_api(
  url,
  test_type = "first",
  n = 1,
  verbose = TRUE,
  time_limit = Inf
)

Arguments

url	The base url to the pxweb api (or a branch of the metadata tree)
test_type	What type of test should be done. The first observation of each table. A random sample of size n. Download all full tables. touch the api by only downloading the first table metadata. This is minimal testing of the API.
n	sample size if test_type is sample.
verbose	The function will print information.
time_limit	Time limit in second the API is allowed to be tested.

Value

Function returns a data.frame with information on each node Two variables are added: checked : The node has been checked error : Whether there were errors encountered with the call download_error : Whether there were errors encountered during download

Examples

## Not run: 
url <- "https://bank.stat.gl/api/v1/en/Greenland/BE/BE01"
res <- pxweb_test_api(url)
res <- pxweb_test_api(url, test_type = "touch")

## End(Not run)

---

Validate a pxweb_query with a pxweb_metadata object

Description

Validate a pxweb_query with a pxweb_metadata object

Usage

pxweb_validate_query_with_metadata(pxq, pxmd)

Arguments

pxq	a pxweb_query object.
pxmd	a pxweb_metadata object.

Details

Validate a query with a metadata object to asses that the query can be used to query the table.

Examples

## Not run: 
url <- "https://api.scb.se/OV0104/v1/doris/sv/ssd/BE/BE0101/BE0101A/BefolkningNy"
json_query <- file.path(
  system.file(package = "pxweb"),
  "extdata", "examples", "json_query_example.json"
)
pxq <- pxweb_query(json_query)
pxweb_validate_query_with_metadata(pxq, pxweb_get(url))

## End(Not run)

---