API Cube PxAPIv1

Home / API / Cube PxAPIv1

Summary

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.

Request url

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.

Read Subjects

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

Read Products

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

Read Collection for 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

Read Metadata of a 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 /pxapiv1/en/4/C2016P3/TSA02

{
title: "Persons aged 25-64 who participated in non-formal education (%)",
variables: [
{
code: "Statistic",
text: "Persons aged 25-64 who participated in non-formal education (%)",
values: [
"740f2ad00b408b25fc5659da7b301cd2"
],
elimination: false
},
{
code: "TLIST(A1)",
text: "Year",
values: [
"2017"
],
elimination: false
},
{
code: "C02196V02652",
text: "Region",
values: [
"IE11",
"IE12",
"IE13",
"IE21",
"IE22",
"IE23",
"IE24",
"IE25"
],
elimination: false
},
{
code: "C02199V02655",
text: "Sex",
values: [
"-",
"1",
"2"
],
elimination: false
},
{
code: "C03459V04182",
text: "Reason for Participation",
values: [
"01",
"02",
"03",
"04",
"05",
"06",
"07",
"08",
"09",
"10",
"11",
"12",
"13",
"14"
],
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

Read Table Data

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.

Logging

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