API Cube PxAPIv1
Home / API / Cube PxAPIv1
The PxAPIvi interface uses a REST-like endpoint to return data and metadata. This is included for backward compatibility and it emulates the version used by Statistics Sweden, see https://www.scb.se/en/services/oppna-data/api-for-the-statistical-database/.
The following data/metadata may be returned by the interface:
- Available Subjects.
- Available Products for a Subject.
- Current data tables for a Product.
- Metadata for a table.
- Data for a table. This will require a query object being passed, as a Query Definition . The query will filter the data to be returned. Data requested in the formats "csv" and "xlsx" will be pivoted on the time dimension by default. This data may be pivoted on any of the other dimensions by specifying it in the url.
The format of the Request url is as follows:
/api.restful/PxStat.Data.Cube_API.PxAPIv1/{language}/[subject]/[product]/[table]/[pivot-dimension]?[query definition]
Optional parameters are shown in square brackets, however if an optional parameter is included then all of the preceding parameters must be included as well. The number of parameters included will define the nature of the returned data.
The call shown below will return a list of valid live Subjects. English language versions will be delivered where possible:
/api.restful/PxStat.Data.Cube_API.PxAPIv1/en
The "language" parameter in this case represents the user's preferred language. If the data is available in that language, the output will be in that language. If not, then the data will be delivered in the default language of the system.
The language parameter must conform to the ISO 639-1 code, e.g. English="en", Irish="ga", Swedish="sv" etc.
Output example for /api.restful/PxStat.Data.Cube_API.PxAPIv1/en/:
[
{
"id": "11",
"type": "l",
"text": "Business Expenditure on Research and Development"
},
{
"id": "4",
"type": "l",
"text": "Census 2016"
},
{
"id": "7",
"type": "l",
"text": "jcsubject"
},
{
"id": "8",
"type": "l",
"text": "LMNEW"
},
{
"id": "3",
"type": "l",
"text": "Prices"
},
{
"id": "2",
"type": "l",
"text": "RPSubject"
}
]
Subject:
| Name | Type | Description |
|---|---|---|
id |
String | Subject Identifier |
type |
String | 'l' in the case of a Subject |
text |
String | Name of the subject |
The call shown below will return a list of valid live Products for a given Subject:
/api.restful/PxStat.Data.Cube_API.PxAPIv1/language/subject Output example for /api.restful/PxStat.Data.Cube_API.PxAPIv1/en/4:
[
{
"id": "C2016P3",
"type": "l",
"text": "Profile 3 - An Age Profile of Ireland"
},
{
"id": "CODE2",
"type": "l",
"text": "Profile 1 - Housing in Ireland"
},
{
"id": "CODE3",
"type": "l",
"text": "Profile 1 - Housing in Ireland"
},
{
"id": "CP1HII",
"type": "l",
"text": "Profile 1 - Housing in Ireland"
}
]Product:
| Name | Type | Description |
|---|---|---|
id |
String | Subject Identifier |
type |
String | 'l' in the case of a Product |
text |
String | Name of the Product |
The call shown below will return a list of live tables for a given Product.
/api.restful/PxStat.Data.Cube_API.PxAPIv1/language/subject/product Output example for /api.restful/PxStat.Data.Cube_API.PxAPIv1/en/4/C2016P3
[
{
"id": "E3002ENOnly",
"type": "t",
"text": "Population 2011 to 2016"
},
{
"id": "CENSUS2",
"type": "t",
"text": "Population by local gov districts"
},
{
"id": "AHM04",
"type": "t",
"text": "Agricultural Input and Output Price Indices (Base 2015=100)"
},
{
"id": "AHM04DR123",
"type": "t",
"text": "Agricultural Input and Output Price Indices (Base 2015=100)"
},
{
"id": "LIAMTESTFNA08",
"type": "t",
"text": "Foreign Nationals in Employment (Number)"
},
{
"id": "LIAMTESTPEC18",
"type": "t",
"text": "Projected Annual Births"
}
]Table:
| Name | Type | Description |
|---|---|---|
id |
String | Table Identifier |
type |
String | 't' in the case of a Table |
text |
String | Name of the Table |
The call shown below will return the metadata for a table.
/api.restful/PxStat.Data.Cube_API.PxAPIv1/language/subject/product/table
Output example for /api.restful/PxStat.Data.Cube_API.PxAPIv1/en/4/C2016P3/TSA02.
{
"title": "Greenhouse Gas Emissions",
"variables": [
{
"code": "Statistic",
"text": "Greenhouse Gas Emissions",
"values": [
"EAA09C1",
"EAA09C2",
"EAA09C3",
"EAA09C4"
],
"valueTexts": [
"Greenhouse Gas Emissions (CO2, N2O, CH4, HFC, PFC, SF6)",
"Carbon Dioxide (CO2) Emissions",
"Nitrous Oxide (N2O) Emissions",
"Methane (CH4) Emissions"
],
"elimination": false
},
{
"code": "TLIST(A1)",
"text": "Year",
"values": [
"2009",
"2010",
"2011",
"2012",
"2013",
"2014",
"2015",
"2016",
"2017"
],
"valueTexts": [
"2009",
"2010",
"2011",
"2012",
"2013",
"2014",
"2015",
"2016",
"2017"
],
"elimination": false
},
{
"code": "C02597V03821",
"text": "Sector NACE Rev 2",
"values": [
"19",
"20",
"21",
"26",
"27",
"28",
"35",
"V0100",
"V0800",
"V1505",
"V1900",
"V2400",
"V2715",
"V3430",
"V3500",
"V3700",
"V3920",
"V3945",
"V3960",
"V39845",
"ZXD100",
"ZXD200"
],
"valueTexts": [
"Coke and refined petroleum products (19)",
"Chemicals and chemical products (20)",
"Basic pharmaceutical products and preparations (21)",
"Computer, electronic and optical products (26)",
"Electrical equipment (27)",
"Machinery and equipment n.e.c. (28)",
"Electricity, gas, steam and air conditioning supply (35)",
"Agriculture, forestry and fishing (01 to 03)",
"Mining and quarrying (05 to 09)",
"Industries and construction (05 to 43)",
"Food products, beverages and tobacco (10 to 12)",
"Textiles, wearing apparel and leather products (13 to 15)",
"Wood, paper, printing and reproduction of recorded media (16 to 18)",
"Rubber and plastic products, other non-metallic mineral products (22,23)",
"Basic metals and fabricated metal products (24,25)",
"Transport equipment (29,30)",
"Furniture, and other manufacturing, repair and installation of machinery and equipment (31 to 33)",
"Water supply; sewerage, waste management and remediation activities (36 to 39)",
"Construction (41 to 43)",
"Services (45 to 96)",
"Households",
"Total emissions"
],
"elimination": false
}
]
}
Metadata: The metadata consists of:
- "title" : String value of the table title.
- Array of "variables" - see below. A variable is a representation of a dimension including its dimension items.
Variable:
| Name | Type | Description |
|---|---|---|
code |
String | Dimension code |
text |
String | Dimension description |
values |
String[] | Array of codes for the dimension items |
elimination |
Boolean | Indicates if elimination is used in the table. For PxStat this will always be false |
The call shown below will return the data for a table. The query object enables us to filter the data by any combination of dimension value or values. The query will exist either as a Query Definition at the end of the url (e.g. a GET request) or in the Request Body (e.g. a POST request).
GET Request /api.restful/PxStat.Data.Cube_API.PxAPIv1/language/subject/product/table?query={query} for example: /api.restful/PxStat.Data.Cube_API.PxAPIv1/en/4/CODE2/E1022?query={"query":[{"code":"STATISTIC","selection":{"filter":"item","values":["E1022C01","E1022C02"]}},{"code":"TLIST(A1)","selection":{"filter":"item","values":["2011","2016"]}}],"response":{"format":"json-stat"}}
Query Definition:
| Name | Type | Description |
|---|---|---|
query |
Array of Query dimensions | Query dimensions |
response |
response | Description of returned data |
Response:
| Name | Type | Description |
|---|---|---|
format |
String | The required format of the output |
Allowed values of format
- json-stat - returns the data in JSON-stat 2.0 format
- csv - returns the data in csv format
- xlsx - returns the data in xlsx format
- px- returns the data in PX 2013 format
Query:
| Name | Type | Description |
|---|---|---|
code |
String | Dimension code |
selection |
selection | Selection description |
Selection:
| Name | Type | Description |
|---|---|---|
filter |
String | default to 'item' |
values |
String array | list of item codes |
In the example below, we want to filter as follows:
- Only data for STATISTIC with code E1022C01 and E1022C02 (2 items).
- Only data for TLIST(A1) with codes 2011 and 2016 (2 items).
- Looking at the metadata tells us there's a called C02196V02652. However, as we want all values of C02196V02652, we do not include a filter for this dimension. There are 8 items in this dimension.
- There is also a dimension called C02699V03267. Again we want all values for this dimension and so we don't include a filter for it. There are 4 items in this dimension.
The total number of datapoints returned will be 2 x 2 x 8 x 4, i.e. 128 datapoints. The ordering is per the metadata, i.e. STATISTIC, TLIST(A1), C02196V02652, C02699V03267.
By default, data requested in the csv and xlsx formats will be displayed pivoted on the time dimension, i.e. a value will be shown for each item in the time dimension on any given tuple. If the data needs to be pivoted on any other dimension, this may be done by specifying the dimension code in the request url. For example:
/api.restful/PxStat.Data.Cube_API.PxAPIv1/en/4/CODE2/E1022/C02010V02440/?query={"query":[{"code":"STATISTIC","selection":{"filter":"item","values":["E1022C01","E1022C02"]}},{"code":"TLIST(A1)","selection":{"filter":"item","values":["2011","2016"]}}],"response":{"format":"xlsx"}}
The "C02010V02440" parameter will ensure that the data will be pivoted on the C02010V02440 dimension instead of the time dimension.
Data may only be pivoted on one dimension at a time.
The following data is retained by the system as part of the API read process:
- All HTTP logs.
- IP address of caller.
- Parameters of the call.
- Data for analysis, e.g. browser type, operating system etc
- Date and time.
