Help for package pxweb

Type:

Package

Title:

R Interface to PXWEB APIs

Version:

0.19.2

Date:

2026-09-05

Description:

Generic interface for the PX-Web/PC-Axis API. The PX-Web/PC-Axis API is used by organizations such as Statistics Sweden and Statistics Finland to disseminate data. The R package can interact with all PX-Web/PC-Axis APIs to fetch information about the data hierarchy, extract metadata and extract and parse statistics to R data.frame format. PX-Web is a solution to disseminate PC-Axis data files in dynamic tables on the web. Since 2013 PX-Web contains an API to disseminate PC-Axis files.

License:

BSD_2_clause + file LICENSE

URL:

https://github.com/rOpenGov/pxweb/, https://ropengov.github.io/pxweb/, https://github.com/rOpenGov/pxweb

BugReports:

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

Depends:

R (≥ 3.5.0)

Imports:

checkmate, curl, httr (≥ 1.1), jsonlite

Suggests:

digest, httptest, knitr, remotes, rmarkdown, testthat (≥ 3.1.7), xml2

VignetteBuilder:

knitr

Encoding:

UTF-8

RoxygenNote:

7.3.3

X-schema.org-isPartOf:

http://ropengov.org/

X-schema.org-keywords:

ropengov

NeedsCompilation:

Packaged:

2026-09-05 18:00:27 UTC; manma760

Author:

Mans Magnusson

[aut, cre], Markus Kainu [aut], Janne Huovari [aut], Leo Lahti

[aut], Love Hansson [ctb], Eydun Nielsen [ctb], Bo Werth [ctb], Thomas Runarsson [ctb], Torbjörn Lindquist [ctb], Palmar Thorsteinsson [ctb], Pyry Kantanen [ctb], Sebastian Ankargren [ctb]

Maintainer:

Mans Magnusson <mons.magnusson@gmail.com>

Repository:

CRAN

Date/Publication:

2026-09-06 11:00:02 UTC

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 mons.magnusson@gmail.com (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/

Add default values to pxe

Description

Add default values to pxe

Usage

add_pxe_defaults(pxe)

Arguments

pxe

a pxweb_explorer object

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 x is a correct `pxweb_database_list` object.

Description

Assert that x is a correct pxweb_database_list object.

Usage

as_pxweb_levels(x)

Arguments

x

an object to check.

Assert that the url structure is correct

Description

Assert that the url slot in the pxweb object is correct.

Usage

assert_pxweb(x)

Arguments

x

a object to assert

Assert a `pxweb_api_catalogue` object

Description

Assert a pxweb_api_catalogue object

Usage

assert_pxweb_api_catalogue(x)

Arguments

x

an object to assert is a pxweb_api_catalogue_entry.

Assert that the rda_file_path is correct

Description

Assert that the rda_file_path slot in the pxweb object is correct.

Usage

assert_pxweb_calls(x)

Arguments

x

a object to assert

Assert that the config slot is correct

Description

Assert that the config slot in the pxweb object is correct.

Usage

assert_pxweb_config(x)

Arguments

x

a object to assert

Assert that x is a correct `pxweb_data` object.

Description

Assert that x is a correct pxweb_data object.

Usage

assert_pxweb_data(x)

Arguments

x

an object to check.

Assert that x is a correct `pxweb_data_comments` object.

Description

Assert that x is a correct pxweb_data_comments object.

Usage

assert_pxweb_data_comments(x)

Arguments

x

an object to check.

Assert that x is a correct `pxweb_data_jsonstat` object. Assert a json-stat version 1.0 or later object

Description

Assert that x is a correct pxweb_data_jsonstat object. Assert a json-stat version 1.0 or later object

Usage

assert_pxweb_data_jsonstat(x)

Arguments

x

an object to check.

Assert that x is a PXWEB API v2 JSON-stat2 data response.

Description

Assert that x is a PXWEB API v2 JSON-stat2 data response.

Usage

assert_pxweb_data_jsonstat2(x)

Arguments

x

an object to check.

Assert that x is a correct `pxweb_database_list` object.

Description

Assert that x is a correct pxweb_database_list object.

Usage

assert_pxweb_database_list(x)

Arguments

x

an object to check.

Assert a `pxweb_input_allowed` object

Description

Assert a pxweb_input_allowed object

Usage

assert_pxweb_input_allowed(x)

## S3 method for class 'pxweb_input_allowed'
print(x, ...)

Arguments

x

an object to assert.

Assert that x is a correct `pxweb_levels` object.

Description

Assert that x is a correct pxweb_levels object.

Usage

assert_pxweb_levels(x)

Arguments

x

an object to check.

Assert that x is a correct `pxweb_metadata` object.

Description

Assert that x is a correct pxweb_metadata object.

Usage

assert_pxweb_metadata(x)

Arguments

x

an object to check.

Assert that x is a PXWEB API v2 metadata response.

Description

Assert that x is a PXWEB API v2 metadata response.

Usage

assert_pxweb_metadata_response_v2(x)

Arguments

x

an object to check.

Assert a pxweb_query object

Description

Assert a pxweb_query object

Usage

assert_pxweb_query(x, check_response_format = TRUE)

Arguments

x

an object to assert conferms to the structure of an pxweb_query object.

Assert a `pxweb_query_v2` object.

Description

Assert a pxweb_query_v2 object.

Usage

assert_pxweb_query_v2(x)

Arguments

x

an object to check.

Assert that the rda_file_path is correct

Description

Assert that the rda_file_path slot in the pxweb object is correct.

Usage

assert_pxweb_rda_file_path(x)

Arguments

x

a object to assert

Assert that x is a correct `pxweb_table_response_v2` object.

Description

Assert that x is a correct pxweb_table_response_v2 object.

Usage

assert_pxweb_table_response_v2(x)

Arguments

x

an object to check.

Assert that the url structure is correct

Description

Assert that the url slot in the pxweb object is correct.

Usage

assert_pxweb_url(x)

Arguments

x

a object to assert

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

Build or get the tmp_rda_file_path from an url or pxweb_api_s3 object

Description

Build or get the tmp_rda_file_path from an url or pxweb_api_s3 object

Usage

build_pxweb_rda_file_path(x)

## S3 method for class 'character'
build_pxweb_rda_file_path(x)

## S3 method for class 'url'
build_pxweb_rda_file_path(x)

## S3 method for class 'pxweb'
build_pxweb_rda_file_path(x)

## S3 method for class 'list'
build_pxweb_rda_file_path(x)

Arguments

x

object to create tmp_file_path for.

Details

The hostname is used to

Build the url to a PXWEB api

Description

Build the url to a PXWEB api

Usage

build_pxweb_url(x)

## S3 method for class 'list'
build_pxweb_url(x)

## S3 method for class 'character'
build_pxweb_url(x)

## S3 method for class 'pxweb'
build_pxweb_url(x)

## S3 method for class 'pxweb_api_catalogue_entry'
build_pxweb_url(x)

Build the url to get the config from a PXWEB api

Description

Build the url to get the config from a PXWEB api

Usage

## S3 method for class 'url'
build_pxweb_url(x)

build_pxweb_config_url(x)

## S3 method for class 'list'
build_pxweb_config_url(x)

## S3 method for class 'pxweb'
build_pxweb_config_url(x)

## S3 method for class 'url'
build_pxweb_config_url(x)

Build the url to a PXWEB V2 API SUBPATH

Description

Build the url to a PXWEB V2 API SUBPATH

Usage

build_pxweb_v2_api_subpath(x)

## S3 method for class 'url'
build_pxweb_v2_api_subpath(x)

Generate batch permutations

Description

Generate batch permutations

Usage

generate_permutations(x)

Arguments

x

a vector with elements to permute

Details

Generates permutations of dim. If more than 6 dim (highly unlikely) a sample of 1000 combinations is drawn. Otherwise all possible permutations are returned.

http_was_redirected

Description

http_was_redirected

Usage

http_was_redirected(r)

Arguments

r

an httr response object, e.g. from a call to httr::GET()

Value

list with slots was_redirected, redirected_from and redirected_to

References

Function in large parts taken from petermeissner.de/blog/2018/11/07/using-httr-to-detect-redirects/.

Examples

## Not run: 
r <- httr::GET("http://httpbin.org/redirect/2")
pxweb:::http_was_redirected(r)

## End(Not run)

Check if a response is a pxweb config response

Description

Check if a response is a pxweb config response

Usage

is_pxweb_config_response(x, version)

Arguments

x

a response object

version

the version of the pxweb API to check for

Test for PXWEB API v2 query selection helpers.

Description

Test for PXWEB API v2 query selection helpers.

Usage

is_pxweb_query_selection(x)

Arguments

x

an object to check.

Parse a character string or throws error if it fails

Description

Parse a character string or throws error if it fails

Usage

parse_url_or_fail(x)

Arguments

x

a character element to parse

Generate permutations of dimensions to find optimal no of batches

Description

Generate permutations of dimensions to find optimal no of batches

Usage

permutations(n, r, v = 1:n, set = TRUE, repeats.allowed = FALSE)

Arguments

n

See gtools::permutations.

r

See gtools::permutations.

v

See gtools::permutations.

set

See gtools::permutations.

repeats.allowed

See gtools::permutations.

Details

Taken from gtools to minimize dependencies. See permutations of the gtools packages for details

Print a catalogue entry

Description

Print a catalogue entry

Usage

## S3 method for class 'pxweb_api_catalogue_entry'
print(x, ...)

Arguments

x

an object used to select a method.

...

further arguments passed to or from other methods.

Convert a pxweb data objects values to valuetext

Description

Convert a pxweb data objects values to valuetext

Usage

pxd_values_to_valuetexts(x, variable_code, variable_vector)

Arguments

x

a pxweb_data object

variable_code

the variable name of the variable to convert. NOTE! Need to be the variable code.

variable_vector

the vector with the variables to convert.

Defines allowed input for a position in a `pxweb_explorer` or character object.

Description

Defines allowed input for a position in a pxweb_explorer or character object.

Usage

pxe_allowed_input(x)

pxe_allowed_input_df()

## S3 method for class 'pxweb_explorer'
pxe_allowed_input(x)

## S3 method for class 'character'
pxe_allowed_input(x)

## S3 method for class 'pxweb_explorer'
pxe_allowed_input(x)

Arguments

x

a object to get allowed input for.

Move in the `pxweb_explorer` position

Description

Move in the pxweb_explorer position

Usage

pxe_back_position(pxe)

pxe_add_position(pxe, new_pos)

Arguments

pxe

a pxweb_explorer object.

new_pos

add a new position.

Details

pxe_back_position moves back one position and pxe_add_position moves forward, based on user choice.

Get the url to a table

Description

Get the url to a table

Usage

pxe_data_url(x)

Arguments

x

a pxweb_explorer object

Handle a user input for a `pxweb_explorer` object.

Description

Handle a user input for a pxweb_explorer object.

Usage

pxe_handle_input(user_input, pxe)

## S3 method for class 'numeric'
pxe_handle_input(user_input, pxe)

## S3 method for class 'character'
pxe_handle_input(user_input, pxe)

Arguments

user_input

an (allowed) user input to handle.

pxe

a pxweb_explorer object to get user input for.

Get (allowed) inputs for a `pxweb_input_allowed` object.

Description

Get (allowed) inputs for a pxweb_input_allowed object.

Usage

pxe_input(allowed_input, title = NULL, test_input = NULL)

pxe_parse_input(user_input, allowed_input)

Arguments

allowed_input

a pxweb_input_allowed.

title

Print (using cat()) before ask for the allowed choices.

test_input

supplying a test input (for testing only)

Details

It handles input and checks if the input is allowed.

Ask to download and download data

Description

Ask to download and download data

Usage

pxe_interactive_get_data(pxe, test_input = NULL)

Arguments

pxe

a pxweb_explorer object with full query

test_input

a test input for testing the function. Since two question, supply a vector of length two.

Get and set pxe_metadata_coices

Description

Get and set pxe_metadata_coices

Usage

pxe_metadata_choices(x)

pxe_metadata_choices(x) <- value

Arguments

x

a pxweb_explorer object

value

an object to set as pxe_metadata_choice

Get the meta data variable names from a `pxweb_explorer` object.

Description

Get the meta data variable names from a pxweb_explorer object.

Usage

pxe_metadata_variable_names(x)

Arguments

x

a pxweb_explorer object

How many choices has the current position?

Description

How many choices has the current position?

Usage

pxe_position_choice_size(x)

pxe_position_print_size(x)

Arguments

x

a pxweb_explorer object to check.

Is the current position an api_catalogue position?

Description

Is the current position an api_catalogue position?

Usage

pxe_position_is_api_catalogue(x)

Arguments

x

a pxweb_explorer object to check.

Is the current position a full query (i.e. choices for all metadata variables)?

Description

Is the current position a full query (i.e. choices for all metadata variables)?

Usage

pxe_position_is_full_query(x)

Arguments

x

a pxweb_explorer object to check.

Is the current position a metadata object?

Description

Is the current position a metadata object?

Usage

pxe_position_is_metadata(x)

Arguments

x

a pxweb_explorer object to check.

Are multiple choices allowed?

Description

Are multiple choices allowed?

Usage

pxe_position_multiple_choice_allowed(x)

Arguments

x

a pxweb_explorer object to check.

Get the table title for the current position

Description

Get the table title for the current position

Usage

pxe_position_title(x)

Arguments

x

a pxweb_explorer object.

Can the variable at the current position be eliminated?

Description

Can the variable at the current position be eliminated?

Usage

pxe_position_variable_can_be_eliminated(x)

Arguments

x

a pxweb_explorer object to check.

Print code to download query

Description

Print code to download query

Usage

pxe_print_download_code(pxe, as)

Arguments

pxe

a pxweb_query object.

as

json or r.

Return the pxweb object at the current position

Description

Return the pxweb object at the current position

Usage

pxe_pxobj_at_position(x)

pxe_pxobj_at_position(x) <- value

Arguments

x

a pxweb_explorer object.

S3 constructor for `pxweb` api object.

Description

The pxwebapi object contain all information to do calls to the pxweb api and keep count of the number of calls. The object is constructed The object will also be cached in R temp folder to minimize calls to api. All urls should be passed through the constructor to set up the pxweb api config.

Garantuees: The base_url has been pinged The sub_path has been checked The config has been captured from the API The url has been checked to be a pxweb api (through config)

Usage

pxweb(url)

is.pxweb(x)

## S3 method for class 'pxweb'
print(x, ...)

Arguments

url

an url to a pxweb api including language and version of the api. See examples.

x

an an object to test if it is a pxweb object.

...

further arguments supplied to print().

Value

A pxweb object.

Examples

## Not run: 
pxapi_1 <-
  pxweb("https://api.scb.se/OV0104/v1/doris/sv/ssd/START/ME/ME0104/ME0104C/ME0104T24")
pxapi_2 <-
  pxweb(url = "https://api.scb.se/OV0104/v1/doris/sv")

## End(Not run)

Add the subpath slot to a pxweb path slot

Description

Add the subpath slot to a pxweb path slot

Usage

pxweb_add_api_subpath(obj)

Arguments

obj

an object to add subpath to

Details

Queries the path from pos 1 and up until a config is returned.

Add an api call to a pxweb_api_s3 object

Description

The pxweb_add_call function add a call the the api in the call stack, then compute

Promise: The stored rda api object will always have the latest calls This is not thread safe so only one session at a time should call the api.

Usage

pxweb_add_call(obj, time_stamp = Sys.time())

Arguments

obj

a pxweb_api_s3 object

Add the config slot to a pxweb object

Description

Add the config slot to a pxweb object

Usage

pxweb_add_config(obj)

Arguments

obj

an object to add config to

Details

Checks if there exist a config object in the object. Otherwise it query the api to get it and add that call to the call stack.

Add mandatory variables to query

Description

Add mandatory variables to query

Usage

pxweb_add_mandatory_variables(pxq, pxmd)

Arguments

pxq

a pxweb_query object.

pxmd

a pxweb_metadata object.

Details

Complement queries that lack explicit requests for variables with requests for every value of these variables.

Add and remove metadata to query

Description

Add and remove metadata to query

Usage

pxweb_add_metadata_to_query(pxq, pxmd)

pxweb_remove_metadata_from_query(pxq, pxmd)

Arguments

pxq

a pxweb_query object.

pxmd

a pxweb_metadata object.

Details

Add metadata values to variables with a query with filter "all".

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.

Get the PXWEB API catalogue

Description

Get the PXWEB API catalogue

Usage

pxweb_api_catalogue()

pxweb_api_catalogue_from_json(json)

pxweb_api_catalogue_from_github(branch = "master")

pxweb_api_catalogue_path()

Details

A list with implemented API:s.

Examples

pxweb_api_catalogue()

Constructor for `pxweb_api_catalogue_entry`.

Description

Constructor for pxweb_api_catalogue_entry.

Usage

pxweb_api_catalogue_entry(x)

## S3 method for class 'list'
pxweb_api_catalogue_entry(x)

assert_pxweb_api_catalogue_entry(x)

Arguments

x

an object to assert is a pxweb_api_catalogue_entry.

Get the api name, rootpath, subpath, path or dbpath

Description

Get the api name, rootpath, subpath, path or dbpath

Usage

pxweb_api_name(x)

## S3 method for class 'url'
pxweb_api_name(x)

## S3 method for class 'pxweb'
pxweb_api_name(x)

## S3 method for class 'pxweb_api_catalogue_entry'
pxweb_api_name(x)

## S3 method for class 'pxweb_explorer'
pxweb_api_name(x)

pxweb_api_rootpath(x)

## S3 method for class 'url'
pxweb_api_rootpath(x)

## S3 method for class 'pxweb'
pxweb_api_rootpath(x)

## S3 method for class 'pxweb_explorer'
pxweb_api_rootpath(x)

pxweb_api_subpath(x, init_slash = TRUE, as_vector = FALSE)

## S3 method for class 'pxweb'
pxweb_api_subpath(x, init_slash = TRUE, as_vector = FALSE)

## S3 method for class 'pxweb_explorer'
pxweb_api_subpath(x, init_slash = TRUE, as_vector = FALSE)

pxweb_api_path(x, init_slash = TRUE, as_vector = FALSE)

## S3 method for class 'url'
pxweb_api_path(x, init_slash = TRUE, as_vector = FALSE)

## S3 method for class 'pxweb'
pxweb_api_path(x, init_slash = TRUE, as_vector = FALSE)

## S3 method for class 'pxweb_explorer'
pxweb_api_path(x, init_slash = TRUE, as_vector = FALSE)

pxweb_api_dbpath(x, init_slash = TRUE, as_vector = FALSE)

## S3 method for class 'pxweb'
pxweb_api_dbpath(x, init_slash = TRUE, as_vector = FALSE)

## S3 method for class 'pxweb_explorer'
pxweb_api_path(x, init_slash = TRUE, as_vector = FALSE)

assert_path(x)

pxe_position_path(
  x,
  init_slash = TRUE,
  as_vector = FALSE,
  include_rootpath = FALSE
)

pxe_metadata_path(x, as_vector = FALSE)

Arguments

x

object to get the name or path for

init_slash

should subpath and path start with a /. Default is TRUE.

as_vector

should subpath and path be a vector split by /. Default is FALSE.

include_rootpath

Should the rootpath be included? Default is FALSE

Details

The PXWEB API contain the following path: API-NAME/API-VERSION/LANGUAGE/DATABASE-ID/<LEVELS>/TABLE-ID

The full url is made up by the rootpath, subpath, and path. The rootpath is made up of the protocol and the API-NAME / hostname and protocol (if any).

The subpath contain the API-VERSION and LANGUAGE but can contain other parts as well. The subpath is the shortest the config can be called for. It can be seen as the base for the API.

The dbpath, the data base path, contain DATABASE-ID/<LEVELS>/TABLE-ID.

The path, is the standar path of an url, i.e. subpath + dbpath.

No path ends with slash, but subpath and dbpath may begin with slash, see the parameters

Coerce a `pxweb_data` object to a `data.frame`

Description

Coerce a pxweb_data object to a data.frame

Usage

pxweb_as_data_frame(
  x,
  row.names = NULL,
  optional = FALSE,
  ...,
  stringsAsFactors = FALSE,
  column.name.type = "text",
  variable.value.type = "text"
)

## S3 method for class 'pxweb_data'
pxweb_as_data_frame(
  x,
  row.names = NULL,
  optional = FALSE,
  ...,
  stringsAsFactors = FALSE,
  column.name.type = "text",
  variable.value.type = "text"
)

## S3 method for class 'pxweb_data_v2'
pxweb_as_data_frame(
  x,
  row.names = NULL,
  optional = FALSE,
  ...,
  stringsAsFactors = FALSE,
  column.name.type = "text",
  variable.value.type = "text"
)

## S3 method for class 'pxweb_data_comments'
pxweb_as_data_frame(
  x,
  row.names = NULL,
  optional = FALSE,
  ...,
  stringsAsFactors = FALSE
)

## S3 method for class 'pxweb_data_comment'
pxweb_as_data_frame(
  x,
  row.names = NULL,
  optional = FALSE,
  ...,
  stringsAsFactors = FALSE
)

## S3 method for class 'pxweb_levels'
pxweb_as_data_frame(
  x,
  row.names = NULL,
  optional = FALSE,
  ...,
  stringsAsFactors = FALSE
)

## S3 method for class 'pxweb_data'
as.data.frame(
  x,
  row.names = NULL,
  optional = FALSE,
  ...,
  stringsAsFactors = FALSE,
  column.name.type = "text",
  variable.value.type = "text"
)

## S3 method for class 'pxweb_data_v2'
as.data.frame(
  x,
  row.names = NULL,
  optional = FALSE,
  ...,
  stringsAsFactors = FALSE,
  column.name.type = "text",
  variable.value.type = "text"
)

## S3 method for class 'pxweb_data_comments'
as.data.frame(
  x,
  row.names = NULL,
  optional = FALSE,
  ...,
  stringsAsFactors = FALSE
)

## S3 method for class 'pxweb_levels'
as.data.frame(
  x,
  row.names = NULL,
  optional = FALSE,
  ...,
  stringsAsFactors = FALSE
)

## S3 method for class 'pxweb_metadata'
as.data.frame(
  x,
  row.names = NULL,
  optional = FALSE,
  ...,
  stringsAsFactors = FALSE
)

pxweb_as_matrix(
  x,
  row.names = NULL,
  column.name.type = "text",
  variable.value.type = "text"
)

## S3 method for class 'pxweb_data'
pxweb_as_matrix(
  x,
  row.names = NULL,
  column.name.type = "text",
  variable.value.type = "text"
)

## S3 method for class 'pxweb_data_v2'
pxweb_as_matrix(
  x,
  row.names = NULL,
  column.name.type = "text",
  variable.value.type = "text"
)

## S3 method for class 'pxweb_data'
as.matrix(
  x,
  ...,
  row.names = NULL,
  column.name.type = "text",
  variable.value.type = "text"
)

## S3 method for class 'pxweb_data_v2'
as.matrix(
  x,
  ...,
  row.names = NULL,
  column.name.type = "text",
  variable.value.type = "text"
)

pxweb_pxd_slot_idx_pos(x)

Arguments

x

an object to convert to data.frame.

row.names

See as.data.frame.

optional

See as.data.frame.

...

See as.data.frame.

stringsAsFactors

See as.data.frame.

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?

Convert object to json

Description

Convert object to json

Usage

pxweb_as_json(x)

## S3 method for class 'pxweb_query'
pxweb_as_json(x)

## S3 method for class 'pxweb_query_v2'
pxweb_as_json(x)

Arguments

x

an object to convert.

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.

Combine pxweb objects

Description

Combine pxweb objects

Usage

pxweb_c(x)

Arguments

x

a list with pxweb objects.

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.

Clear cache of all (or one) `pxweb` object

Description

Clear cache of all (or one) pxweb object

Usage

pxweb_clear_cache(x = NULL)

Arguments

x

a pxweb object to clear cache for. Default is NULL (clear everything).

Details

Clean the cache and sleep to restore api timing limit.

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)

Construct a `pxweb_data` object.

Description

An object that contain the data for a given PXWEB table.

Usage

pxweb_data(x)

Arguments

x

a list returned from a PXWEB API to convert to a pxweb_data object.

Value

a pxweb_data object

Combine pxweb objects

Description

Combine pxweb objects

Usage

pxweb_data_c(x)

Arguments

x

a list with pxweb objects.

Get query filter

Description

Get query filter

Usage

pxweb_data_colnames(pxd, type = "text")

## S3 method for class 'pxweb_data'
pxweb_data_colnames(pxd, type = "text")

## S3 method for class 'pxweb_data_v2'
pxweb_data_colnames(pxd, type = "text")

Arguments

pxd

a pxweb_data object.

Value

character vector with column names.

Construct a `pxweb_data_comment` object

Description

Construct a pxweb_data_comment object

Usage

pxweb_data_column_comment(x, column_idx)

pxweb_data_value_comment(x, comment_idx)

pxweb_data_obs_comment(x, obs_idx)

Arguments

x

an pxweb_data to extract a pxweb_data_comment object from.

column_idx

the index of the column to extract.

comment_idx

the index of the comment to extract.

obs_idx

the index of the comment to extract.

Construct a `pxweb_data_comments` object.

Description

An object that contain the comments for a given PXWEB table.

Usage

pxweb_data_comments(x)

## S3 method for class 'pxweb_data'
pxweb_data_comments(x)

## S3 method for class 'pxweb_data_v2'
pxweb_data_comments(x)

Arguments

x

a pxweb_data object.

Value

a pxweb_data_comments object

Examples

## Not run: 
url <- "https://api.scb.se/OV0104/v1/doris/en/ssd/BE/BE0101/BE0101A/BefolkningNy"
json_query <-
  file.path(system.file(package = "pxweb"), "extdata", "examples", "json_query_example.json")
pxd <- pxweb_get(url = url, query = json_query)
pxdcs <- pxweb_data_comments(x = pxd)
pxdc_df <- as.data.frame(pxdcs, stringsAsFactors = TRUE)

## End(Not run)

Compute the dimension of the query `pxweb_data` object

Description

Compute the dimension of the query pxweb_data object

Usage

pxweb_data_dim(pxd)

## S3 method for class 'pxweb_data'
pxweb_data_dim(pxd)

## S3 method for class 'pxweb_data_v2'
pxweb_data_dim(pxd)

Arguments

pxd

a pxweb_data object.

Construct a `pxweb_data_jsonstat` object.

Description

An object that contain the data for a given PXWEB table.

Usage

pxweb_data_jsonstat(x)

Arguments

x

a list returned from a PXWEB API to convert to a pxweb_data_jsonstat object.

Value

a pxweb_data_jsonstat object.

Construct a `pxweb_data_jsonstat2` object.

Description

An object that contains JSON-stat2 data returned by a PXWEB API v2 /tables/{tableId}/data endpoint.

Usage

pxweb_data_jsonstat2(x)

Arguments

x

a list returned from a PXWEB API v2 data endpoint.

Value

a pxweb_data_jsonstat2 object.

Construct a pragmatic `pxweb_data_v2` object.

Description

A thin wrapper around PXWEB API v2 JSON-stat2 data. The original response is kept as-is while data-frame coercion is provided through as.data.frame().

Usage

pxweb_data_v2(x)

Arguments

x

a list returned from a PXWEB API v2 data endpoint.

Value

a pxweb_data_v2 object.

Combine PXWEB API v2 data objects.

Description

Combines a list of pxweb_data_v2 JSON-stat2 data objects returned from split PXWEB API v2 queries. The combined object keeps the v2 data shape and rebuilds dimension indexes, labels, sizes, and values so it can be converted with as.data.frame().

Usage

pxweb_data_v2_c(x)

Arguments

x

a list of pxweb_data_v2 objects.

Value

a combined pxweb_data_v2 object.

Construct a v2 dimension note comment.

Description

Converts a JSON-stat2 dimension-level note to a v1-style column_comment object.

Usage

pxweb_data_v2_column_comment(x, column_idx, comment)

Arguments

x

a pxweb_data_v2 object.

column_idx

integer index of the dimension column.

comment

a normalized comment string.

Value

a pxweb_data_comment object.

Construct a v2 dataset note comment.

Description

Converts a JSON-stat2 dataset-level note to an obs_comment object. Dataset notes do not point to a specific row or column, so both index positions are NA.

Usage

pxweb_data_v2_dataset_note_comment(x, comment)

Arguments

x

a pxweb_data_v2 object.

comment

a normalized comment string.

Value

a pxweb_data_comment object.

Normalize PXWEB API v2 note/status text.

Description

Collapses JSON-stat2 note-like fields to a single character string. Empty and missing values return NULL, while multiple note fragments are joined with newlines.

Usage

pxweb_data_v2_note_text(x)

Arguments

x

a JSON-stat2 note/status field.

Value

a character string, or NULL when no text is available.

Construct a v2 observation comment.

Description

Converts a JSON-stat2 observation-level annotation, currently cell status, to a v1-style obs_comment object.

Usage

pxweb_data_v2_obs_comment(x, obs_idx, comment)

Arguments

x

a pxweb_data_v2 object.

obs_idx

one-based observation row index.

comment

a normalized comment string.

Value

a pxweb_data_comment object.

Construct v2 status comments.

Description

Converts JSON-stat2 status entries to a list of v1-style obs_comment objects. JSON-stat2 status indexes are zero-based, so they are shifted to the one-based row indexes used by pxweb_data_comments.

Usage

pxweb_data_v2_status_comments(x)

Arguments

x

a pxweb_data_v2 object.

Value

a list of pxweb_data_comment objects.

Construct a v2 category note comment.

Description

Converts a JSON-stat2 category-level note to a v1-style value_comment object and indexes every data-frame row containing the noted value.

Usage

pxweb_data_v2_value_comment(x, column_idx, value_code, comment)

Arguments

x

a pxweb_data_v2 object.

column_idx

integer index of the dimension column.

value_code

category value code that carries the note.

comment

a normalized comment string.

Value

a pxweb_data_comment object.

Construct a `pxweb_database_list` object.

Description

An object that contain the list of databases for a given PXWEB api.

Usage

pxweb_database_list(x)

Arguments

x

a list returned from a PXWEB API to convert to a pxweb_database_list object.

Value

a pxweb_database_list object

Backend helpers for PXWEB APIs

Description

Backend helpers for PXWEB APIs

Usage

pxweb_detect_version(x)

Create a `pxweb_explorer` object.

Description

position the current position in the api, as a character vector from the root. Note position is not alway a correct url. Metadata and other choices are part of position

root is the bottom path (as position) that the user can go. If length 0, user can essentially go to hostname.

paste(root_path + position, collapse = "/") is used to construct the path to the position in case of url.

print out a bar for separation purposes

Usage

pxweb_explorer(x = NULL)

## S3 method for class ''NULL''
pxweb_explorer(x)

## S3 method for class 'character'
pxweb_explorer(x)

## S3 method for class 'pxweb'
pxweb_explorer(x)

## S3 method for class 'pxweb_api_catalogue_entry'
pxweb_explorer(x)

assert_pxweb_explorer(x)

## S3 method for class 'pxweb_explorer'
print(x, ...)

print_bar()

pxe_print_choices(x)

Arguments

x

a pxweb object, a PXWEB url, NULL or an api in the api catalogue.

Examples

## The functions below are internal generic functions
## x <- pxweb_explorer()
## url <- "api.scb.se"
## x <- pxweb_explorer(x = url)
## url <- "https://api.scb.se/OV0104/v1/doris/en/ssd/BE/BE0101/BE0101A/"
## x <- pxweb_explorer(x = url)
## url <- "https://api.scb.se/OV0104/v1/doris/en/ssd/BE/BE0101/BE0101A/BefolkningNy"
## x <- pxweb_explorer(x = url)

Fix url characters

Description

Fix url characters

Usage

pxweb_fix_url(x)

Arguments

x

a string to fix

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)

Build api test data.frame

Description

Build api test data.frame

Usage

pxweb_get_api_test_data_frame(x)

Arguments

x

a pxweb object

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.

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)

Setup a structure to log all API calls

Description

Setup a structure to log all API calls

Usage

pxweb_http_log_on(fn = "log_pxweb_api_http_calls.txt")

pxweb_http_log_off()

pxweb_log_paths_path()

pxweb_http_log_is_on()

pxweb_http_log_response(r)

pxweb_response_to_log_as_json(r)

Arguments

fn

The file name of the log file.

Details

Set up internal structure to handle http PXWEB API calls. http calls are stored in a log file. To access the path to this log file, the path is stored in the pxweb folder in the tempdir(). The path is given by pxweb_log_paths_path(). If the file exists, the http calls should be logged (appended) to the log file where the object contains the path.

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.

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/")

Get input from user

Description

Get input from user

Usage

pxweb_interactive_input(pxe, test_input = NULL)

Arguments

pxe

a pxweb_explorer object to get user input for.

test_input

supplying a test input (for testing only).

Construct a `pxweb_levels` object.

Description

An object that contain the levels for a given PXWEB api position.

Usage

pxweb_levels(x)

Arguments

x

a list returned from a PXWEB API to convert to a pxweb_levels object.

Value

a pxweb_levels object

Construct a `pxweb_metadata` object.

Description

An object that contain the metadata for a given PXWEB table.

Usage

pxweb_metadata(x)

Arguments

x

a list returned from a PXWEB API to convert to a pxweb_metadata object.

Value

a pxweb_metadata object

Add values to NULL value variables in PXWEB metadata objects

Description

Add values to NULL value variables in PXWEB metadata objects

Usage

pxweb_metadata_add_null_values(x, px)

Arguments

x

an object to check if is a pxweb_metadata object to which we should add values.

px

a pxweb object

Details

Some metadata objects may have NULL values. In these cases the values are downloaded and added to the metadata object.

Compue the dimension of a metadata object

Description

Compue the dimension of a metadata object

Usage

pxweb_metadata_dim(pxmd)

Arguments

pxmd

a pxweb_metadata object.

Get boolean vector

Description

Get boolean vector

Usage

pxweb_metadata_elimination(pxmd)

Arguments

pxmd

a pxweb_metadata object.

Value

pxweb_metadata eliminations as a named boolean vector.

Get boolean vector

Description

Get boolean vector

Usage

pxweb_metadata_time(pxmd)

Arguments

pxmd

a pxweb_metadata object.

Value

pxweb_metadata eliminations as a named boolean vector.

Construct a `pxweb_metadata` object from a PXWEB API v2 metadata response.

Description

Converts the JSON-stat2-style metadata returned by PXWEB API v2 /tables/{tableId}/metadata endpoints to the existing pxweb_metadata shape used by the package internals. The original v2 payload is preserved as the pxweb_metadata_v2 attribute.

Usage

pxweb_metadata_v2(x)

Arguments

x

a list returned from a PXWEB API v2 metadata endpoint.

Value

a pxweb_metadata object.

Get value texts from a PXWEB API v2 dimension.

Description

Get value texts from a PXWEB API v2 dimension.

Usage

pxweb_metadata_v2_value_texts(dim, values)

Arguments

dim

a dimension list from a PXWEB API v2 metadata response.

values

a character vector of value codes.

Value

a character vector of value labels aligned with values.

Get ordered values from a PXWEB API v2 dimension.

Description

Get ordered values from a PXWEB API v2 dimension.

Usage

pxweb_metadata_v2_values(dim)

Arguments

dim

a dimension list from a PXWEB API v2 metadata response.

Value

a character vector of value codes ordered by the dimension index.

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.

Create a PXWEB query

Description

Creates a pxweb query object from either a list with named values, a json query file or json query string. See examples below.

Usage

pxweb_query(x)

## S3 method for class 'character'
pxweb_query(x)

## S3 method for class 'json'
pxweb_query(x)

## S3 method for class 'pxweb_query'
pxweb_query(x)

## S3 method for class 'list'
pxweb_query(x)

## S3 method for class 'response'
pxweb_query(x)

## S3 method for class 'pxweb_explorer'
pxweb_query(x)

Arguments

x

an object to cast as a pxweb_query object.

Examples

dims <- list(
  Alue = c("*"),
  "Asuntokunnan koko" = c("*"),
  Talotyyppi = c("S"),
  Vuosi = c("*")
)
pxq1 <- pxweb_query(dims)

json_query <- file.path(
  system.file(package = "pxweb"),
  "extdata", "examples", "json_query_example.json"
)
pxq2 <- pxweb_query(json_query)

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().

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.

Convert a `pxweb_query` object to a PXWEB API v2 query.

Description

Convert a pxweb_query object to a PXWEB API v2 query.

Usage

pxweb_query_as_v2(pxq)

Arguments

pxq

a pxweb_query object.

Value

a pxweb_query_v2 object.

Compute the dimension of the query

Description

Compute the dimension of the query

Usage

pxweb_query_dim(pxq)

Arguments

pxq

a pxweb_query object.

Get vector indicating splittable variables

Description

Get vector indicating splittable variables

Usage

pxweb_query_dim_splittable(pxq, pxmd)

Arguments

pxq

a pxweb_query object.

Details

Splitable variables are variables that can be split. Content variables cannot be split, nor variables with filter == "top".

Currently, we can only be sure that time variables and eliminated variables can be split. Hopefully the next API makes this more clear.

Value

a named logical vector.

Get query values

Description

Get query values

Usage

pxweb_query_filter(pxq)

Arguments

pxq

a pxweb_query object.

Value

query variable selection filters as a named character vector.

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()
)

Convert a named list to a PXWEB API v2 request.

Description

Convert a named list to a PXWEB API v2 request.

Usage

pxweb_query_list_as_v2(x)

Arguments

x

a named list with character values or pxweb_query_selection helper objects.

Value

A list with a body slot containing a pxweb_query_v2 object and an extra_query slot containing v2 query parameters such as codelist[Variable] and outputValues[Variable].

Construct a PXWEB API v2 query selection helper.

Description

Construct a PXWEB API v2 query selection helper.

Usage

pxweb_query_selection(
  type,
  value_codes,
  codelist = NULL,
  output_values = NULL,
  class = character()
)

Arguments

type

selection type.

value_codes

values to use in the v2 valueCodes selection.

codelist

optional codelist id.

output_values

optional output values mode.

class

additional S3 class names.

Build codelist-related query parameters for a v2 selection helper.

Description

Build codelist-related query parameters for a v2 selection helper.

Usage

pxweb_query_selection_extra_query(x, variable_code)

Arguments

x

a pxweb_query_selection object.

variable_code

PXWEB variable code.

Construct a `pxweb_query_v2` object.

Description

Construct a pxweb_query_v2 object.

Usage

pxweb_query_v2(x)

Arguments

x

a list with a PXWEB API v2 selection body.

Value

a pxweb_query_v2 object.

Get PXWEB API v2 extra query parameters.

Description

Returns the extra URL query parameters attached to a pxweb_query by v2 selection helpers, for example aggregation and valueset codelists.

Usage

pxweb_query_v2_extra_query(pxq)

Arguments

pxq

a pxweb_query object.

Value

A named list of extra v2 query parameters, such as codelist[Variable] and outputValues[Variable].

Test whether a query variable uses a PXWEB API v2 codelist.

Description

Codelist selections are carried as URL query parameters in v2 requests and should not be validated or expanded against the ordinary metadata values.

Usage

pxweb_query_v2_has_codelist(pxq, variable_code)

Arguments

pxq

a pxweb_query object.

variable_code

PXWEB variable code.

Value

TRUE if variable_code uses a v2 codelist query parameter, otherwise FALSE.

Construct a PXWEB API v2 request object.

Description

Construct a PXWEB API v2 request object.

Usage

pxweb_query_v2_request(body, extra_query = list())

Arguments

body

a pxweb_query_v2 object.

extra_query

additional URL query parameters.

Get the PXWEB API v2 selection type for a query variable.

Description

The selection type is recorded when a query is built from v2 helper objects such as pxweb_latest or pxweb_aggregation.

Usage

pxweb_query_v2_selection_type(pxq, variable_code)

Arguments

pxq

a pxweb_query object.

variable_code

PXWEB variable code.

Value

A character scalar with the v2 selection type for variable_code.

Convert one query value to a PXWEB API v2 selection fragment.

Description

Convert one query value to a PXWEB API v2 selection fragment.

Usage

pxweb_query_value_as_v2(x, variable_code)

Arguments

x

a character vector or pxweb_query_selection object.

variable_code

PXWEB variable code.

Get query filter

Description

Get query filter

Usage

pxweb_query_values(pxq)

Arguments

pxq

a pxweb_query object.

Value

query variable selection values as a named list of character vectors.

Get the requested PXWEB API v2 output format from a response URL.

Description

Extracts the outputFormat query parameter from a PXWEB API v2 response URL. The value is lower-cased so it can be used for response routing. If the response URL has no outputFormat parameter, the function returns NULL.

Usage

pxweb_response_v2_output_format(x)

Arguments

x

a httr response object.

Value

a lower-case output format string, or NULL.

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)

Detect the PXWEB API version used by a search URL

Description

Detect the PXWEB API version used by a search URL

Usage

pxweb_search_api_version(api_url)

Arguments

api_url

a PXWEB API URL.

Extract a scalar character value from a list

Description

Extract a scalar character value from a list

Usage

pxweb_search_chr(x, name)

Arguments

x

a list.

name

the element name to extract.

Create an empty PXWEB API v1 search result

Description

Create an empty PXWEB API v1 search result

Usage

pxweb_search_empty_v1()

Extract a link URL from a PXWEB API v2 links list

Description

Extract a link URL from a PXWEB API v2 links list

Usage

pxweb_search_link(links, rel)

Arguments

links

a PXWEB API links list.

rel

the link relation to extract.

Extract a scalar numeric value from a list

Description

Extract a scalar numeric value from a list

Usage

pxweb_search_num(x, name)

Arguments

x

a list.

name

the element name to extract.

Parse PXWEB API v1 search results

Description

Parse PXWEB API v1 search results

Usage

pxweb_search_parse_v1(x, api_url)

Arguments

x

a parsed PXWEB API v1 search response.

api_url

the PXWEB API v1 database root URL used for the search.

Parse PXWEB API v2 search results

Description

Parse PXWEB API v2 search results

Usage

pxweb_search_parse_v2(x)

Arguments

x

a parsed PXWEB API v2 search response.

Split a parsed URL path into parts

Description

Split a parsed URL path into parts

Usage

pxweb_search_path_parts(parsed_url)

Arguments

parsed_url

a parsed URL object.

Do a PXWEB search GET request

Description

Do a PXWEB search GET request

Usage

pxweb_search_request(url, query, ...)

Arguments

url

a PXWEB search URL.

query

a named list of query string parameters.

...

further arguments passed to httr::GET.

Parse a PXWEB search response

Description

Parse a PXWEB search response

Usage

pxweb_search_response(response)

Arguments

response

a httr response object.

Remove trailing slashes from a URL string

Description

Remove trailing slashes from a URL string

Usage

pxweb_search_trim_slash(x)

Arguments

x

a character string.

Build the PXWEB search URL

Description

Build the PXWEB search URL

Usage

pxweb_search_url(api_url, version)

Arguments

api_url

a PXWEB API root URL.

version

PXWEB API version, "v1" or "v2".

Build a PXWEB API v1 table URL from a search hit

Description

Build a PXWEB API v1 table URL from a search hit

Usage

pxweb_search_v1_table_url(api_url, path, id)

Arguments

api_url

the PXWEB API v1 database root URL.

path

the search hit path.

id

the search hit table id.

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)

Split query in optimal sub-queries

Description

Split query in optimal sub-queries

Usage

pxweb_split_query(pxq, px, pxmd)

Arguments

pxq

a pxweb_query object.

px

a pxweb object.

pxmd

a pxweb_metadata object.

Details

Computes (brute-force) the optimal split of a query to match the api maximum value limit. It also take into account that time variables and content variables should not be split. Also variables with filter "top" should not be split, since the top filter does not supply the individual levels, just a number. This can probably be improved further.

Value

a list with pxweb_query objects.

Construct a `table_response_v2` object.

Description

An object that contain the data for a given PXWEB TableResponse (API v2).

Usage

pxweb_table_response_v2(x)

Arguments

x

a list returned from a PXWEB API to convert to a table_response_v2 object.

Value

a pxweb_table_response_v2 object.

Setup temorary directory for the pxweb

Description

Setup temorary directory for the pxweb

Usage

pxweb_tempdir(to = "apis")

Arguments

to

to what part of the temp folder (apis or logs)

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)

Create all paths from a list of pxweb_api_catalogue entries

Description

Create all paths from a list of pxweb_api_catalogue entries

Usage

pxweb_test_create_api_paths(apis)

Arguments

apis

a list of pxweb_api_catalogue_entry elements

Test time limit object

Description

Test time limit object

Usage

pxweb_test_time_limit(time_limit)

is_test_time_limit_reached(x)

Arguments

time_limit

the number of seconds the API will be tested.

Details

Used to limit testing of API:s.

Build PXWEB API v2 data endpoint query parameters.

Description

Creates the query parameter list sent to PXWEB API v2 /tables/{tableId}/data requests. The language is taken from the URL when present, otherwise from the raw v2 metadata attached to pxmd.

Usage

pxweb_v2_data_query_params(px, pxmd = NULL, output_format = "json-stat2")

Arguments

px

a pxweb object.

pxmd

optional pxweb_metadata object created from a v2 metadata response.

output_format

data output format requested from the API. Defaults to "json-stat2".

Value

a named list of query parameters.

Build a PXWEB API v2 data request.

Description

Creates the request pieces used to POST a query to the PXWEB API v2 /tables/{tableId}/data endpoint. The returned body is the v2 selection JSON generated from a pxweb_query; the query parameters include language and output format.

Usage

pxweb_v2_data_request(px, pxq, pxmd, output_format = "json-stat2")

Arguments

px

a pxweb object for a PXWEB API v2 endpoint.

pxq

a pxweb_query object.

pxmd

a pxweb_metadata object created from v2 metadata.

output_format

data output format requested from the API. Defaults to "json-stat2".

Value

a list with url, body, and query elements.

Build PXWEB API v2 value code query parameters.

Description

Creates the valueCodes[Variable] URL query parameters used when a split v2 request cannot send its selection in the JSON body.

Usage

pxweb_v2_data_value_codes_query(pxq)

Arguments

pxq

a pxweb_query object.

Value

A named list of valueCodes[Variable] query parameters, one for each query dimension.

Convert a PXWEB API v2 output format to a file extension.

Description

Maps a PXWEB API v2 outputFormat value to the file extension used when non JSON-stat2 responses are written to a temporary file. Most formats are already valid extensions; json-px is normalized to json.

Usage

pxweb_v2_output_file_extension(output_format)

Arguments

output_format

a PXWEB API v2 output format string.

Value

a file extension string.

Extract a PXWEB API v2 table id.

Description

Gets the table id used by PXWEB API v2 /tables/{tableId} endpoints. When v2 metadata is available, the id is read from the preserved raw metadata attribute; otherwise it is parsed from the URL path.

Usage

pxweb_v2_table_id(x, pxmd = NULL)

Arguments

x

a pxweb object, url object, or URL string.

pxmd

optional pxweb_metadata object created from a v2 metadata response.

Value

a single table id string.

Build the PXWEB API v2 metadata URL for a table.

Description

Creates a /tables/{tableId}/metadata URL from any PXWEB API v2 table, metadata, or data URL. If the input URL contains a lang query parameter, it is preserved on the metadata URL.

Usage

pxweb_v2_table_metadata_url(x)

Arguments

x

a pxweb object, url object, or URL string.

Value

a metadata endpoint URL string.

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)

Save and load `pxweb` objects from R temp folder

Description

Save and load pxweb objects from R temp folder

Usage

save_pxweb(obj)

load_pxweb(obj)

load_pxweb_calls(obj)

load_pxweb_config(obj)

load_pxweb_api_subpath(obj)

Arguments

obj

a pxweb object

Split variables into chunks

Description

Split variables into chunks

Usage

split_dimensions_left_right(x, bool, max_size)

Details

Splitable variables are variables that can be split. Content variables cannot be split, not variables with filter == "top"

Value

a pxweb_split_dimensions

Pad a string to a fixed size

Description

Pad a string to a fixed size

Usage

str_pad(txt, n = 5, pad = " ", type = "left")

Arguments

txt

a character vector to pad

n

final char width

pad

pad symbol

type

pad from 'left' or 'right'.

Taken from `trimws` for reasons of compatibility with previous R versios.

Description

Taken from trimws for reasons of compatibility with previous R versios.

Usage

str_trim(x, which = c("both", "left", "right"))

Arguments

x

a string to trim.

which

how to trim the string.

Package {pxweb}

Interface to PX-WEB APIs from R

Description

Author(s)

References

See Also

Add default values to pxe

Description

Usage

Arguments

Defunct functions

Description

Usage

Arguments

Format

Assert that x is a correct pxweb_database_list object.

Description

Usage

Arguments

Assert that the url structure is correct

Description

Usage

Arguments

Assert a pxweb_api_catalogue object

Description

Usage

Arguments

Assert that the rda_file_path is correct

Description

Usage

Arguments

Assert that the config slot is correct

Description

Usage

Arguments

Assert that x is a correct pxweb_data object.

Description

Usage

Arguments

Assert that x is a correct pxweb_data_comments object.

Description

Usage

Arguments

Assert that x is a correct pxweb_data_jsonstat object. Assert a json-stat version 1.0 or later object

Description

Usage

Arguments

Assert that x is a PXWEB API v2 JSON-stat2 data response.

Description

Usage

Arguments

Assert that x is a correct pxweb_database_list object.

Description

Usage

Arguments

Assert a pxweb_input_allowed object

Description

Usage

Arguments

Assert that x is a correct pxweb_levels object.

Description

Usage

Arguments

Assert that x is a correct pxweb_metadata object.

Description

Usage

Arguments

Assert that x is a PXWEB API v2 metadata response.

Description

Usage

Arguments

Assert a pxweb_query object

Description

Usage

Arguments

Assert a pxweb_query_v2 object.

Description

Usage

Arguments

Assert that the rda_file_path is correct

Assert that x is a correct `pxweb_database_list` object.

Assert a `pxweb_api_catalogue` object

Assert that x is a correct `pxweb_data` object.

Assert that x is a correct `pxweb_data_comments` object.

Assert that x is a correct `pxweb_data_jsonstat` object. Assert a json-stat version 1.0 or later object

Assert that x is a correct `pxweb_database_list` object.

Assert a `pxweb_input_allowed` object

Assert that x is a correct `pxweb_levels` object.

Assert that x is a correct `pxweb_metadata` object.

Assert a `pxweb_query_v2` object.

Assert that x is a correct `pxweb_table_response_v2` object.

Defines allowed input for a position in a `pxweb_explorer` or character object.