Skip to main content

Without load shifting: usage = 96 kWh → cost = €49. With load shifting: usage = 98 kWh → cost = €34

​
Design

​
To optimise the operation of an HVAC system by energy cost:

Once the customer completes the Connect flow, or if you imported their tariff:
  1. Use Flatpeak API to find time periods when the energy price is above the daily average.
  2. Pre-cool before those high-cost periods.
  3. Reduce consumption during high-cost periods until either:
  • the maximum temperature tolerance is reached, or
  • the energy price falls back down.

​
To display energy cost:

  1. Submit consumed energy to the submit-interval-meter-records endpoint with tariff_type = IMPORT and direction = IMPORT.
  2. Use calculate-energy-cost-by-time-interval to fetch costs for the IMPORT direction and present them to the customer.

​
Implementation

  • Using Schedules API
  • Using Raw Tariff Rates API
To detect high-cost periods, use the schedules-by-price-limit endpoint.
  • Request a 12 or 24 hour window and set segment=HIGH with relative=0.25 to capture the top 25% periods of high electriciy price.
  • Run this periodically to generate or update the next day’s operating schedule.
curl --request GET \
  --url 'https://api.flatpeak.com/slots/threshold/loc_65e42ce4d3b813479b252160 \
  ?start_time=2023-06-15T00:00:00Z \
  &end_time=2023-06-16T00:00:00Z \
  &direction=IMPORT \
  &segment=HIGH \
  &relative=0.75' \
  --header 'Authorization: Bearer <token>'
Use the data from the previous step to schedule your system to pre-cool before a high-cost period begins.In this example, the high-cost period starts at 08:00. The system is programmed to start lowering the temperature at 07:45, reaching the minimum allowed temperature of -21°C before prices rise.
{
    "start_time": "2023-06-15T08:00:00Z",
    "end_time": "2023-06-16T09:20:00Z",
    "tariff": {
      "rate": 14.998,
      "confidence": 1
    }
}
Submit electricity meter readings from your system to Flatpeak API:
  • Interval meter records
  • Cumulative meter records
If your system logs meter records as intervals, call the submit-interval-meter-records endpoint.
curl --request PUT \
  --url https://api.flatpeak.com/meters/interval \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '[
  {
    "location_id": "loc_641b90b758fb8e6293716e40",
    "device_id": "dev_65e6d8334c8d715963d99db3",
    "session_reference_id": "SESSION1234567890",
    "direction": "IMPORT",
    "tariff_rate": "IMPORT",
    "units": "W",
    "value": 8214,
    "confidence": 1,
    "start_time": "2023-06-16T01:00:00Z",
    "end_time": "2023-06-16T01:30:00Z"
  }
]'
If your system can differentiate between grid-supplied and locally generated energy (e.g. solar), set “tariff_rate”: “LOCAL” when submitting records for solar generation. This tells Flatpeak to treat the energy as zero-cost during cost calculations.
To display the energy cost used by your system, call the calculate-energy-cost-by-time-interval endpoint.You can request:
  • Raw (unaggregated) costs for custom processing, or
  • Pre-aggregated totals by DAY or MONTH.
curl --request POST \
  --url 'https://api.flatpeak.com/costs/interval/dev_65e6d8334c8d715963d99db3 \
  ?aggregation=MONTH \
  &direction=IMPORT \
  &include_tariff=true' \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "start_time": "2023-11-07T05:31:56Z",
  "end_time": "2023-12-07T05:31:56Z"
}'
The tariff.value in the response is the total energy cost — ready to display directly to the customer.
⌘I