1420.0.55.001 - Population Clock Web Service, User Guide  
Latest ISSUE Released at 11:30 AM (CANBERRA TIME) 11/07/2014  First Issue
   Page tools: Print Print Page Print all pages in this productPrint All RSS Feed RSS Bookmark and Share Search this Product

For Developers

Universal Resource Identifier (URI)

Access the API through the following URI: http://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":"http://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
    source: 'Australian Demographic Statistics, September Quarter 2013 (cat. no. 3101.0)'
    sourceURL
String json
    sourceURL:'http://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:'http://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 = "http://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.
        Image: Population Clock Web Service API process
        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.”