Australian Bureau of Statistics

Rate the ABS website
ABS @ Facebook ABS @ Twitter ABS RSS ABS Email notification service

ABS ITT User Documentation

Introduction

The ABS ITT is a restful query interface for the ABS.Stat data warehouse.

ITT allows a programmer to easily call ABS.Stat using simple restful url queries to retrieve, data, concepts, codelists and other details of available ABS.Stat datasets.

All queries share the same general method of use, eg:

http://stat.abs.gov.au/itt/query.jsp?method=GetCodeListValue&datasetid=LF&concept=TSEST&format=json

Here you can see each query starts with:

http://stat.abs.gov.au/itt/query.jsp?method=

and then follows one of the methods, in this instance GetCodeListValue. After that are the parameters to the method call.

There are four methods available for use with the ABS ITT - GetDatasetList, GetDatasetConcepts, GetCodeListValue and GetGenericData.

Details on how to access each method are available below.

GetDatasetList
GetDatasetList returns a JSON list of the available datasets and each dataset description. There are no parameters.

Example:
http://stat.abs.gov.au/itt/query.jsp?method=GetDatasetList

Returns an output like this:
{
    "datasets": [
        {
            "id": "ERP_ASGS",
            "description": "Annual Population Estimates (ERP) by Statistical Area, Sex and Age"
        },
        {
            "id": "ALC",
            "description": "Apparent Consumption of Alcohol, Australia"
        },
        {
            "id": "TOUR_ACCOM",
            "description": "Tourist Accommodation"
        },
        {
            "id": "IAS_5",
            "description": "Volume of data downloaded by type of access connection"
        },
        {
            "id": "LABOUR_PRICE_INDEX",
            "description": "Wage Price Index"
        }
    ],
    "copyright": "ABS (c) copyright Commonwealth of Australia 2014. Retrieved on 3/06/2014 at 10:37"
}

GetDatasetConcepts
Returns a JSON list of the available concepts in a dataset. There is one parameter, datasetid.

Example:
http://stat.abs.gov.au/itt/query.jsp?method=GetDatasetConcepts&datasetid=LF

Returns an output like this:
{
    "concepts": [
        "ASGC_2010",
        "ITEM",
        "SEX_ABS",
        "AGE",
        "TSEST",
        "FREQUENCY"
    ],
    "copyright": "ABS (c) copyright Commonwealth of Australia 2014. Retrieved on 3/06/2014 at 10:38"
}
Parameter Allowable Values Examples
datasetid Any dataset ID in ABS.Stat. These can be retrieved using the GetDatasetList method.
Note: Case sensitive
LF, CPI, ABS_CENSUS2011_B01

An example page that uses the GetDatasetList, and GetCodeListValue methods to return codelists is available here
GetCodeListValue
GetCodeListValue returns the results of a query regarding a code list used in a dataset. This can include the codes, associated descriptions and parent or child relationships between codes. Codelists are also known as dimensions or categories.

This method has two required parameters, datasetid and concept. It also has a number of optional parameteres including code and relationship.

Examples:
This request will return the code list details of the Labour Force dataset (datasetid=LF) for the time series estimate concept (concept=TSEST).
http://stat.abs.gov.au/itt/query.jsp?method=GetCodeListValue&datasetid=LF&concept=TSEST&format=json
{
    "codes": [
        {
            "code": "10",
            "description": "Original",
            "parentCode": "",
            "parentDescription": ""
        },
        {
            "code": "20",
            "description": "Seasonally Adjusted",
            "parentCode": "",
            "parentDescription": ""
        },
        {
            "code": "30",
            "description": "Trend",
            "parentCode": "",
            "parentDescription": ""
        },
        {
            "code": "Labour Force",
            "description": "Labour Force",
            "parentCode": "",
            "parentDescription": ""
        }
    ],
    "copyright": "ABS (c) copyright Commonwealth of Australia 2014. Retrieved on 1/06/2014 at 13:54"
}
Parameter Allowable Values Examples
datasetid Any dataset ID in ABS.Stat. These can be retrieved using the GetDatasetList method.
Note: Case sensitive
LF, CPI, ABS_CENSUS2011_B01
concept The concept within the selected dataset that you wish to retrieve. These can be retrieved using the GetDatasetConcept method.
Note: Case sensitive
AGE, TSEST, SEX_ABS
code Any code from within the specified concept. Multiple codes can be selected using comma separated lists. If no code is specified the entire codelist will be returned
Note: Case sensitive
1,8,50,OTH,V
relationship Can only be used in conjunction with the code parameter. The allowable values are:
  • parent
  • children
  • parentCode
children - returns all direct child codes of the given code
parent - returns the parent code and description
parentCode - returns just the parent code of the given code

An example page that uses the GetDatasetList, and GetCodeListValue methods to return codelists is available here
GetGenericData
GetGenericData performs an SDMX query on an ABS.Stat dataset and returns data for a specified combination of codes. This method has two required parameters, datasetid and an and parameter specifying the codes requested.

GetGenericData also has a large number of additional parameters to assist with filtering data, formatting output, and performing calculations.

Example:
GetGenericData queries take the following form. GetGenericData is followed by the required datasetid=LF and and=ASGC_2010.0.... The optional filtering parameter start=2006-07 is appended after the required parameters.
http://stat.abs.gov.au/itt/query.jsp?method=GetGenericData&datasetid=LF&­and=ASGC_2010.0,ITEM.14,SEX_ABS.3,AGE.1599,TSEST.30,FREQUENCY.M&­&start=2006-07

Parameter Allowable Values Examples
datasetid Any dataset ID in ABS.Stat. These can be retrieved using the GetDatasetList method.
Note: Case sensitive
LF, CPI, ABS_CENSUS2011_B01
and A list of comma separated concepts and values for the and and part of the query. The format is CONCEPT.VALUE. &and=ASGC_2010.0
or A list of comma separated concepts and values for the or and part of the query. The format is CONCEPT.VALUE. &or=ASGS.1
orParent A code in the format CONCEPT.VALUE.
Uses all children of the specified code for the query.
&orParent=ASGC_2010.0
All codes with the parent ASGC_2010.0 (Australia) are selected. Data for all states would be returned.
start Start date in the appropriate format &start=2006 : Annual data
&start=2006-Q3 : Quarterly data
&start=2006-11 : Monthly data
end End date in the appropriate format &end=2006
top Integer. Returns a sorted list of the top N results. &top=10
&top=-1 will return all results in a sorted list.
bottom Integer. Returns a sorted list of the bottom N results. &bottom=10
&bottom=-1 will return all results in a sorted list.
series latest or years &series=latest : Returns values from the latest series in the dataset.
&series=2009,2010,2005 : Returns values for 2005,2009 and 2010
format See Formats, Callback and JSONP below

Further Examples:

This request will retrieve the top 5 unemployment data periods after 2006-03 from the Labour Force dataset (LF).
http://stat.abs.gov.au/itt/query.jsp?method=GetGenericData&datasetid=LF&­and=ASGC_2010.0,ITEM.14,SEX_ABS.3,AGE.1599,TSEST.30,FREQUENCY.M&­TIME_FORMAT=P1M&start=2006-03&format=vtable&top=5

TimeValue
2014-025.9086673
2014-015.902197
2014-035.8978536
2014-045.8778427
2013-125.8750841

Query the total unemployment from 2013-12. Note the use of the or=ASGC_2010 which controls what concept produces the description.
http://stat.abs.gov.au/itt/query.jsp?method=GetGenericData&datasetid=LF&or=ASGC_2010&and­=ASGC_2010.0,ITEM.14,SEX_ABS.3,AGE.1599,TSEST.30,FREQUENCY.M&TIME_FORMAT=P1M&start=2013-12&format=htable

ASGC_2010Description2013-122014-012014-022014-032014-042014-05
0Total5.87508415.9021975.90866735.89785365.87784275.8547221

This is the same query with a different or= concept so that the TSEST drives the description.
http://stat.abs.gov.au/itt/query.jsp?method=GetGenericData&datasetid=LF&or=TSEST&and­=ASGC_2010.0,ITEM.14,SEX_ABS.3,AGE.1599,TSEST.30,FREQUENCY.M&TIME_FORMAT=P1M&start=2013-12&format=htable

TSESTDescription2013-122014-012014-022014-032014-042014-05
30Trend5.87508415.9021975.90866735.89785365.87784275.8547221

GetGenericData - Calc Function
The calc parameter can be used with the GetGenericData method to perform calculations and comparisons between data within the same dataset. Through the use of calc parameters a second query is defined, followed by the operation to be performed.

Example

This query disaplys the difference in male and female labour force. The first series is defined as usual, followed by a second using calcDatasetid,calcCode and calcAnd. Finally the calc operation minusCV is specified to show the difference.
http://stat.abs.gov.au/itt/query.jsp?method=GetGenericData&datasetid=LF&­and=ASGC_2010.0,ITEM.4,SEX_ABS.1,AGE.1599,TSEST.30&­or=ASGC_2010&start=2013-01&format=htable&­calcDatasetid=LF&calcAnd=ASGC_2010.0,ITEM.4,SEX_ABS.2,AGE.1599,TSEST.30&­calc=minusCV&calcCode=ASGC_2010
Parameter Allowable Values Examples
calcDatasetid Any dataset ID in ABS.Stat. Must be the same as used in datasetid
Note: Case sensitive
calcAnd As with and
calcOr As with or
calcCode Any concept in the dataset Used to specify the category across which the calculations will be made.
calc
  • percent
  • minus
  • minusCV
  • multiply
  • divideCV
  • divide
  • plus
  • change
  • changePercent
Specifies the operation to be performed.
CV operations are the reverse of standard, eg minus is A-B while minusCV is B-A.
Further Examples

To view the change population projections from one time period to the next for Australia, with different mortality assumptions. Note the first column of the table is the starting number, and the following columns the year on year change.
http://stat.abs.gov.au/itt/query.jsp?method=GetGenericData&datasetid=POP_PROJ_2011&or­=MORTALITY.1.2&and­=ASGS_2011.0,SEX_ABS.3,AGE.TT,FERTILITY.1,NOM.1&­start=2090&format=htable&calc=change

MORTALITYDescription209020912092209320942095209620972098209921002101
1High life expectancy64194852533008533084533240533336533352533240533128532920532632532200531688
2Medium life expectancy60958740495540495668495620495400494992494424493692492820491816490704489536


To view the difference in male and female labour force. Two datasets area used by using calcAnd, calcDatasetid,calcCode with the calc operation minusCV.
http://stat.abs.gov.au/itt/query.jsp?method=GetGenericData&datasetid=LF&­and=ASGC_2010.0,ITEM.4,SEX_ABS.1,AGE.1599,TSEST.30&­or=ASGC_2010&start=2013-01&format=htable&­calcDatasetid=LF&calcAnd=ASGC_2010.0,ITEM.4,SEX_ABS.2,AGE.1599,TSEST.30&­calc=minusCV&calcCode=ASGC_2010

ASGC_2010Description2013-062013-072013-082013-092013-102013-112013-122014-012014-022014-032014-042014-05
0Total6220.3006220.1836217.7236214.1696212.2316215.1476223.3906234.9536247.3506258.6966267.9286274.487
Formats, Callback and JSONP
In addition to the query parameters, most methods allow two additional parameters to determine the format of the response returned, format= and callback=.

Format

The format= function allows users to specify the format of the response returned by GetCodeListValue and GetGenericData
For certain formats additional parameters are available to further define the response.
Parameter Allowable Values Examples
format For use with GetCodeListValue
  • table
  • json
  • count
  • code

For use with GetGenericData
  • csv
  • htable
  • vtable
  • json
  • latest
  • excel
&format=table : Returns a HTML formatted table with columns Code, Description, ParentCode
&format=json : Returns a JSON formatted response.
&format=count :Returns a single number response of the count of codes
&format=code : Returns a comma separated list. Only for use with relationship= queries

&format=json :(default) Returns a JSOn formatted response.
&format=csv : Returns data in CSV format
&format=htable : Returns a HTML formatted table with time periods on the x axis.
&format=vtable : Returns a HTML formatted table with time periods on the y axis.
&format=latest : Returns the last value of the last series in the query as plain text.
&format=excel : Returns an xls spreadsheet of the results (experimental)
nf For use with GetGenericData. Specifies the number format to be returned
  • 1
  • 2
&nf=1 - thousand separator is a space.
&nf=2 - thousand separator is a comma.
missing Code to be inserted for a missing value when using format=htable &missing=-- (default)
periods Comma separated list of years to be displayed when using format=htable &periods=2007,2008,2009,2010
class Text, specifies the class name when using format=htable or format=vtable &class=NRPtableType
&class=GetGenericDataHtable (default when format=htable)
&class=GetGenericDataVtable (default when format=vtable)
Callback and JSONP

The &callback= parameter can be used to return a JSONP response, wrapping the query response in a function call to allow for cross domain access within the page.

As an example, while this query
http://stat.abs.gov.au/itt/query.jsp?method=GetGenericData­&datasetid=LF&or=ASGC_2010­&and=ASGC_2010.0,ITEM.14,SEX_ABS.3,AGE.1599,TSEST.30,FREQUENCY.M­&TIME_FORMAT=P1M&format=latest
returns the plain text response of
5.8547221
adding the parameter &callback=foo
http://stat.abs.gov.au/itt/query.jsp?method=GetGenericData­&datasetid=LF&or=ASGC_2010­&and=ASGC_2010.0,ITEM.14,SEX_ABS.3,AGE.1599,TSEST.30,FREQUENCY.M­&TIME_FORMAT=P1M&format=latest&callback=foo
results in a .js file containing
foo( {"text": "5.8547221"} )
which can be directly processed using the script element.
Example jQuery Code

Example JSONP jQuery call

var server = 'http://stat.abs.gov.au/itt/';
$.ajax( { url:server+'query.jsp?method=GetDatasetList&callback=?',
dataType : 'jsonp',
success : function (data){
for( d in data.datasets){
// data.datasets[d].id + data.datasets[d].description
}
}
});

Example of JSONP jQuery call to retrieve dataset listing

Open getDatasets page

Example of JSONP jQuery call to retrieve data

Open getData page

Example of getJSON jQuery call to retrieve a dataset list

Open getCodelist page

Example of getJSON jQuery call using GetDatasetList, and GetCodeListValue to find and retrieve available codelists

Open getCodelist page

Bookmark and Share. Opens in a new window

© Commonwealth of Australia 2014

Unless otherwise noted, content on this website is licensed under a Creative Commons Attribution 2.5 Australia Licence together with any terms, conditions and exclusions as set out in the website Copyright notice. For permission to do anything beyond the scope of this licence and copyright terms contact us.