⚡︎ Usage Snapshot Netting

Aggregating a collection of usage snapshots to determine a net amount at every moment in time

Background

Calculating the net usage is the act of taking a usage snapshot and a list of 1 or many synthetic snapshots and aggregating their net kwh together, per period i.e. 30 minute interval. This allows you to create custom scenarios that can all be aggregated together.

Furthermore, beyond just aggregating the net kwh, we also consider an optional battery storage in our calculations. A battery can vary in size and the storage can be configured to leave X% of charge remaining (in case of a power cut) and similarly it can be configured to not charge to 100% if there's an option to sell back to the grid.

Prerequisites

Before you can follow this guide, you will need:

  • To be able to make a request in your programming language of choice, our API reference has example requests using multiple common languages and libraries, just look for the "Language" dropdown at the top of the page.
  • Your subscription key (32 alphanumerical combination key).

Usage Snapshot Netting

To perform a netting you issue the following POST request:

POST - Creating a Net Snapshot

The post request will take the list of snapshots, walk through time in order and net the usage together all whilst considering the battery storage parameters. What this results in is a net snapshot that follows a standard usage snapshot protocol, stored as a blob here.

Solar Calculation Inputs

{
  "customer_id": "demo_customer",
  "net_configuration": {
    "usage_snapshot_id_list": [
    	{"snapshot_id": "123_abc"},
			{"snapshot_id": "456_def"},
			{"snapshot_id": "789_ghi"}
    ],
    "battery_configuration":{
      "battery_size_kw":15.0,
      "charging_configuration":{
        "cutoff_percentage":1.0,
        "time_period":{
  	      "start":"21:00",
	        "end":"00:00"
        }
      },
      "discharging_configuration":{
      	"cutoff_percentage":0.2,
        "time_period":{}      
    	}
    }
  }
}

Let's break down each of these:

  • customer_id the customer_id against which you'd like the net snapshot associated
  • net_configuration the overall configuration of the netting scenario
  • usage_snapshot_id_list a list of valid snapshot ids to use for the netting
  • battery_configuration the battery specific configuration to be applied during the netting process
  • battery_size_kw storage capacity of the battery in kw
  • charging_configuration configuration for when you charge the battery
  • discharging_configuration configuration for when to consume/discharge the battery
  • cutoff_percentage a float between 0 and 1 that represents the percentage to cutoff the respective charge/discharge
  • time_period an optional start and end time window to apply the charge/discharge of the battery

POST - Handling the Response

The Ahiko API uses JSON to encode responses. Most languages have libraries to encode and decode JSON.

The API response will look like:

{
  "success": true,
  "id": "net_usage_snapshot_d5c5b3a8-2174-48b1-ba33-56dfca574bbf"
}

Let's break down this response:

  • success whether or not the snapshot was successfully netted and stored
  • id the netted snapshot unique identifier