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

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

---

Cite a PXWEB data object

Description

Cite a PXWEB data object

Usage

pxweb_cite(x, style = "citation")

Arguments

x	a pxweb_data object to cite.
style	see bibentry.

Details

Functionality to automatic cite PXWEB data objects.

---

Do a GET call to PXWEB API

Description

Do a GET call to PXWEB API

Usage

pxweb_get(url, query = NULL, verbose = TRUE)

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.

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 downloaded json query
jstat2_url <- "https://pxdata.stat.fi:443/PxWeb/api/v1/fi/StatFin/eot/statfin_eot_pxt_132a.px"
jstat2_query <- file.path(
  system.file(package = "pxweb"),
  "extdata", "examples", "sq-api_table_statfin_eot_pxt_132a.px.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"
)

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?

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.

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

The function returns a list with three slots: url: The URL to the data query: The query to access the data data: The downloaded data (if chosen to download data)

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

---

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)

---