Author: Øyvind Langsrud and Jan Bruusgaard

# Using PxWebApi v2 with PxWebApiData

#### Øyvind Langsrud and Jan Bruusgaard

## Preface

This vignette describes the functionality in the R package PxWebApiData related to PxWebApi v2. The new functions follow the recommended snake_case naming convention.

For older functionality, see Using PxWebApi v1 with PxWebApiData.

The vignette first describes the function `get_api_data()` for retrieving data from a pre-made URL. Note that this function is not limited to PxWebApi. At the end of the vignette, it is also shown how data from Eurostat can be retrieved using `get_api_data()`.

The main function for PxWebApi v2 in the package can be considered to be `api_data()`. It is closely related to `ApiData()` for PxWebApi v1. The function `api_data()` retrieves data in one step. Internally, the functions `query_url()` and `get_api_data()` are called.

As described later in the vignette, the package also provides dedicated functions for retrieving metadata associated with PxWebApi v2.

# `get_api_data()`: retrieve data from a pre-made URL

When a data URL is already available, the data can be retrieved using `get_api_data()`, as illustrated in the example below.

    url <- paste0(
      "https://data.ssb.no/api/pxwebapi/v2/tables/04861/data?lang=en",
      "&valueCodes[Region]=0301,324*",
      "&valueCodes[ContentsCode]=???????",
      "&valueCodes[Tid]=top(2)"
    )

    get_api_data(url)

    $`04861: Area and population of urban settlements, by region, contents and year`
             region            contents year  value
    1 Oslo - Oslove Number of residents 2024 714630
    2 Oslo - Oslove Number of residents 2025 720631
    3      Eidsvoll Number of residents 2024  23154
    4      Eidsvoll Number of residents 2025  23599
    5        Hurdal Number of residents 2024   1174
    6        Hurdal Number of residents 2025   1217

    $dataset
      Region ContentsCode  Tid  value
    1   0301      Bosatte 2024 714630
    2   0301      Bosatte 2025 720631
    3   3240      Bosatte 2024  23154
    4   3240      Bosatte 2025  23599
    5   3242      Bosatte 2024   1174
    6   3242      Bosatte 2025   1217

To return a single data frame with labels only, use the function `get_api_data_1`. The function `get_api_data_2` returns codes only. To return a data frame containing both labels and codes, use `get_api_data_12`.

The output from `get_api_data()` is identical to the output from `api_data()`, which is shown below. As shown, the functions `info()` and `note()` can also be used to display additional information.

# `query_url()`: generate a URL from specifications

The function `query_url()` can be used to generate a data URL. The URL used in the example above can be generated as follows:

    query_url("https://data.ssb.no/api/pxwebapi/v2/tables/04861/data?lang=en",
              Region = c("0301", "324*"),
              ContentsCode = "???????",
              Tid = "top(2)")

    [1] "https://data.ssb.no/api/pxwebapi/v2/tables/04861/data?lang=en&valueCodes[Region]=0301,324*&valueCodes[ContentsCode]=???????&valueCodes[Tid]=top(2)"

The function `query_url()` can be used in many different ways.

A more detailed description is given below in the section on `api_data()`. The input to the two functions is identical.

# `api_data()`: specify and retrieve data in one step

## Specification by codes, `*`, `?`, and `top(n)`

The dataset considered here has three variables: `Region`, `ContentsCode`, and `Tid`. These variables can be used as input parameters.

Each variable can be specified using codes corresponding to the coding used in PxWebApi URL queries.

Codes can be specified directly. It is also possible to truncate codes using an asterisk (`*`) or to mask individual characters using a question mark (`?`). In the example below, seven characters are masked.

Using `top(2)` returns the first two values from the start position.

    api_data("https://data.ssb.no/api/pxwebapi/v2/tables/04861/data?lang=en",
             Region = c("0301", "324*"),
             ContentsCode = "???????",
             Tid = "top(2)")

    $`04861: Area and population of urban settlements, by region, contents and year`
             region            contents year  value
    1 Oslo - Oslove Number of residents 2024 714630
    2 Oslo - Oslove Number of residents 2025 720631
    3      Eidsvoll Number of residents 2024  23154
    4      Eidsvoll Number of residents 2025  23599
    5        Hurdal Number of residents 2024   1174
    6        Hurdal Number of residents 2025   1217

    $dataset
      Region ContentsCode  Tid  value
    1   0301      Bosatte 2024 714630
    2   0301      Bosatte 2025 720631
    3   3240      Bosatte 2024  23154
    4   3240      Bosatte 2025  23599
    5   3242      Bosatte 2024   1174
    6   3242      Bosatte 2025   1217

A list of two data frames is returned: one with labels and one with codes.

To return a single data frame with labels only, use the function `api_data_1`. The function `api_data_2` returns codes only. To return a data frame containing both labels and codes, use `api_data_12`.

Internally, a data URL is first constructed and the data are then retrieved using the function `get_api_data()`.

To obtain the generated URL, replace `api_data()` with `query_url()`. The URL for this example has already been generated using `query_url()` in the example above.

## Specification using (default) indexing

Numeric values are interpreted as indexing, either as row numbers in the metadata or as indices. See the parameter `use_index` for further details.

As specified by the parameter `default_query`, unspecified variables are set to `c(1, -2, -1)`. In the example below, `Tid` is unspecified, which therefore corresponds to the first and the two last years.

    api_data_12("https://data.ssb.no/api/pxwebapi/v2/tables/04861/data?lang=en",
               Region = 14:17,
               ContentsCode = 2)

          region            contents year Region ContentsCode  Tid value
    1      Asker Number of residents 2000   3203      Bosatte 2000     0
    2      Asker Number of residents 2024   3203      Bosatte 2024 93769
    3      Asker Number of residents 2025   3203      Bosatte 2025 95455
    4 Lillestrøm Number of residents 2000   3205      Bosatte 2000     0
    5 Lillestrøm Number of residents 2024   3205      Bosatte 2024 87596
    6 Lillestrøm Number of residents 2025   3205      Bosatte 2025 89143
     [ reached 'max' / getOption("max.print") -- omitted 6 rows ]

## Specification using `TRUE`, `FALSE`, imaginary values (e.g. `3i`), and labels

All possible values are obtained by `TRUE` and this is equivalent to `"*"`. Elimination of a variable is obtained by `FALSE`. Imaginary values represent `top`, for example `3i` is equivalent to `"top(3)"`.

    api_data_2("https://data.ssb.no/api/pxwebapi/v2/tables/04861/data?lang=en",
              Region = FALSE,
              ContentsCode = TRUE,
              Tid = 3i)

      ContentsCode  Tid      value
    1        Areal 2023    2266.99
    2        Areal 2024    2279.97
    3        Areal 2025    2285.89
    4      Bosatte 2023 4554562.00
    5      Bosatte 2024 4619969.00
    6      Bosatte 2025 4662945.00

Labels can also be used as an alternative to codes.

    obj <- api_data("https://data.ssb.no/api/pxwebapi/v2/tables/04861/data?lang=en",
                    Region = c("Asker", "Hurdal"),
                    ContentsCode = TRUE,
                    Tid = 2i)

To show either label version or code version.

    obj[[1]]

      region                        contents year    value
    1  Asker Area of urban settlements (km²) 2024    51.89
    2  Asker Area of urban settlements (km²) 2025    52.00
    3  Asker             Number of residents 2024 93769.00
    4  Asker             Number of residents 2025 95455.00
    5 Hurdal Area of urban settlements (km²) 2024     1.19
    6 Hurdal Area of urban settlements (km²) 2025     1.20
    7 Hurdal             Number of residents 2024  1174.00
    8 Hurdal             Number of residents 2025  1217.00

    obj[[2]]

      Region ContentsCode  Tid    value
    1   3203        Areal 2024    51.89
    2   3203        Areal 2025    52.00
    3   3203      Bosatte 2024 93769.00
    4   3203      Bosatte 2025 95455.00
    5   3242        Areal 2024     1.19
    6   3242        Areal 2025     1.20
    7   3242      Bosatte 2024  1174.00
    8   3242      Bosatte 2025  1217.00

## 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:20, ]  # 9 rows printed

       Vekst ContentsCode  Tid value NAstatus
    14    50  VarigKultur 2015    NA        :
    15    50  VarigKultur 2020    NA        .
    16    51 Veksthusbedr 2012    NA       ..
    17    51 Veksthusbedr 2015    94     <NA>
    18    51 Veksthusbedr 2020    89     <NA>
    19    51  BedrMedBiol 2012    NA       ..
    20    51  BedrMedBiol 2015    67     <NA>

In this case, the `NAstatus` variable is included. See the `api_data()` parameter `make_na_status`.

## Show additional information

Use `info()` and `note()` (or `comment()`) to list additional dataset information.

    info(obj)

                                                                              label
    "04861: Area and population of urban settlements, by region, contents and year"
                                                                             source
                                                                "Statistics Norway"
                                                                            updated
                                                             "2025-10-27T07:00:00Z"
                                                                            tableid
                                                                            "04861"
                                                                           contents
                                 "04861: Area and population of urban settlements,"

    note(obj)

                                                                                                        [1]
                                      "Not included persons lacking information on type of residence area."
                                                                                                        [2]
    "As of 1. January 2013 Statistics Norway implemented a new method for defining urban settlements, resulting in a more accurate delimitation. Due to this figures before and after 2013 are not directly comparable."
                                                                                                        [3]
                                                                                    "Year 2010 is missing."
                                                                                                        [4]
    "[See list over changes in regional classifications](https://www.ssb.no/offentlig-sektor/kommunekatalog/endringer-i-de-regionale-inndelingene) (in Norwegian).
    "

Use `note()` for explanation of NA status codes

    note(out)

                                                                                                        [1]
    ". = Category not applicable. Figures do not exist at this time, because the category was not in use when the figures were collected."
                                                                                                        [2]
             ": = Confidential. Figures are not published so as to avoid identifying persons or companies."
                                                                                                        [3]
    ".. = Data not available. Figures have not been entered into our databases or are too unreliable to be published."

## Specification by `list()` for advanced queries

Advanced queries can be specified using named lists, where the names correspond to the encoding used in PxWebApi URL queries.

     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)

      Region Kjonn Alder ContentsCode  Tid value
    1 K-3101     2   H17    Personer1 2024  2944
    2 K-3101     2   H17    Personer1 2025  2926
    3 K-3101     2   H18    Personer1 2024 12843
    4 K-3101     2   H18    Personer1 2025 12954
    5 K-3101     1   H17    Personer1 2024  3078
    6 K-3101     1   H17    Personer1 2025  3021
    7 K-3101     1   H18    Personer1 2024 13070
     [ reached 'max' / getOption("max.print") -- omitted 9 rows ]

In this case, the generated URL is:

     url <- query_url("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)
     cat(gsub("&", "\n&", url))

    https://data.ssb.no/api/pxwebapi/v2/tables/07459/data?lang=en
    &codelist[Region]=agg_KommSummer
    &valueCodes[Region]=K-3101,K-3103
    &outputValues[Region]=aggregated
    &valueCodes[Kjonn]=*
    &codelist[Alder]=agg_TodeltGrupperingB
    &valueCodes[Alder]=H17,H18
    &outputValues[Alder]=aggregated
    &valueCodes[ContentsCode]=Personer1
    &valueCodes[Tid]=top(2)

To improve readability, `cat()` together with `gsub()` is used to print the long URL across multiple lines.

This query is constructed using information available in the metadata; see the section below.

# Obtaining metadata

## `meta_frames()`

Metadata for a data set can be obtained using `meta_frames()`.

    mf <- meta_frames("https://data.ssb.no/api/pxwebapi/v2/tables/04861/data?lang=en")
    print(mf)

    $Region
       code index           label
    1  3101     0          Halden
    2  3103     1            Moss
    3  3105     2       Sarpsborg
    4  3107     3     Fredrikstad
    5  3110     4          Hvaler
    6  3112     5            Råde
    7  3114     6 Våler (Østfold)
    8  3116     7        Skiptvet
    9  3118     8   Indre Østfold
    10 3120     9       Rakkestad
    11 3122    10          Marker
    12 3124    11         Aremark
    13 3201    12           Bærum
    14 3203    13           Asker
     [ reached 'max' / getOption("max.print") -- omitted 938 rows ]

    $ContentsCode
         code index                           label unit.base unit.decimals
    1   Areal     0 Area of urban settlements (km²)       km²             2
    2 Bosatte     1             Number of residents   persons             0

    $Tid
       code index label
    1  2000     0  2000
    2  2002     1  2002
    3  2003     2  2003
    4  2004     3  2004
    5  2005     4  2005
    6  2006     5  2006
    7  2007     6  2007
    8  2008     7  2008
    9  2009     8  2009
    10 2011     9  2011
    11 2012    10  2012
    12 2013    11  2013
    13 2014    12  2014
    14 2015    13  2015
     [ reached 'max' / getOption("max.print") -- omitted 10 rows ]

Information about whether variables can be eliminated is stored as an attribute and can be retrieved for all variables at once:

    sapply(mf, attr, "elimination") # elimination info for all variables

          Region ContentsCode          Tid
            TRUE        FALSE        FALSE

Code list information is stored as a data frame in another attribute:

    attr(mf[["Region"]], "code_lists")

                         id                                          label
    1        agg_KommFylker          Counties 2024, aggregated time series
    2       agg_KommForrige                       Municipalities 2020-2023
    3        agg_KommSummer    Municipalities 2024, aggregated time series
    4    agg_LandsdelKommun                                   Regions 2025
    5  agg_Politidistrikt16                           Police district 2016
    6       agg_RegionerBVF Regions (Child welfare and family counselling)
    7    agg_SentralIndeksA       Centrality (can not be used before 1977)
    8  agg_OkonomRegion2020                          Economic regions 2024
    9      agg_Valgdistrikt                            Electoral districts
    10            vs_Kommun                             All municipalities
              type
    1  Aggregation
    2  Aggregation
    3  Aggregation
    4  Aggregation
    5  Aggregation
    6  Aggregation
    7  Aggregation
    8  Aggregation
    9  Aggregation
    10    Valueset
                                                                            links
    1        https://data.ssb.no/api/pxwebapi/v2/codeLists/agg_KommFylker?lang=en
    2       https://data.ssb.no/api/pxwebapi/v2/codeLists/agg_KommForrige?lang=en
    3        https://data.ssb.no/api/pxwebapi/v2/codeLists/agg_KommSummer?lang=en
    4    https://data.ssb.no/api/pxwebapi/v2/codeLists/agg_LandsdelKommun?lang=en
    5  https://data.ssb.no/api/pxwebapi/v2/codeLists/agg_Politidistrikt16?lang=en
    6       https://data.ssb.no/api/pxwebapi/v2/codeLists/agg_RegionerBVF?lang=en
    7    https://data.ssb.no/api/pxwebapi/v2/codeLists/agg_SentralIndeksA?lang=en
    8  https://data.ssb.no/api/pxwebapi/v2/codeLists/agg_OkonomRegion2020?lang=en
    9      https://data.ssb.no/api/pxwebapi/v2/codeLists/agg_Valgdistrikt?lang=en
    10            https://data.ssb.no/api/pxwebapi/v2/codeLists/vs_Kommun?lang=en

## `meta_code_list()`

Metadata for code lists referenced in this output can be retrieved using `meta_code_list()`.

## `meta_data()`

To download raw metadata without further processing, use `meta_data()`.

Note that it does not matter whether the input URL refers to data or metadata; this is handled automatically.

# Eurostat data

Eurostat REST API offers JSON-stat version 2. It is possible to use this package to obtain data from Eurostat by using `get_api_data` or the similar functions with `1`, `2` or `12` at the end

This example shows HICP total index, latest two periods for EU and Norway. See Eurostat guidelines for more.

    url_eurostat <- paste0(   # Here the long url is split into several lines using paste0
      "https://ec.europa.eu/eurostat/api/dissemination/statistics/1.0/data/prc_hicp_mv12r",
      "?format=JSON&lang=EN&lastTimePeriod=2&coicop=CP00&geo=NO&geo=EU")
    url_eurostat

    [1] "https://ec.europa.eu/eurostat/api/dissemination/statistics/1.0/data/prc_hicp_mv12r?format=JSON&lang=EN&lastTimePeriod=2&coicop=CP00&geo=NO&geo=EU"

    get_api_data_12(url_eurostat)

    No encoding supplied: defaulting to UTF-8.

      Time frequency                         Unit of measure
    1        Monthly Moving 12 months average rate of change
    2        Monthly Moving 12 months average rate of change
    3        Monthly Moving 12 months average rate of change
    4        Monthly Moving 12 months average rate of change
      Classification of individual consumption by purpose (COICOP)
    1                                               All-items HICP
    2                                               All-items HICP
    3                                               All-items HICP
    4                                               All-items HICP
                                                                                       Geopolitical entity (reporting)
    1 European Union (EU6-1958, EU9-1973, EU10-1981, EU12-1986, EU15-1995, EU25-2004, EU27-2007, EU28-2013, EU27-2020)
    2 European Union (EU6-1958, EU9-1973, EU10-1981, EU12-1986, EU15-1995, EU25-2004, EU27-2007, EU28-2013, EU27-2020)
    3                                                                                                           Norway
    4                                                                                                           Norway
         Time freq         unit coicop geo    time value
    1 2025-11    M RCH_MV12MAVR   CP00  EU 2025-11   2.5
    2 2025-12    M RCH_MV12MAVR   CP00  EU 2025-12   2.5
    3 2025-11    M RCH_MV12MAVR   CP00  NO 2025-11   2.7
    4 2025-12    M RCH_MV12MAVR   CP00  NO 2025-12   2.8

# Background

PxWeb and it’s API, PxWebApi is used as output database (Statbank) by many statistical agencies in the Nordic countries and several others, i.e. Statistics Norway, Statistics Finland, Statistics Sweden. See list of installations.

For hints on using PxWebApi v2 in general see PxWebApi v2 User Guide.