Author: Øyvind Langsrud, Jan Bruusgaard, Solveig Bjørkholt and Susie Jentoft

# Using PxWebApi v1 with PxWebApiData

#### Øyvind Langsrud, Jan Bruusgaard, Solveig Bjørkholt and Susie Jentoft

### Preface

This vignette describes the functionality in the R package PxWebApiData related to PxWebApi v1.

Most of the content in this vignette was written before PxWebApi v2 was introduced.

For PxWebApi v2 functionality, see Using PxWebApi v2 with PxWebApiData.

An introduction to the R package PxWebApiData (for PxWebApi v1) is given below. Six calls to the main function, `ApiData`, are demonstrated. First, two calls for reading data sets are shown. The third call captures meta data. However, in practise, one may look at the meta data first. Then three more examples and some background is given.

Note: Earlier versions of this vignette demonstrated “readymade datasets by GetApiData”. As Statistics Norway will remove the readymade API during 2025, these examples are now replaced. The new PxWebApi 2 is now the primary API for Statistics Norway.

## Specification by variable indices and variable id’s

The dataset below has three variables, Region, ContentsCode and Tid. The variables can be used as input parameters. Here two of the parameters are specified by variable id’s and one parameter is specified by indices. Negative values are used to specify reversed indices. Thus, we here obtain the two first and the two last years in the data.

A list of two data frames is returned; the label version and the id version.

    ApiData("https://data.ssb.no/api/v0/en/table/04861",
            Region = c("1103", "0301"), ContentsCode = "Bosatte", Tid = c(1, 2, -2, -1))

    $`04861: Area and population of urban settlements, by region, contents and year`
             region            contents year  value
    1 Oslo - Oslove Number of residents 2000 504348
    2 Oslo - Oslove Number of residents 2002 508134
    3 Oslo - Oslove Number of residents 2024 714630
    4 Oslo - Oslove Number of residents 2025 720631
    5     Stavanger Number of residents 2000 106804
    6     Stavanger Number of residents 2002 108271
    7     Stavanger Number of residents 2024 142897
    8     Stavanger Number of residents 2025 143972

    $dataset
      Region ContentsCode  Tid  value
    1   0301      Bosatte 2000 504348
    2   0301      Bosatte 2002 508134
    3   0301      Bosatte 2024 714630
    4   0301      Bosatte 2025 720631
    5   1103      Bosatte 2000 106804
    6   1103      Bosatte 2002 108271
    7   1103      Bosatte 2024 142897
    8   1103      Bosatte 2025 143972

To return a single dataset with only labels use the function `ApiData1`. The function `Apidata2` returns only id’s. To return a dataset with both labels and id’s in one dataframe use `ApiData12`.

    ApiData12("https://data.ssb.no/api/v0/en/table/04861",
            Region = c("1103", "0301"), ContentsCode = "Bosatte", Tid = c(1, 2, -2, -1))

             region            contents year Region ContentsCode  Tid  value
    1 Oslo - Oslove Number of residents 2000   0301      Bosatte 2000 504348
    2 Oslo - Oslove Number of residents 2002   0301      Bosatte 2002 508134
    3 Oslo - Oslove Number of residents 2024   0301      Bosatte 2024 714630
    4 Oslo - Oslove Number of residents 2025   0301      Bosatte 2025 720631
    5     Stavanger Number of residents 2000   1103      Bosatte 2000 106804
    6     Stavanger Number of residents 2002   1103      Bosatte 2002 108271
    7     Stavanger Number of residents 2024   1103      Bosatte 2024 142897
    8     Stavanger Number of residents 2025   1103      Bosatte 2025 143972

## Specification by TRUE, FALSE and imaginary values (e.g. 3i).

All possible values is obtained by TRUE and corresponds to filter `"all": "*"` in the api query. Elimination of a variable is obtained by FALSE. An imaginary value corresponds to filter `"top"` in the api query.

    x <- ApiData("https://data.ssb.no/api/v0/en/table/04861",
            Region = FALSE, ContentsCode = TRUE, Tid = 3i)

To show either label version or id version

    x[[1]]

                             contents year      value
    1 Area of urban settlements (km²) 2023    2266.99
    2 Area of urban settlements (km²) 2024    2279.97
    3 Area of urban settlements (km²) 2025    2285.89
    4             Number of residents 2023 4554562.00
    5             Number of residents 2024 4619969.00
    6             Number of residents 2025 4662945.00

    x[[2]]

      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

## Show additional information

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

    info(x)

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

    note(x)

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

## Obtaining meta data

Meta information about the data set can be obtained by `returnMetaFrames = TRUE`.

    ApiData("https://data.ssb.no/api/v0/en/table/04861",  returnMetaFrames = TRUE)

    $Region
       values      valueTexts
    1    3101          Halden
    2    3103            Moss
    3    3105       Sarpsborg
    4    3107     Fredrikstad
    5    3110          Hvaler
    6    3112            Råde
    7    3114 Våler (Østfold)
    8    3116        Skiptvet
    9    3118   Indre Østfold
    10   3120       Rakkestad
    11   3122          Marker
    12   3124         Aremark
    13   3201           Bærum
    14   3203           Asker
    15   3205      Lillestrøm
    16   3207    Nordre Follo
    17   3209      Ullensaker
    18   3212        Nesodden
    19   3214           Frogn
    20   3216          Vestby
    21   3218              Ås
    22   3220         Enebakk
     [ reached 'max' / getOption("max.print") -- omitted 930 rows ]

    $ContentsCode
       values                      valueTexts
    1   Areal Area of urban settlements (km²)
    2 Bosatte             Number of residents

    $Tid
       values valueTexts
    1    2000       2000
    2    2002       2002
    3    2003       2003
    4    2004       2004
    5    2005       2005
    6    2006       2006
    7    2007       2007
    8    2008       2008
    9    2009       2009
    10   2011       2011
    11   2012       2012
    12   2013       2013
    13   2014       2014
    14   2015       2015
    15   2016       2016
    16   2017       2017
    17   2018       2018
    18   2019       2019
    19   2020       2020
    20   2021       2021
    21   2022       2022
    22   2023       2023
     [ reached 'max' / getOption("max.print") -- omitted 2 rows ]

    attr(,"text")
          Region ContentsCode          Tid
        "region"   "contents"       "year"
    attr(,"elimination")
          Region ContentsCode          Tid
            TRUE        FALSE        FALSE
    attr(,"time")
          Region ContentsCode          Tid
           FALSE        FALSE         TRUE

## Aggregations using filter agg:

PxWebApi offers two more filters for groupings, `agg:` and `vs:`. You can see these filters in the code “API Query for this table” when you have made a table in PxWeb.

`agg`: is used for readymade aggregation groupings.

This example shows the use of aggregation in age groups and aggregated timeseries for the new Norwegian municipality structure from 2020. Also note the url where `/en` is replaced by `/no`. That returns labels in Norwegian instead of in English.

    ApiData("https://data.ssb.no/api/v0/no/table/07459",
            Region = list("agg:KommSummer", c("K-3101", "K-3103")),
            Tid = 4i,
            Alder = list("agg:TodeltGrupperingB", c("H17", "H18")),
            Kjonn = TRUE)

    $`07459: Befolkning, etter region, kjønn, alder, statistikkvariabel og år`
      region   kjønn             alder statistikkvariabel   år value
    1 Halden Kvinner           0-17 år           Personer 2022  2937
    2 Halden Kvinner           0-17 år           Personer 2023  2933
    3 Halden Kvinner           0-17 år           Personer 2024  2944
    4 Halden Kvinner           0-17 år           Personer 2025  2926
    5 Halden Kvinner 18 år eller eldre           Personer 2022 12626
    6 Halden Kvinner 18 år eller eldre           Personer 2023 12787
    7 Halden Kvinner 18 år eller eldre           Personer 2024 12843
     [ reached 'max' / getOption("max.print") -- omitted 25 rows ]

    $dataset
      Region Kjonn Alder ContentsCode  Tid value
    1 K-3101     2   H17    Personer1 2022  2937
    2 K-3101     2   H17    Personer1 2023  2933
    3 K-3101     2   H17    Personer1 2024  2944
    4 K-3101     2   H17    Personer1 2025  2926
    5 K-3101     2   H18    Personer1 2022 12626
    6 K-3101     2   H18    Personer1 2023 12787
    7 K-3101     2   H18    Personer1 2024 12843
     [ reached 'max' / getOption("max.print") -- omitted 25 rows ]

There are two limitations in the PxWebApi using these filters.

1. The name of the filter and the id’s are not shown in metadata, only in the code “API Query for this table”.
2. The filters `agg:` and `vs:` can only take single elements as input. Filter `"all":"*"` eg. TRUE, does not work with agg: and vs:.

The other filter `vs:`, specify the grouping value sets, which is a part of the value pool. As it is only possible to give single elements as input, it is easier to query the value pool. This means that `vs:` is redundant.

In this example Region is the value pool and Fylker (counties) is the value set. As `vs:Fylker` is redundant, both will return the same:

      Region = list("vs:Fylker",c("01","02"))
      Region = c("01","02")

## Return the API query as JSON

In PxWebApi the original query is formulated as JSON. Using the parameter returnApiQuery is useful for debugging.

    ApiData("https://data.ssb.no/api/v0/en/table/04861",  returnApiQuery = TRUE)

    {
      "query": [
        {
          "code": "Region",
          "selection": {
            "filter": "item",
            "values": ["3101", "2399", "9999"]
          }
        },
        {
          "code": "ContentsCode",
          "selection": {
            "filter": "item",
            "values": ["Areal", "Bosatte"]
          }
        },
        {
          "code": "Tid",
          "selection": {
            "filter": "item",
            "values": ["2000", "2024", "2025"]
          }
        }
      ],
      "response": {
        "format": "json-stat2"
      }
    }

To convert an original JSON API query to a PxWebApiData query there is also a simple webpage PxWebApiData call creator.

## PxWebApi 2 examples with GetApiData

The text in this section was written before the new functionality described in Using PxWebApi v2 with PxWebApiData.

The legacy function `GetApiData()` is therefore used here. However, the same examples can now be run in exactly the same way using `get_api_data()` instead.

Statistics Norway has announced that PxWebApi 2 is now the primary API for Statbank Norway’s 7500 public tables. This API supports GET queries defined entirely in a URL.

Version 1 of PxWebApi will continue to exist in parallel for a period of time, but only supports POST queries. The limited API with “readymade datasets” will be removed during 2025, since PxWebApi 2 offers GET queries.

The `GetApiData` function can be used with URLs for PxWebApi 2 in a similar way as it was previously used for “readymade datasets”. It corresponds to using the parameter `getDataByGET = TRUE` in the `ApiData` function. Corresponding wrapper functions `GetApiData1`, `GetApiData2` and `GetApiData12` are available for `ApiData1`, `ApiData2` and `ApiData12`.

    # Example dataset
    url1 <- "https://data.ssb.no/api/pxwebapi/v2/tables/05810/data?lang=en"
    x <- GetApiData(url1)

    x[[1]]    # Label version of the dataset

             age contents year     gender   value
    1        All  Persons 2025 Both sexes 5594340
    2        All  Persons 2025    Females 2775143
    3        All  Persons 2025      Males 2819197
    4  0-6 years  Persons 2025 Both sexes  390630
    5  0-6 years  Persons 2025    Females  190150
    6  0-6 years  Persons 2025      Males  200480
    7 7-15 years  Persons 2025 Both sexes  581299
    8 7-15 years  Persons 2025    Females  282276
    9 7-15 years  Persons 2025      Males  299023
     [ reached 'max' / getOption("max.print") -- omitted 12 rows ]

    comment(x)

                                                                                                      label
                                                     "05810: Population, by age, contents, year and gender"
                                                                                                     source
                                                                                        "Statistics Norway"
                                                                                                    updated
                                                                                     "2025-02-25T07:00:00Z"
                                                                                                    tableid
                                                                                                    "05810"
                                                                                                   contents
                                                                                       "05810: Population,"
                                                                                                       note
    "Until 1990 the figures correspond per 31 Desember. As from 1995 the figures correspond per 1 January."

    # More specific query with selected dimensions
    url2 <- paste0(
      "https://data.ssb.no/api/pxwebapi/v2/tables/03013/data?lang=en",
      "&valueCodes[Konsumgrp]=??",
      "&valueCodes[ContentsCode]=KpiIndMnd",
      "&valueCodes[Tid]=top(2)"
    )

    x2 <- GetApiData2(url2)
    x2  # id version of the dataset

       Konsumgrp ContentsCode     Tid value
    1         01    KpiIndMnd 2025M11 141.6
    2         01    KpiIndMnd 2025M12 139.2
    3         02    KpiIndMnd 2025M11 132.1
    4         02    KpiIndMnd 2025M12 132.0
    5         03    KpiIndMnd 2025M11 105.9
    6         03    KpiIndMnd 2025M12 105.6
    7         04    KpiIndMnd 2025M11 143.7
    8         04    KpiIndMnd 2025M12 144.0
    9         05    KpiIndMnd 2025M11 142.0
    10        05    KpiIndMnd 2025M12 144.8
    11        06    KpiIndMnd 2025M11 133.2
     [ reached 'max' / getOption("max.print") -- omitted 13 rows ]

## Eurostat data

Eurostat REST API offers JSON-stat version 2. It is possible to use this package to obtain data from Eurostat by using `GetApiData` 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.

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

    [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"

    GetApiData12(urlEurostat)

    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

## Practical example

We would like to extract the number of female R&D personel in the services sector of the Norwegian business life for the years 2019 and 2020.

1. Locate the relevant table at https://www.ssb.no that contains information on R&D personel. Having obtained the relevant table, table 07964, we create the link https://data.ssb.no/api/v0/no/table/07964/

2. Load the package.

    library(PxWebApiData)

3. Check which variables that exist in the data.

    variables <- ApiData("https://data.ssb.no/api/v0/no/table/07964/",
                         returnMetaFrames = TRUE)

    names(variables)

    [1] "NACE2007"     "ContentsCode" "Tid"

4. Check which values each variable contains.

    values <- ApiData("https://data.ssb.no/api/v0/no/table/07964/",
                      returnMetaData = TRUE)

    values[[1]]$values

     [1] "A-N"       "A03"       "B05-B09"   "B06_B09.1" "C"         "C10-C11"
     [7] "C13"       "C14-C15"   "C16"       "C17"       "C18"       "C19-C20"
    [13] "C21"       "C22"       "C23"       "C24"       "C25"       "C26"
    [19] "C26.3"     "C26.5"     "C27"       "C28"       "C29"       "C30"
    [25] "C30.1"     "C31"       "C32"       "C32.5"     "C33"       "D35"
    [31] "E36-E39"   "F41-F43"   "G-N"       "G46"       "H49-H53"   "J58"
    [37] "J58.2"     "J59-J60"   "J61"       "J62"       "J63"       "K64-K66"
    [43] "M70"       "M71"       "M72"
     [ reached 'max' / getOption("max.print") -- omitted 2 entries ]

    values[[2]]$values

    [1] "EnhetTot"           "EnheterFoU"         "FoUpersonale"
    [4] "KvinneligFoUpers"   "FoUPersonaleUoHutd" "FoUPersonaleDoktor"
    [7] "FoUArsverk"         "FoUArsverkPers"     "FoUArsverkUtd"

    values[[3]]$values

     [1] "2007" "2008" "2009" "2010" "2011" "2012" "2013" "2014" "2015" "2016"
    [11] "2017" "2018" "2019" "2020" "2021" "2022" "2023"

5. Define these variables in the query to sort out the values we want.

    mydata <- ApiData("https://data.ssb.no/api/v0/en/table/07964/",
                    Tid = c("2021", "2022"), # Define year to 2021 and 2022
                    NACE2007 = "G-N", # Define the services sector
                    ContentsCode = c("KvinneligFoUpers")) # Define women R&D personell

    mydata <- mydata[[1]] # Extract the first list element, which contains full variable names.

    head(mydata)

      industry (SIC2007)             contents year value
    1     Services total Female R&D personnel 2021  4904
    2     Services total Female R&D personnel 2022  5449

6. Show additional information.

    comment(mydata)

                                                                                                      label
    "07964: O07964: R&D personnel and R&D full-time equivalents (FTE) in Business Enterprise sector, by industry (SIC2007), contents and year"
                                                                                                     source
                                                                                        "Statistics Norway"
                                                                                                    updated
                                                                                     "2025-02-24T07:00:00Z"
                                                                                                    tableid
                                                                                                    "07964"
                                                                                                   contents
          "07964: O07964: R&D personnel and R&D full-time equivalents (FTE) in Business Enterprise sector,"
                                                                                                      note1
                                               "The table includes enterprises with at least 10 employees."
                                                                                                      note2
    "R&D personnel include employees that perform R&D in the enterprises (internal R&D personnel). External or hired R&D personnel are not included."

## 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 in general see PxWebApi User Guide.