API Cube PxAPIv1
Home / API / Cube PxAPIv1
The PxAPIvi interface uses a REST-like endpoint to return data and metadata. 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, either as a Query Definition (i.e. in the url of a GET request) or in the Request Body (in the case of a POST request). The query will filter the data to be returned.
The format of the Request url is as follows:
/api.restful/PxStat.Data.Cube_API.PxAPIv1/{language}/[subject]/[product]/[table]/?[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:
/pxapiv1/language/
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 The data is formatted as a JSON-stat object. This is equivalent to a standard JSON-stat object except without the data.
/pxapiv1/language/subject/product/table
Output example for /pxapiv1/en/4/C2016P3/TSA02
{
"jsonrpc": "2.0",
"result": {
"class": "dataset",
"dimension": {
"STATISTIC": {
"category": {
"index": [
"TSA02C1",
"TSA02C2",
"TSA02C3"
],
"label": {
"TSA02C1": "Trade Price Index for Imports (Base 2010=100)",
"TSA02C2": "Trade Price Index for Exports (Base 2010=100)",
"TSA02C3": "Terms of Trade Index (Base 2010=100)"
},
"unit": {
"TSA02C1": {
"decimals": 1,
"label": "Base 2010=100",
"position": "end"
},
"TSA02C2": {
"decimals": 1,
"label": "Base 2010=100",
"position": "end"
},
"TSA02C3": {
"decimals": 1,
"label": "Base 2010=100",
"position": "end"
}
}
},
"label": "Statistic"
},
"TLIST(A1)": {
"category": {
"index": [
"2016",
"2017",
"2018",
"2019"
],
"label": {
"2016": "2016",
"2017": "2017",
"2018": "2018",
"2019": "2019"
}
},
"label": "Year"
},
"AASTATE": {
"category": {
"index": [
"-"
],
"label": {
"-": "State"
}
},
"label": "State"
}
},
"extension": {
"matrix": "TSA02",
"reasons": [],
"language": {
"code": "en",
"name": "English"
},
"contact": {
"name": "John Carroll",
"email": "[email protected]",
"phone": ""
},
"subject": {
"code": 11,
"value": "Business Expenditure on Research and Development"
},
"product": {
"code": "BERD",
"value": "BERD Region"
},
"official": true,
"copyright": {
"name": "Central Statistics Office, Ireland",
"code": "CSO",
"href": "https://www.cso.ie"
},
"exceptional": true,
"reservation": false,
"archive": false,
"analytical": false,
"dependency": false
},
"href": "https://dev-ws.cso.ie/public/api.restful/PxStat.Data.Cube_API.ReadDataset/TSA02/JSON-stat/2.0/en",
"id": [
"STATISTIC",
"TLIST(A1)",
"AASTATE"
],
"label": "Merchandise Trade Price Indices",
"link": {
"alternate": [
{
"type": "text/csv",
"href": "https://dev-ws.cso.ie/public/api.restful/PxStat.Data.Cube_API.ReadDataset/TSA02/CSV/1.0/en"
},
{
"type": "application/json",
"href": "https://dev-ws.cso.ie/public/api.restful/PxStat.Data.Cube_API.ReadDataset/TSA02/JSON-stat/1.0/en"
},
{
"type": "text/plain",
"href": "https://dev-ws.cso.ie/public/api.restful/PxStat.Data.Cube_API.ReadDataset/TSA02/PX/2013/en"
},
{
"type": "application/base64",
"href": "https://dev-ws.cso.ie/public/api.restful/PxStat.Data.Cube_API.ReadDataset/TSA02/XLSX/2007/en"
}
]
},
"note": [],
"role": {
"metric": [
"STATISTIC"
],
"time": [
"TLIST(A1)"
]
},
"size": [
3,
4,
1
],
"updated": "2020-07-08T11:51:48.437Z",
"version": "2.0"
},
"id": null
}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).
For details of the Query object, please see Data Formats
GET Request /pxapiv1/language/subject/product/table?query={query}
An example of a query included in the Query Definition is:
/pxapiv1/en/4/C2016P3/TSA02/?query={"class": "query",
"id": [
"STATISTIC",
"TLIST(A1)"
],
"dimension": {
"STATISTIC": {
"category": {
"index": [
"TSA02C3"
]
}
},
"TLIST(A1)": {
"category": {
"index": [
"2019",
"2018"
]
}
}
},
"extension": {
"language": {
"code": "en"
},
"format": {
"type": "JSON-stat",
"version": "2.0"
},
"matrix": "TSA02"
},
"version": "2.0"
}
}
}
Alternatively, we can make the call as /pxapiv1/en/4/C2016P3/TSA02/ while including the query in the body of the Request.
In the example below, we want to filter as follows:
- Only data for STATISTIC with code TSA02C3 (1 item)
- Only data for TLIST(A1) with codes 2018 and 2019 (2 items)
- Looking at the metadata tells us there's another dimen sion called AASTATE. However, as we want all values of AASTATE, we do not include a filter for this dimension. There is 1 item in this dimension
The total number of datapoints returned will be 1 x 2 x 1, i.e. 2 datapoints. The ordering is per the metadata, i.e. STATISTIC, TLIST(A1), AASTATE.
A JSON-stat object is returned, see below:
{
"jsonrpc": "2.0",
"result": {
"class": "dataset",
"dimension": {
"STATISTIC": {
"category": {
"index": [
"TSA02C3"
],
"label": {
"TSA02C3": "Terms of Trade Index (Base 2010=100)"
},
"unit": {
"TSA02C3": {
"decimals": 1,
"label": "Base 2010=100",
"position": "end"
}
}
},
"label": "Statistic"
},
"TLIST(A1)": {
"category": {
"index": [
"2018",
"2019"
],
"label": {
"2018": "2018",
"2019": "2019"
}
},
"label": "Year"
},
"AASTATE": {
"category": {
"index": [
"-"
],
"label": {
"-": "State"
}
},
"label": "State"
}
},
"extension": {
"matrix": "TSA02",
"reasons": [],
"language": {
"code": "en",
"name": "English"
},
"contact": {
"name": "John Carroll",
"email": "[email protected]",
"phone": ""
},
"subject": {
"code": 11,
"value": "Business Expenditure on Research and Development"
},
"product": {
"code": "BERD",
"value": "BERD Region"
},
"official": true,
"copyright": {
"name": "Central Statistics Office, Ireland",
"code": "CSO",
"href": "https://www.cso.ie"
},
"exceptional": true,
"reservation": false,
"archive": false,
"analytical": false,
"dependency": false
},
"href": "https://dev-ws.cso.ie/public/api.restful/PxStat.Data.Cube_API.ReadDataset/TSA02/JSON-stat/2.0/en",
"id": [
"STATISTIC",
"TLIST(A1)",
"AASTATE"
],
"label": "Merchandise Trade Price Indices",
"link": {
"alternate": [
{
"type": "text/csv",
"href": "https://dev-ws.cso.ie/public/api.restful/PxStat.Data.Cube_API.ReadDataset/TSA02/CSV/1.0/en"
},
{
"type": "application/json",
"href": "https://dev-ws.cso.ie/public/api.restful/PxStat.Data.Cube_API.ReadDataset/TSA02/JSON-stat/1.0/en"
},
{
"type": "text/plain",
"href": "https://dev-ws.cso.ie/public/api.restful/PxStat.Data.Cube_API.ReadDataset/TSA02/PX/2013/en"
},
{
"type": "application/base64",
"href": "https://dev-ws.cso.ie/public/api.restful/PxStat.Data.Cube_API.ReadDataset/TSA02/XLSX/2007/en"
}
]
},
"note": [],
"role": {
"metric": [
"STATISTIC"
],
"time": [
"TLIST(A1)"
]
},
"size": [
1,
2,
1
],
"updated": "2020-07-08T11:51:48.437Z",
"value": [
99.6,
103.0
],
"version": "2.0"
},
"id": null
}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
