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 associatednet_configuration
the overall configuration of the netting scenariousage_snapshot_id_list
a list of valid snapshot ids to use for the nettingbattery_configuration
the battery specific configuration to be applied during the netting processbattery_size_kw
storage capacity of the battery in kwcharging_configuration
configuration for when you charge the batterydischarging_configuration
configuration for when to consume/discharge the batterycutoff_percentage
a float between 0 and 1 that represents the percentage to cutoff the respective charge/dischargetime_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 storedid
the netted snapshot unique identifier