Data API user guide

User assistance for Data API, machine to machine access to detailed ABS statistics

Cite
Released
22/03/2022

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. Performance and availability may be impacted during periods of high use. The ABS monitors the service and will work to resolve any issues as soon as possible.

The service may be subject to change.

If you have feedback or questions, please contact the ABS APIs team. 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 (Beta) allows you request detailed ABS statistics including economic, social and Census data.

Customise your query to return only the data and metadata you are interested in, in the format you want.

Try it out

 

Recent Updates

The ABS Data API Beta received a major update on the 29th of November 2024 that may impact how users are able to access and request data.

The URL path for making Data API calls has changed from https://api.data.abs.gov.au/data/[query] to https://data.api.abs.gov.au/rest/data/[query]

New features include:

  • Users can request data for a specific number of time periods using the lastNObservations and firstNObservations modifiers in their API url calls.
  • Users can request that queried data be returned from the API as a CSV file.
  • Labels and codes can be returned with a comma separator instead of the default combined.
  • Users can specify a request for only data that has been updated since a certain point in time using the ‘UpdatedAfter’ modifer in their API url calls.
  • Referential metadata can be requested for specifically the current level.

Some of these features are explained in greater detail in the Worked Examples section of the guide.

Other notable improvements include:

  • SDMX-JSON queries no longer return dots in place of commas within textual values.
  • Dataflow-level attributes are no longer returned twice.
  • The labels=both parameter is now supported when downloading data as a CSV.
  • Using the detail=allcompletestubs parameter now returns all related artefact’s annotations.
  • The endPeriod filter no longer excludes data from the set filter year, eg. endPeriod=2017 will include data for 2017.
  • The SDMX-JSON extraction of Hierarchical Codelists now correctly includes the ID of the contained hierarchies. This was already working in SDMX-XML.
  • Enhanced performance for retrieving the first observation in a large dataflow (lastNObservations=1).
  • Structure version numbers no longer require redundant zeroes to be valid
    • application/vnd.sdmx.data+json;version=2.0.0
    • application/vnd.sdmx.data+json;version=2.0
    • application/vnd.sdmx.data+json;version=2

Base URL

This service only responds to a single GET method:

https://data.api.abs.gov.au/rest/

 

Response Format

Data is available in XML, JSON and CSV. If no format is selected the API will return XML.

Metadata is primarily available in XML. Some metadata is also available in JSON.

ABS Data API (Beta) is fully compliant with SDMX 2.1 - the Statistical Data and Metadata Exchange information model. The SDMX-REST Guide is available on GitHub.

You can specify the response in the API URL using the "format" query parameter. E.g: https://data.api..abs.gov.au/rest/data/jv/all?startPeriod=2020&format=jsondata

  • XML is returned by default
  • Structure specific XML (good for time series): "format=structurespecificdata"
  • JSON: "format=jsondata"
  • CSV: "format=csv"

You can also use the "accept" header to specify the response format as a header when you make an API call. E.g: "accept: application/xml"

  • XML: application/xml
  • Structure specific XML: application/vnd.sdmx.structurespecificdata+xml
  • JSON: application/vnd.sdmx.data+json
  • CSV: text/csv
  • CSV: application/vnd.sdmx.data+csv
  • CSV with labels for codelists: application/vnd.sdmx.data+csv;labels=both
  • CSV file with labels for codelists: application/vnd.sdmx.data+csv;file=true;labels=both

 

OpenAPI Specification

The OpenAPI / swagger definition for this service is currently at https://api.gov.au/assets/APIs/abs/DataAPI.openapi.html

GetData

  • Get data: {string: dataflowIdentifier} {string: datakey} {string: startPeriod} {string: endPeriod} {string: detail} {string: dimensionAtObservation}

GetMetadata

  • Get all structures of specified type: {string: structureType} {string: agencyId} {string: detail}
  • Get latest version of specified structure: {string: structureType} {string: agencyId} {string: structureId} {string: references} {string: detail}
  • Get specified version of specified structure: {string: structureType} {string: agencyId} {string: structureId} {string: structureVersion} {string: references} {string: detail}

 

Authentication

As of the 29th of November 2024, Data API keys have been removed and we have transitioned to a register of interest system.

The Data API is freely accessible without the need for an API key.

If you wish to be added to the register of interest, so as to receive updates regarding Data API system updates, then please contact us and provide your name or organisation name.