For Developers

Universal Resource Identifier (URI)

Access the API through the following URI: https://www.abs.gov.au/api/demography/populationprojection

Data in the ABS Population Clock Web Service / API

To create your own Population Clock refer to section Using the ABS Population Clock Web Service / API in your own applications below.

The ABS Population Clock Web Service / API provides data in a JavaScript Object Notation (JSON) format.

Example:

{"attribution":"Australian Bureau of Statistics",
"popNow":"23518535",
"timeStamp":"10 Jun 2014 09:50:39 EST",
"projectionStartDate":"30 September 2013",
"birthRate":"1 minute and 42 seconds ",
"deathRate":"3 minutes and 36 seconds ",
"overseasMigrationRate":"2 minutes and 9 seconds ",
"growthRate":"1 minute and 17 seconds ",
"rateSecond":"77.14304584893798663891",
"source":"Australian Demographic Statistics, September Quarter 2013 (cat. no. 3101.0)",
"sourceURL":"https://www.abs.gov.au/ausstats/abs@.nsf/mf/3101.0",
"copyRight":"Copyright Commonwealth of Australia"}

Below is a brief description of the data contained in the API:

Property	Type	Definition	Example
attribution	String json	Australian Bureau of Statistics (ABS) material used 'as supplied' with no modification or transformation to the ABS material including calculating percentages, graphing / charting data or deriving new statistics from published ABS statistics may be used provided the following attribution: 'Source: Australian Bureau of Statistics' or 'Source: ABS'. If you have modified or transformed ABS material, or derived new material from those of the ABS in any way, the following attribution must be used: 'Based on Australian Bureau of Statistics data' or 'Based on ABS data'.	attribution : 'Australian Bureau of Statistics'
popNow	String json	This instance population (determined by timeStamp) value - the displayed (interpolated) popclock value	popNow : '23518535'
timeStamp	String json	The exact date-time at which PopNow is calculated (ie the date-time used in the popclock interpolation).	timeStamp : '10 Jun 2014 09:50:39 EST'
projectionStartDate	String json	The date of the base Estimated Resident Population (ie the START population)	projectionStartDate : '30 September 2013'
birthRate	String json	Birth rate expressed as minutes and seconds per birth	birthRate : '1 minutes and 42 second'
deathRate	String json	Death rate expressed as minutes and seconds per death	deathRate : '3 minutes and 36 second'
overseasMigrationRate	String json	Net Overseas Migration rate expressed as minutes and seconds per net overseas migrant	overseasMigrationRate : '2 minutes and 9 second'
growthRate	String json	Population growth rate expressed as minutes and seconds per person added to the population	growthRate : '1 minutes and 17 second'
rateSecond	String json	Growth rate expressed as seconds per person added to the population	rateSecond : '77.14304584893798663891'
source	String json	The entire text string used to source Australian Demographic Statistics (ABS Cat. No. 3101.0) in accordance with publication standards	source: 'Australian Demographic Statistics, September Quarter 2013 (cat. no. 3101.0)'
sourceURL	String json	The source URL for Australian Demographic Statistics (ABS Cat. No. 3101.0) in accordance with publication standards	sourceURL:'https://www.abs.gov.au/ausstats/abs@.nsf/mf/3101.0'
copyRight	String json	All data and other material produced by the Australian Bureau of Statistics (ABS) constitutes Commonwealth copyright administered by the ABS. Unless otherwise noted, all ABS data presented in this application, except the ABS logo, the Commonwealth Coat of Arms, and any material protected by a trademark, is licenced under a Creative Commons Attribution 2.5 Australia licence.	copyRight : 'Copyright Commonwealth of Australia.'

Using the ABS Population Clock Web Service / API in your own applications

For programmers looking to consume the Population Clock Web Service / API we recommend their application design follow a similar approach to the ‘ABS Stats’ iOS app. The ‘ABS Stats’ iOS app is designed with a cache to store the population data it retrieves from the Population Clock Web Service / API. In this way, the app is able to perform its own calculations and present the Australian population projection in real time. This eliminates the need for frequent continuous API polling by the app, which in turns removes other technological factors such as network latency and network connectivity. The use of a cache on the host application allows for instant access to the population data and provides added fault tolerance when the application cannot reach the Population Clock Web Service / API. Additionally, the host application would only need to parse the population data once and store it in the cache in a format that is ready for use by the host application.

We recommend that consumers of the web service call the Population Clock Web Service / API once a day. The data provided by the web service is updated only when there is a new quarterly release of Australian Demographic Statistics (ABS Cat. No 3101.0). The API’s data provide the consumer with the ability to calculate their own figures i.e. current projected Australian population – see Frequently Asked Questions – How is the data in the Population Clock Web Service / API calculated?

Below is an example of using jQuery to retrieve population data from the Population Clock Web Service / API and parsing the JSON output to increment your own Population Clock:

The properties used are: popNow, rateSecond and timeStamp or Date.getTime

<html>
<head>
<title>jQuery calling RESTful Population Clock Web Service API</title>
<meta xmlns="http://www.w3.org/1999/xhtml" content="text/html; charset=utf-8" />
<script src="http://code.jquery.com/jquery-2.1.1.js"></script>
</head>

<body>
<script type='text/javascript'>
jQuery.support.cors = true;
var Population;
var receivedTime;
function calculatePopulation() {
if(Population){
var nowTime = new Date();

var timeDif = Math.abs((nowTime.getTime() - receivedTime.getTime()) / 1000);

var rate = Number(Population.rateSecond);
var addToPop = Math.round(Number(timeDif) / Number(rate));
var currPop = Number(Population.popNow) + Number(addToPop);

$('#displayPopulation').html(""+currPop);
}
}
function getData(){
var client = new $.ajax({url:'https://www.abs.gov.au/api/demography/populationprojection',
contentType: "application/json; charset=utf-8",
dataType: "json"});
client.success(function(data) {
Population = data;
receivedTime = new Date();
});
client.error(function(error) {
alert('Error: '+ error.statusText);
});
}

function checkUpdate() {
var nowTime = new Date();
if(receivedTime && (DiffInDays(receivedTime,nowTime)>2)){
getData();
}
calculatePopulation();
}

function DiffInMilliseconds(First, Second) {
var start = new Date(First);
var end = new Date();

if (Second != null) {
end = new Date(Second);
}

if (First != null) {
start = new Date(First);
}

var millisBetween = end.getTime() - start.getTime();
return millisBetween;
}

function DiffInDays(First, Second) {
var millisBetween = DiffInMilliseconds(First, Second);
var millisecondsPerDay =s 1000 * 60 * 60 * 24;
var days = millisBetween / millisecondsPerDay;
return Math.floor(days);
}


$(document).ready(function () {
getData();
setInterval(function() {
checkUpdate();
}, 2000);

});
</script>
<h1>How to use Population Clock Web Service API jQuery</h1>
<p>This is a basic example</p>
<p>Australian Population is: </p><span id="displayPopulation"></span>

</body>
</html>

Technical overview

The Population Clock Web Service / API is built using Java and utilises Representational State Transfer (REST) architecture to allow for the simplest set of communication requirements as opposed to Simple Object Access Protocol (SOAP).
To retrieve the population figure from the Population Clock Web Service / API, the consumer constructs a simple Hypertext Transfer Protocol (HTTP) GET request parsing the output as a JSON object. Below is some C# .NET code sample demonstrating using standard class libraries to call the Population Clock Web Service / API and parsing the output as a JSON object:

string requestUrl = "https://www.abs.gov.au/api/demography/populationprojection";

HttpWebRequest request = WebRequest.Create(requestUrl) as HttpWebRequest;
request.Method = "GET";
request.ContentType = "application/json";
using (HttpWebResponse response = request.GetResponse() as HttpWebResponse)
{
if (response.StatusCode != HttpStatusCode.OK)
throw new Exception(String.Format( "Server error (HTTP {0}: {1}).",response.StatusCode,response.StatusDescription));
DataContractJsonSerializer jsonSerializer = new DataContractJsonSerializer(typeof(Response));

object objResponse = jsonSerializer.ReadObject(response.GetResponseStream());
Response respJSON = objResponse as Response;
Console.WriteLine("The Australian projected population is: " + respJSON.PopNow);
}

The Population Clock Web Service / API retrieves its data from ABS.Stat SDMX Web Service (http://stat.abs.gov.au/sdmxws/sdmx.asmx) which implements SOAP. The Population Clock Web Service / API has its own cache to store the population data retrieved from ABS.Stat. This approach minimises unnecessary calls to ABS.Stat, as the population data updates on a quarterly basis.

Simple technologies have been applied in the design of the Population Clock Web Service / API. ABS intends that this approach will give programmers more time to spend on building their own applications (smart phone applications, web site applications, desktop applications), and to interpret, analyse and ultimately present the population data in an innovative way. Some recommendations follow for incorporating API data into your apps.

Further help for developers using Population Clock Web Service / API

The ABS ßetaWorks blog provides information about ABS website innovations. It also provides a developer’s forum for sharing ideas, providing feedback and reporting any technical issues using APIs.

If you cannot find an answer through ABS BetaWorks, the ABS National Information Referral Service is also available to email, or to call during Australian Eastern Standard Time office hours. They will ensure your enquiries or feedback are relayed to our technical staff for response.

Changes to available all available ABS web services will be advertised on the ABS website. The addition of new APIs will be advertised on the website and on ßetaWorks.

As the source datasets for the API are on ABS.Stat, it may be occasionally down or over capacity. In this event, users should expect an error code of 500 with the message “ABS RESTful web service currently unavailable.”