​
Introduction

FlatPeak Schedules API enables you to optimise your device’s energy costs without reducing its total energy usage. It does so by creating intelligent consumption or export schedules, that take into account your device’s energy needs, grid tariffs, real-time and projected local energy generation, and the availability of locally stored energy.

​
Example applications

Schedules API can help creating smart charging sessions for one or multiple EVs. Or maximise savings and export revenues from on-site PV, wind and/or energy storage systems.

Together with Meters API and Cost Calculate API, Schedules API provides a complete smart energy management and reporting solution for your devices.

Read Use cases guide to plan your implementation.

​
How to use Schedules API

1

Creating your first Schedule

To create a schedule, you will need at least the following:

Object/ParameterDescription
device_idFlatPeak ID of the device you will be creating the schedule for. You may include multiple devices in one request.
location_idFlatPeak ID of the location where you want to create the schedule. For example, the location where the device is permanently installed (such as an EV charger or BESS) or where the device is at the moment (for example, an electric vehicle).
directionDirection of energy transfer. Possible options are” IMPORT for when the device will be consuming the energy and EXPORT when the device will be exporting the energy (for example, when BESS is projected to have surplus energy that it will want to export into the grid).
start_timeTime when energy transfer may begin. Set it to the current time if you don’t know.
end_time.Time when energy transfer must be completed. If you don’t have this information, set this value to a presumed reasonable figure. For example, overnight EV charging can be 5:30am.
max_powerMaximum speed of power transfer this device supports (i.e. power rating)
shaving_threshold.relativeRelative tariff cap. Where highest tariff over the requested period is 1 and lowest is 0.01, provide value up to which you are willing to by energy.
shaving_threshold.absoluteAbsolute tariff cap in local currency. Overrides relative value if provided.
energyAmount of energy the device requires in WH or KWh. Set it to an approximate amount if you don’t know. For example, for an electric cat, this can be 60KWh.

With this information, use create-schedule endpoint to create your first Schedule:

Example Request
curl --request POST \
  --url https://api.flatpeak.com/schedules \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "location_id": "loc_641b90b758fb8e6293716e40",
    "max_power": {
      "units": "W",
      "value": "14000"
    },
    "shaving_threshold": {
      "relative": 0.83,
      "absolute": 0.123
    },
    "data": [
      {
        "device_id": "dev_65e6d8334c8d715963d99db3",
        "direction": "IMPORT",
        "start_time": "2024-08-01T00:00:00Z",
        "end_time": "2024-08-01T23:59:59Z",
        "max_power": {
          "units": "W",
          "value": 4000
        },
        "energy": {
          "units": "WH",
          "value": 2500
        }
      }
    ]
  }'
2

Understanding the response

The response will include the following key values:

Object/ParameterDescription
idUnique schedule response object identifier.
energy.valueThe scheduled amount of energy will be transferred under this schedule.
tariff.valueEstimated total monetary cost (or value in case of EXPORT) of energy in currency_code.
savings.shaving.cost.valueAmount of money saved by shaving algorythm. In local currency using large units.
savings.shaving.cost.percentagePercentage of cost saved by shaving algorythm.
savings.optimisation.valueThe amount of money this schedule will save you versus if you start using energy immediately without regard to the tariffs.
savings.optimisation.percentageThe percentage of money this schedule will save you versus if you would start using energy immediately without regard to the tariffs.
data.scheduleSeries of time slots where your device can use or export energy with suggested max_power. The max_power value can be lower than your requested value in complex cases such as load balancing.
Example Response
{
  "id": "sch_65ea3fb185c1541f247c251e",
  "object": "schedule",
  "live_mode": true,
  "location_id": "loc_641b90b758fb8e6293716e40",
  "location_timezone": "Europe/London",
  "currency_code": "GBP",
  "max_power": {
    "units": "W",
    "value": 4000
  },
  "shaving_threshold": {
    "relative": 0.83,
    "absolute": 0.123
  },
  "tariff": {
    "value": 928.372,
    "confidence": 1
  },
  "savings": {
    "value": 0.0239,
    "percentage": 1.34
  },
  "data": [
    {
      "device_id": "dev_664525107c44d88a37ca1ad7",
      "direction": "IMPORT",
      "start_time": "2024-08-01T18:00:00Z",
      "end_time": "2024-08-01T20:00:00Z",
      "max_power": {
        "units": "W",
        "value": 2000
      },
      "energy": {
        "units": "WH",
        "value": 2500
      },
      "tariff": {
        "value": 928.372,
        "confidence": 1
      },
      "savings": {
        "value": 0.0239,
        "percentage": 1.34
      },
      "schedule": [
        {
          "start_time": "2022-02-02T02:00:00Z",
          "end_time": "2022-02-02T04:30:00Z",
          "power": {
            "units": "W",
            "value": 11000
          }
        }
      ]
    }
  ]
}
Note that IMPORT is optimised for the lowest energy cost using the import tariff and local generation values; EXPORT is optimised for the highest return using the export tariff.

Was this page helpful?

Local generation