PxWebApiData (version 1.9.0)

api_data: PX-Web Data by API

Description

This function constructs a PxWebApi v2 data URL using query_url() and retrieves the data using get_api_data().

Usage

api_data(
  url_or_tableid,
  ...,
  url_type = "ssb",
  use_index = FALSE,
  default_query = c(1, -2, -1),
  return_dataset = NULL,
  make_na_status = TRUE,
  verbose_print = FALSE
)
api_data_1(..., return_dataset = 1)
api_data_2(..., return_dataset = 2)
api_data_12(..., return_dataset = 12)

Value

A data frame, or a list of data frames, depending on the input and parameters.

Arguments

url_or_tableid

A table id, a PxWebApi v2 URL to data or metadata, or metadata returned by meta_data() or meta_frames().

...

Specification of query for each variable. See ‘Details’.

url_type

Currently two possibilities: "ssb" (Norwegian) or "ssb_en" (English).

use_index

Logical. If TRUE, numeric values are matched against the index variable in the metadata, which usually starts at 0. If FALSE (default), numeric values are interpreted as row numbers in the metadata, using standard R indexing. Negative values can be used to specify reversed row numbers.

default_query

Specification for variables not included in .... The default is default_query = c(1, -2, -1), which selects the first and the two last codes listed in the metadata. Use default_query = TRUE and omit specifying individual variables to retrieve entire tables.

return_dataset

Possible non-NULL values are 1, 2 and 12. Then a single data set is returned as a data frame.

make_na_status

When TRUE and when dataPackage is "rjstat" and when missing entries in value, the function tries to add an additional variable, named NAstatus, with status codes. An explanation of these status codes is provided in the note part of the comment attribute, i.e. what you get with note(). See the bottom example.

verbose_print

When TRUE, printing to console

Details

Each variable is specified by using the variable name as an input parameter.

The value can be specified either as a vector or as a list.

Vector input

When specified as a vector, this results in a valueCodes specification. The vector can be specified in the same way as in a PxWebApi URL. In addition, the specification method inherited from the legacy ApiData() function for PxWebApi v1 can be used:

• TRUE means all values and is equivalent to "*".

• FALSE means eliminated, which is equivalent to removing the variable from the URL. This is meaningful for variables that can be eliminated; see the lower examples in meta_frames().

• Imaginary values represent top, e.g. 3i is equivalent to "top(3)".

• Numeric values are interpreted as row numbers (negative values allowed) or as indices; see the parameter description of use_index.

• Codes can be specified directly, including the use of wildcards such as "*" and "??". Labels may also be used as an alternative to codes.

List input

When the input is a named list, the URL is constructed directly from the names and elements of the list (see examples). It is also possible to omit the name of a list element. In this case, the element results in a valueCodes specification and is processed in the same way as vector input.

Examples

obj <- api_data(14162, Region = FALSE, InnKvartering1 = FALSE, Landkoder2 = FALSE, 
                ContentsCode = TRUE, Tid = 3i, url_type = "ssb_en")
          
obj[[1]]    # The label version of the dataset, as returned by api_data_1()
obj[[2]]    # The code version of the dataset, as returned by api_data_2()
names(obj)
info(obj)   # Similar to comment(); see also note() below

 # same as above 
 # api_data("https://data.ssb.no/api/pxwebapi/v2/tables/14162/data?lang=en", 
 #           default_query = FALSE, ContentsCode = "*", Tid = "top(3)")
 
 # also same as above 
 # api_data(14162, url_type = "ssb_en", default_query = FALSE,
 #          ContentsCode = list(valueCodes = "*"), 
 #          Tid = list(valueCodes = "top(3)"))

 api_data_1("https://data.ssb.no/api/pxwebapi/v2/tables/09546/data?lang=en",
            Region = FALSE, SkoleSTR = "07", GrSkolOrgForm = "4", 
            EierforhSkole = 1:2, ContentsCode = TRUE, Tid = "202?") 
            
 api_data_2("https://data.ssb.no/api/pxwebapi/v2/tables/07459/data?lang=en",
            Region = list(codelist = "agg_KommSummer", 
                          valueCodes = c("K-3101", "K-3103"), 
                          outputValues = "aggregated"),
            Kjonn = TRUE,
            Alder = list(codelist = "agg_TodeltGrupperingB", 
                         valueCodes = c("H17", "H18"),
                         outputValues = "aggregated"),
            ContentsCode = 1,
            Tid = 2i)           
            
 # codes and labels can be mixed            
 api_data_12(4861, 
             Region = c("Sarpsborg", "3103", "402?"), 
             ContentsCode = "Bosatte", 
             Tid = c(1, -1), 
             url_type = "ssb_en") 
             
 
 # A Statistics Sweden example             
 api_data_12("https://statistikdatabasen.scb.se/api/v2/tables/TAB4537/data?lang=en", 
             Region = "??", 
             Kon = FALSE)                      

 
 # Use default_query = TRUE to retrieve entire tables
 out <- api_data_2("https://data.ssb.no/api/pxwebapi/v2/tables/10172/data?lang=en", 
                            default_query = TRUE)
 out[14:22, ]  # 9 rows printed      

 
 # Use note() for explanation of status codes (see api_data() parameter makeNAstatus)                       
 note(out)
 
 # info() and note() return parts of the comment attribute
 info(out)
 comment(out)