About the Beta
This beta release allows you to preview ABS Data API before it is released in its final form and gives you the opportunity to provide the ABS with feedback as we work to enhance the service.
We will continue to load new datasets and update existing datasets as soon as possible after embargo on the data is lifted. However, data in this beta release may not necessarily be the most up to date. For the most up to date information visit the ABS website.
Availability of the ABS Data API (Beta) is not guaranteed. The service may be subject to change.
You can contact the ABS APIs team at api.data@abs.gov.au. Please let us know any feedback or issues you have. You can request to join our register of interest to be notified of any changes in the API. The ABS privacy policy outlines how the ABS handles any personal information that you provide to us.
Key Information
The ABS Data REST API allows you to request ABS statistics including detailed economic, social and Census data. Filter your query to return the data and metadata you are interested in.
The ABS Data API uses the Statistical Data and Metadata Exchange (SDMX) standard. Data is available in XML, JSON and CSV.
contact:
email: api.data@abs.gov.au
host: data.api.abs.gov.au
externalDocs:
description: SDMX RESTful web services specification on GitHub
url: https://github.com/sdmx-twg/sdmx-rest/wiki
schemes:
- https
paths:
'/rest/data/{dataflowIdentifier}/{dataKey}':
get:
tags:
- Get Data
summary: Get data from a dataflow in XML, JSON or CSV.
operationId: GetData
consumes: []
produces:
- application/vnd.sdmx.data+json
- application/xml
- application/vnd.sdmx.structurespecificdata+xml
- text/csv
- application/vnd.sdmx.data+csv
- application/vnd.sdmx.data+csv;labels=both
- application/vnd.sdmx.data+csv;file=true;labels=both
parameters:
- name: dataflowIdentifier
in: path
description: |
The dataflow identifier in {agencyId},{dataflowId},{version} format (eg. "ABS,CPI,1.1.0").
A list of all available dataflows can be returned using the *GET /rest/{structureType}/{agencyId}* operation.
agencyId and version are optional. If agencyId is not specified it will default to “all”. If version is not specified it will default to “latest”.
required: true
type: string
- name: dataKey
in: path
description: |
The key to query data returned.
Use "all" if you would like to return all data for the dataset.
To filter data returned provide a data key, containing one or more coded values for each dimension, separated by a dot (dimensions must be in the order they are defined in the data structure).
For example “1.115486.10.50.Q” filters for a single Consumer Price Index series
* *Measure*: 1 - Index Number
* *Index*: 115486 - Health
* *Adjustment Type*: 10 - Original
* *Region*: 50 - Weighted average of eight capital cities
* *Frequency*: Q - Quarterly
Wildcarding is supported by omitting values for the dimension. Eg. data for all regions: “1.115486.10..Q”.
The OR operator is supported using the + character. Eg. data for 2 series “1.131188+131189.10.50.Q”.
You can combine wildcarding and the OR operator. Eg. “1.131188+131189.10..Q".
The maximum allowed length of this parameter is currently 260 characters. Requests that exceed this limit will return a 400 error. We intend to increase this limit soon.
The dataKey parameter is case sensitive.
required: true
type: string
- name: startPeriod
in: query
description: |
The start period (used to filter on time). This is inclusive. The value can be in the following formats:
* year: yyyy
* year-semester: yyyy-S1 - yyyy-S2
* year-quarter: yyyy-Q1 - yyyy-Q4
* year-month: yyyy-01 - yyyy-12
required: false
type: string
- name: endPeriod
in: query
description: |
The end period (used to filter on time). This is inclusive. The value can be in the following formats:
* year: yyyy
* year-semester: yyyy-S1 - yyyy-S2
* year-quarter: yyyy-Q1 - yyyy-Q4
* year-month: yyyy-01 - yyyy-12
required: false
type: string
- name: format
in: query
description: |
The format of data to return. Refer to the accept header if omitted.
* **csvwithlabels**: csv format with columns for dimension codes and labels.
* **csvfile**: csv format with columns for dimension codes.
* **jsondata**: sdmx json format equivalent to application/vnd.sdmx.data+json
* **genericdata**: sdmx xml format equivalent to application/vnd.sdmx.genericdata+xml
* **structurespecificdata**: sdmx xml format equivalent to application/vnd.sdmx.structurespecificdata+xml
required: false
type: string
enum:
- csvfilewithlabels
- csvfile
- jsondata
- genericdata
- structurespecificdata
- name: detail
in: query
description: |
The detail of data to return.
* **full**: The data - series and observations - and the attributes will be returned. This is the default.
* **dataonly**: The attributes will be excluded from the returned message.
* **serieskeysonly**: Only the series, but without the attributes and the observations, will be returned. This can be useful for performance reasons, to return the series that match a certain query, without returning the actual data.
* **nodata**: The series, including the attributes, will be returned, but the observations will not be returned.
required: false
type: string
enum:
- full
- dataonly
- serieskeysonly
- nodata
- name: dimensionAtObservation
in: query
description: |
Define the way data should be organized in the returned message. Possible options are:
* **TIME_PERIOD**: This will return a timeseries view of the data. This is the default value.
* **AllDimensions**: This will return a flat view of the data, with no groupings.
* **The ID of any other dimension**: This will return a cross-sectional view of the data.
required: false
type: string
responses:
'200':
description: Success
schema:
type: string
'404':
description: No records found
schema:
type: string
'/rest/{structureType}/{agencyId}':
get:
tags:
- Get Metadata
summary: Get all structures of a specific type.
operationId: GetStructuresByAgencyId
consumes: []
produces:
- application/xml
- application/vnd.sdmx.structure+json
parameters:
- name: structureType
in: path
description: The type of structure to retrieve.
required: true
type: string
enum:
- dataflow
- datastructure
- codelist
- conceptscheme
- categoryscheme
- contentconstraint
- actualconstraint
- agencyscheme
- categorisation
- hierarchicalcodelist
- name: agencyId
in: path
description: The id of the agency maintaining the structures. Eg. "ABS".
required: true
type: string
default: ABS
- name: detail
in: query
description: |
Specify the desired amount of detail to be returned. For example, it is possible to instruct the web service to return only basic information about the resource, this is known in SDMX as a stub.
* **allstubs**: All artefacts will be returned as stubs.
* **referencestubs**: The referenced artefacts will be returned as stubs.
* **referencepartial**: The referenced item schemes should only include items used by the artefact to be returned. For example, a concept scheme would only contain the concepts used in a DSD, and its isPartial flag would be set to true. As another example, if a dataflow is constrained, then the codelists returned should only contain the subset of codes allowed by that constraint.
* **allcompletestubs**: All artefacts should be returned as complete stubs, containing identification information, the artefacts' name, description, annotations and isFinal information.
* **referencecompletestubs**: The referenced artefacts should be returned as complete stubs, containing identification information, the artefacts' name, description, annotations and isFinal information.
* **full**: All available information for all artefacts will be returned. This is the default.
required: false
type: string
enum:
- full
- allstubs
- referencestubs
- referencepartial
- allcompletestubs
- referencecompletestubs
responses:
'200':
description: Success
schema:
type: string
'/rest/{structureType}/{agencyId}/{structureId}':
get:
tags:
- Get Metadata
summary: 'Get the latest structure of a specific type, for a given agency and structure id.'
operationId: GetLatestStructure
consumes: []
produces:
- application/xml
- application/vnd.sdmx.structure+json
parameters:
- name: structureType
in: path
description: The type of structure to retrieve.
required: true
type: string
enum:
- dataflow
- datastructure
- codelist
- conceptscheme
- categoryscheme
- contentconstraint
- actualconstraint
- agencyscheme
- categorisation
- hierarchicalcodelist
- name: agencyId
in: path
description: The id of the agency maintaining the structures. Eg. "ABS".
required: true
type: string
default: ABS
- name: structureId
in: path
description: The structure's id. "all" will return all artefacts of the selected structure type.
required: true
type: string
- name: references
in: query
description:
|
Instruct the web service to return (or not) the artefacts referenced by the artefact(s) you are querying. Eg. the codelists and concepts used by the data structure you are querying. You can also retrieve the artefacts that use the artefact you are querying, eg. the dataflows that use the data structure definition queried.
* **none**: No references will be returned. This is the default.
* **parents**: The artefacts that use the artefact matching the query (for example, the dataflows that use the data structure definition matching the query) will be returned.
* **parentsandsiblings**: The artefacts that use the artefact matching the query, as well as the artefacts referenced by these artefacts will be returned.
* **children**: The artefacts referenced by the matching artefact will be returned (for example, the concept schemes and code lists used in a DSD).
* **descendants**: References of references, up to any level, will also be returned.
* **all**: The combination of parentsandsiblings and descendants.
* In addition, a specific structure type may also be used (e.g. codelist, dataflow, etc.).
required: false
type: string
enum:
- none
- parents
- parentsandsiblings
- children
- descendants
- all
- datastructure
- dataflow
- codelist
- conceptscheme
- categoryscheme
- contentconstraint
- actualconstraint
- agencyscheme
- categorisation
- hierarchicalcodelist
- name: detail
in: query
description: |
Specify the desired amount of detail to be returned. For example, it is possible to instruct the web service to return only basic information about the resource, this is known in SDMX as a stub.
* **allstubs**: All artefacts will be returned as stubs.
* **referencestubs**: The referenced artefacts will be returned as stubs.
* **referencepartial**: The referenced item schemes should only include items used by the artefact to be returned. For example, a concept scheme would only contain the concepts used in a DSD, and its isPartial flag would be set to true. As another example, if a dataflow is constrained, then the codelists returned should only contain the subset of codes allowed by that constraint.
* **allcompletestubs**: All artefacts should be returned as complete stubs, containing identification information, the artefacts' name, description, annotations and isFinal information.
* **referencecompletestubs**: The referenced artefacts should be returned as complete stubs, containing identification information, the artefacts' name, description, annotations and isFinal information.
* **full**: All available information for all artefacts will be returned. This is the default.
required: false
type: string
enum:
- full
- allstubs
- referencestubs
- referencepartial
- allcompletestubs
- referencecompletestubs
responses:
'200':
description: Success
schema:
type: string
'/rest/{structureType}/{agencyId}/{structureId}/{structureVersion}':
get:
tags:
- Get Metadata
summary: 'Get a specific version of a structure of a specific type, for a given agency and structure id.'
operationId: GetStructures
consumes: []
produces:
- application/xml
- application/vnd.sdmx.structure+json
parameters:
- name: structureType
in: path
description: The type of structure to retrieve.
required: true
type: string
enum:
- dataflow
- datastructure
- codelist
- conceptscheme
- categoryscheme
- contentconstraint
- actualconstraint
- agencyscheme
- categorisation
- hierarchicalcodelist
- name: agencyId
in: path
description: The id of the agency maintaining the structures. Eg. "ABS".
required: true
type: string
default: ABS
- name: structureId
in: path
description: The structure's id. "all" will return all artefacts of the selected structure type.
required: true
type: string
- name: structureVersion
in: path
description: The version of the structure to retrieve. Three numbers separated by points, eg. "1.0.0".
required: true
type: string
- name: references
in: query
description:
|
Instruct the web service to return (or not) the artefacts referenced by the artefact(s) you are querying. Eg. the codelists and concepts used by the data structure you are querying. You can also retrieve the artefacts that use the artefact you are querying, eg. the dataflows that use the data structure definition queried.
* **none**: No references will be returned. This is the default.
* **parents**: The artefacts that use the artefact matching the query (for example, the dataflows that use the data structure definition matching the query) will be returned.
* **parentsandsiblings**: The artefacts that use the artefact matching the query, as well as the artefacts referenced by these artefacts will be returned.
* **children**: The artefacts referenced by the matching artefact will be returned (for example, the concept schemes and code lists used in a DSD).
* **descendants**: References of references, up to any level, will also be returned.
* **all**: The combination of parentsandsiblings and descendants.
* In addition, a specific structure type may also be used (e.g. codelist, dataflow, etc.).
required: false
type: string
enum:
- none
- parents
- parentsandsiblings
- children
- descendants
- all
- datastructure
- dataflow
- codelist
- conceptscheme
- categoryscheme
- contentconstraint
- actualconstraint
- agencyscheme
- categorisation
- hierarchicalcodelist
- name: detail
in: query
description: |
Specify the desired amount of detail to be returned. For example, it is possible to instruct the web service to return only basic information about the resource, this is known in SDMX as a stub.
* **allstubs**: All artefacts will be returned as stubs.
* **referencestubs**: The referenced artefacts will be returned as stubs.
* **referencepartial**: The referenced item schemes should only include items used by the artefact to be returned. For example, a concept scheme would only contain the concepts used in a DSD, and its isPartial flag would be set to true. As another example, if a dataflow is constrained, then the codelists returned should only contain the subset of codes allowed by that constraint.
* **allcompletestubs**: All artefacts should be returned as complete stubs, containing identification information, the artefacts' name, description, annotations and isFinal information.
* **referencecompletestubs**: The referenced artefacts should be returned as complete stubs, containing identification information, the artefacts' name, description, annotations and isFinal information.
* **full**: All available information for all artefacts will be returned. This is the default.
required: false
type: string
enum:
- full
- allstubs
- referencestubs
- referencepartial
- allcompletestubs
- referencecompletestubs
responses:
'200':
description: Success
schema:
type: string
definitions: {}