Emissions Intensity API Guide

Summary

This document describes how to access data available in the Emissions data product available through the AgData Shop. For details about the methodology used to generate the data please refer to Aryai, V., Goldsworthy, M. "Controlling electricity storage to balance electricity costs and greenhouse gas emissions in buildings", Energy Inform 5, 11 (2022). https://doi.org/10.1186/s42162-022-00216-5.

Prerequisites

• Authorization and license agreement. You can purchase a subscription through our AgData Shop. 

• Some programming experience to consume REST API data services. An example is provided using the python programming language, but python is not required at all.

Data Structure and Variables

The Emissions data is organized as a collection of time series estimates of the carbon emissions intensity of grid-consumed power for the five regions of the National Electricity Market (NEM) updated at five-minute intervals with the most up-to-date information available. Estimates are calculated using an energy balance model combined with publicly available generator SCADA data, interstate power flows/losses and state-level regional demand data sourced from the market operator. Generator carbon emissions intensity factors include Scope 1 and Scope 3 emissions.

Multilple Stream Requests

The following structure shows a single data point for the nsw  and qld  streams for illustration purposes, but it is worth noting that all data is JSON encoded with the following structure:

• The actual data for consumption appears in the "results" collection.

• The "streamCount" and "count" metadata fields refer to the number of columns and rows (resp.) in the response data.

• All timestamp data is provided as RFC339, UTC formatted string data with the value of each timestamp defining the key for the data object.

• The value of the data object is another collection of key-value pairs, with the key denoting the stream id under consideration and the value consisting of another key-value pair.

• The innermost key-value pair has the special key "v" which denotes the actual (floating point) value of the data point.

• Valid stream_id  values for this dataset are:

  • csiro.energy.dch.agshop.regional_global_emissions.nsw 

  • csiro.energy.dch.agshop.regional_global_emissions.qld

  • csiro.energy.dch.agshop.regional_global_emissions.sa

  • csiro.energy.dch.agshop.regional_global_emissions.vic

  • csiro.energy.dch.agshop.regional_global_emissions.tas

• Units of emissions data in this data is gCO₂/kWh.

Single Stream Requests

The following structure shows a single data point for the nsw  stream for illustration purposes, but it is worth noting that all data is JSON encoded with the following structure:

• The actual data for consumption appears in the "results" collection.

• The "streamCount" and "count" metadata fields refer to the number of columns and rows (resp.) in the response data.

• All timestamp data is provided as RFC339, UTC formatted string data with the value of each timestamp corresponding to the "t" key.

• The value of the data object is given by the nested "v" field, and the stream_id value no longer appears in the "results" field.

• Valid stream_id  values for this dataset are:

  • csiro.energy.dch.agshop.regional_global_emissions.nsw 

  • csiro.energy.dch.agshop.regional_global_emissions.qld

  • csiro.energy.dch.agshop.regional_global_emissions.sa

  • csiro.energy.dch.agshop.regional_global_emissions.vic

  • csiro.energy.dch.agshop.regional_global_emissions.tas

• Units of emissions data in this data is gCO₂/kWh.

Sample Use (python)

Upon purchasing access to the data, you will be provided with access credentials.

Accessing Your Credentials

After purchasing access to data through the Data Shop, you will receive your access credentials, which are crucial for accessing the data. To find these credentials, follow the steps below:

1. Sign into your Data Shop account.

2. Navigate to the My Account tab.

3. Click on the Orders tab.

4. Under Recurring payments, select View order (make sure to note your Order number - XXXX).

5. On the Order information page, check for the Note(s) tab. Here, you will find your client_id and client_secret.

Your newly acquired AgData Shop credentials will permit you access to the data itself which is the Senaps cloud platform. The following sample code shows how one can use the credentials to make a GET request to the data, as well as parse the data and write the (parsed) response to disk in parquet format for use downstream.

Example Code

The following example can be used to make a request using the above credentials with some time boundaries, with the response data written straight to disk.  

Whilst this example has been constructed in python, any language can be employed by following a similar pattern.  It is also worth noting that the polars library used is actually a rust library, so the above workflow can be reconstructed in a straightforward manner in rust or any of the wrappers that are provided, including python, NodeJS, and R.

Prerequisites

• Ensure you have Python 3.10 or higher installed on your system to avoid errors related to language features such as the match functionality.

• Install necessary Python packages if they are not already installed:

Steps to Use the Code

1. Set Up Authentication:
   Replace <YOUR CLIENT ID> and <YOUR CLIENT SECRET>  in the following code with your credentials (see Accessing Your Credentials).
   
   

2. Configure Parameters:
   Adjust the regions, start, end, and write_path parameters in the code to match your data retrieval needs:
   - regions: List of region codes for which you want emissions data (e.g., ["nsw", "qld" , "sa","tas","vic"]).
   - start: Start date and time for the data retrieval in ISO 8601 format (e.g., "2023-05-01T00:00:00.000Z").
   - end: Enddate and time for the data retrieval in ISO 8601 format (e.g., "2023-05-10T00:00:00.000Z").
   - write_path: Path to save the output data in Parquet format (e.g., Path("C:\demo_response.parquet")).
   
   

3. Run the Code.