Switched system

Design

To create a schedule optimised by energy cost:

Once the customer completes the Connect flow, or if you imported their tariff:

Create a default schedule that provides a fixed number of daily “on” hours when the tariff is low (i.e. 5 hours between 8pm and 6am on the following day).
Allow the customer to change that schedule by setting a choice of:
- Number of daily “on” hours (add weekday/weekend and so on), or/and
- When the “on” period must end (i.e. complete charging by 6 am) or
- Absolute tariff threshold (i.e. “on” when the tariff is below $0.15/kWh), or
- Relative tariff threshold (i.e. “on” when the tariff is below 40% daily average).

To keep the schedule aligned with tariff changes:

When an energy user (i.e. an EV) connects to your device or is scheduled daily:
- Pass schedule settings to the API,
- Receive actualised schedule (slots),
- Apply this actualised schedule to your device.

To log the amount of transferred energy:

During or after the energy transfer, log it to meter records API under the IMPORT tariff.
Log any energy from local generation (i.e., solar) under the LOCAL tariff.

To display the cost of transferred energy:

When you want to display the energy cost, call the API to get it in real-time, aggregated by (charging) session or day/month/year.

Consider offering tariff threshold-based (aka price cap) scheduling as a premium feature.

Implementation

Creating and updating schedules

Once the customer’s tariff is added via Connect or imported via the API, program your device to enable energy delivery when the tariff is lowest:

To create an “on/off” schedule that provides a fixed number of daily “on” hours when the tariff is low, call the slots-time API endpoint and use the start_time and end_time values for the total period of the Response object to create a daily schedule in your device within this period.

curl --request GET \
  --url 'https://api.flatpeak.com/slots/time/loc_65e42ce4d3b813479b252160\
  ?start_time=2023-06-15T09%3A00%3A00Z \
  &end_time=2023-06-16T09%3A00%3A00Z \
  &direction=IMPORT \
  &segment=LOW \
  &duration=300 \
  --header 'Authorization: Bearer <token>'

We recommend re-running the process every time an energy user (i.e. an EV) connects.

curl --request GET \
  --url 'https://api.flatpeak.com/slots/time/loc_65e42ce4d3b813479b252160\
  ?start_time=2023-06-15T09%3A00%3A00Z \
  &end_time=2023-06-16T09%3A00%3A00Z \
  &direction=IMPORT \
  &segment=LOW \
  &duration=300 \
  --header 'Authorization: Bearer <token>'

We recommend re-running the process every time an energy user (i.e. an EV) connects.

To create a schedule to set your device to “on” when the tariff is below a specific value (for example ≤ $0.15/kWh), call slots-threshold API endpoint and use start_time and end_time values of the Response object to create a schedule in your device.

curl --request GET \
  --url 'https://api.flatpeak.com/slots/threshold/loc_65e42ce4d3b813479b252160 \
  ?start_time=2023-06-15T09%3A00%3A00Z \
  &end_time=2023-06-16T09%3A00%3A00Z \
  &direction=IMPORT \
  &segment=LOW \
  &absolute=10.15' \
  --header 'Authorization: Bearer <token>'

We recommend setting the schedule 24 hours in advance and re-running the process every time an energy user (e.g., an EV) connects.

Metering energy transfers

When you want to calculate the cost of energy that is being transferred (or has been transferred) via your device, submit its meter reading to one of the API endpoints:

If your system logs meter records as intervals, call submit-interval-meter-records API. You can use this endpoint to import historic records too.

If your device is an EV charger, we recommend that you log records “tagged” by the charging session ID if you have it. Use the session_reference_id parameter in the request. This will make it easy to report the cost per charging session later.

Make sure that you use the units parameter correctly: W represents the speed of transfer over the accounting period; WH represents the amount of energy transferred over that period.

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"
  }
]'

The API response will indicate that the submitted records have been processed successfully. You can submit up to 10,000 records at a time for a device or location.

If your system logs meter records as intervals, call submit-interval-meter-records API. You can use this endpoint to import historic records too.

Make sure that you use the units parameter correctly: W represents the speed of transfer over the accounting period; WH represents the amount of energy transferred over that period.

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"
  }
]'

The API response will indicate that the submitted records have been processed successfully. You can submit up to 10,000 records at a time for a device or location.

If your system logs meter records as cumulative values, call the submit-cumulative-meter-records API. This endpoint also supports importing historical records.

curl --request PUT \
  --url https://api.flatpeak.com/cumulative/epoch \
  --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": "WH",
  "data": [
    {
      "time": 1721991392,
      "value": 1553
    }
  ]
}'

The API response will indicate that the submitted records have been processed successfully. You can submit up to 10,000 records at a time.

If your system can distinguish between energy sourced from the grid versus from local generation, such as solar, set "tariff_rate": "LOCAL" when submitting the records. This will tell FlatPeak to account for this energy as “free” when calculating its cost.

Displaying energy cost

When you want to display the cost of energy that has been transferred via your device for a charging session, and you have previously “tagged” your meter records with session_reference_id, use calculate-energy-cost-by-session-id API:

curl --request POST \
  --url 'https://api.flatpeak.com/costs/session/SESSION1234567890 \
  ?direction=IMPORT \
  &include_tariff=true' \
  --header 'Authorization: Bearer <token>'

curl --request POST \
  --url 'https://api.flatpeak.com/costs/session/SESSION1234567890 \
  ?direction=IMPORT \
  &include_tariff=true' \
  --header 'Authorization: Bearer <token>'

When you want to display the cost of energy that has been transferred via your device aggregated by day, month or year, use calculate-energy-cost-by-time-interval API:

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"
}'

Case studies

Data import & export

Service objects

Data sources

Branded plans

Design

To create a schedule optimised by energy cost:

To keep the schedule aligned with tariff changes:

To log the amount of transferred energy:

To display the cost of transferred energy:

Implementation

Case studies

Data import & export

Service objects

Data sources

Branded plans

​Design

​To create a schedule optimised by energy cost:

​To keep the schedule aligned with tariff changes:

​To log the amount of transferred energy:

​To display the cost of transferred energy:

​Implementation

Design

To create a schedule optimised by energy cost:

To keep the schedule aligned with tariff changes:

To log the amount of transferred energy:

To display the cost of transferred energy:

Implementation