v1

latestOpenAPI 3.1.02026-07-1342111193.6 KB

Spark

Optimize Storage Dispatch Schedules (Beta)

Optimize energy flows into and out of a storage system to minimize cost, given a corresponding tariff, consumption profile, solar generation profile, and storage specifications. Supports a variety of installation configurations and dispatch strategies.

post/spark/storage_optimization/schedules

Headers

Arcadia-Versionstring required

The Arcadia-Version for the request

Request body

main_tariff_idstring required

The Genability 'masterTariffId' unique identifier for this tariff, prefixed with gen_mtid_. See Genability documentation for details.

from_date_timestring date-time required

Start time of the consumption and solar curves. Must be the start of an hour (i.e. :00:00).

consumption_curve_kwh_acnumber[] required

Timeseries representing how much AC consumption needs to be met at each timestep (kWh AC).

solar_generation_curve_kwh_dcnumber[]

Timeseries representing how much DC solar production occurs at each timestep (kWh DC). If absent, assumed to be 0. If present, must have the same length as consumption_curve_kwh_ac. Note that DC to AC conversion is specified with solar_dc_to_ac_efficiency.

solar_dc_to_ac_efficiencynumber

How efficiently the solar inverter converts outgoing DC power to AC (0.0 - 1.0).

allow_grid_to_batteryboolean

Allow the battery to be charged from the grid (true/false, defaults to true). DC-coupled batteries only chargable via solar should set this to false.

allow_solar_to_batteryboolean

Allow the battery to be charged from solar (true/false, defaults to true). AC-coupled batteries may want to set this to false if indirect AC charging from converted solar is not possible.

allow_solar_to_gridboolean

Allow excess solar to be sold back to the grid (true/false, defaults to true). Solar tied exclusively to the battery and/or the site should set this to false, which may cause curtailment in the result.

allow_battery_to_gridboolean

Allow battery to export energy to the grid (true/false, defaults to true). Batteries configured exclusively for self-consumption should set this to false.

battery_dc_coupledboolean

Whether the battery is DC coupled (true/false). If false, solar power must be converted from DC to AC and then back to DC before it can be stored.

battery_ac_to_dc_efficiencynumber

How efficiently the battery inverter converts incoming AC power to DC (0.0 - 1.0).

battery_dc_to_ac_efficiencynumber

How efficiently the battery inverter converts outgoing DC power to AC (0.0 - 1.0)

battery_input_efficiencynumber

Coulombic efficiency of the battery, i.e. ratio of input kWh for a full charge to output kWh for a full discharge (0.0 - 1.0).

battery_nameplate_powernumber

The maximum amount of power that can instantaneously flow into or out of the battery (kW DC).

battery_nameplate_capacitynumber

Maximum charge that the battery can hold (kWh DC).

battery_min_socnumber

Minimum state of charge of the battery (0.0 - 1.0).

battery_max_socnumber

Maximum state of charge of the battery (0.0 - 1.0).

battery_initial_socnumber

Initial state of charge of the battery (0.0 - 1.0).

battery_degradation_cost_per_discharge_kwhnumber

Optionally impose a cost on total discharge from the battery as a simplified degradation model ($/kWh).

export_limit_kwh_acnumber

Maximum energy that can be exported to the grid at any given timestep (kWh AC). Leave unspecified for unlimited exports, or set to 0 to forbid them.

Example request

{
  "main_tariff_id": "gen_mtid_3424821",
  "tariff_property_inputs": [
    {
      "keyName": "accPlusAdderCustomerType"
    }
  ],
  "from_date_time": "2021-03-18T00:00:00-07:00",
  "consumption_curve_kwh_ac": [
    0.8,
    1,
    1.2,
    1
  ],
  "solar_generation_curve_kwh_dc": [
    0.5,
    2.4,
    1.3,
    0.4
  ],
  "solar_dc_to_ac_efficiency": 0.96,
  "allow_grid_to_battery": true,
  "allow_solar_to_battery": true,
  "allow_solar_to_grid": true,
  "allow_battery_to_grid": true,
  "battery_dc_coupled": true,
  "battery_ac_to_dc_efficiency": 0.96,
  "battery_dc_to_ac_efficiency": 0.96,
  "battery_input_efficiency": 0.975,
  "battery_nameplate_power": 3,
  "battery_nameplate_capacity": 6,
  "battery_min_soc": 0.1,
  "battery_max_soc": 1,
  "battery_initial_soc": 0.5
}

Response

Success

from_date_timestring date-time required

Start time corresponding to the beginning of the hour when the consumption and solar curves start. Echoed back from request parameters.

grid_to_site_kwh_acnumber[] required

Amount of electricity flowing to site load from the grid (kWh AC).

grid_to_battery_kwh_acnumber[] required

Amount of electricity flowing to the battery from the grid, before conversion with battery_ac_to_dc_efficiency (kWh AC).

solar_to_battery_kwh_dcnumber[] required

Amount of electricity flowing to the battery from PV solar generation, either without any conversion if battery_dc_coupled or after double-conversion with solar_dc_to_ac_efficiency * battery_ac_to_dc_efficiency if not (kWh DC).

solar_to_site_kwh_acnumber[] required

Amount of electricity flowing to site load from PV solar generation, after conversion with solar_dc_to_ac_efficiency (kWh AC).

solar_to_grid_kwh_acnumber[] required

Amount of electricity flowing to the grid from PV solar generation, after conversion with solar_dc_to_ac_efficiency (kWh AC).

solar_curtailed_kwh_dcnumber[] required

Amount of electricity from solar that goes unused (kWh DC).

battery_to_site_kwh_acnumber[] required

Amount of electricity flowing to site load from the battery, after conversion with battery_dc_to_ac_efficiency (kWh AC).

battery_to_grid_kwh_acnumber[] required

Amount of electricity flowing to the grid from battery, after conversion with battery_dc_to_ac_efficiency (kWh AC).

net_load_kwh_acnumber[]

Amount of electricity flowing from the grid if positive or to the grid if negative (kWh AC). Equals grid_to_site_kwh_ac + grid_to_battery_kwh_ac - battery_to_grid_kwh_ac - solar_to_grid_kwh_ac.

battery_socnumber[] required

Hourly battery state of charge (0.0 - 1.0, though in practice, all values will be between battery_min_soc and battery_max_soc). Multiply by battery_nameplate_capacity to get a timeseries of kWh DC stored.

Example response

{
  "from_date_time": "2021-03-18T00:00:00-07:00",
  "grid_to_site_kwh_ac": [
    1.3,
    1.1,
    0,
    0
  ],
  "grid_to_battery_kwh_ac": [
    1.56,
    0,
    0,
    0
  ],
  "solar_to_battery_kwh_dc": [
    0,
    1.5,
    0,
    0
  ],
  "solar_to_site_kwh_ac": [
    0,
    0.1,
    1.3,
    1.5
  ],
  "solar_to_grid_kwh_ac": [
    0,
    0,
    0.4,
    1.4
  ],
  "solar_curtailed_kwh_dc": [
    0,
    0,
    0,
    0
  ],
  "battery_to_site_kwh_ac": [
    0,
    0,
    0.1,
    0.2
  ],
  "battery_to_grid_kwh_ac": [
    0,
    0,
    0.1,
    0.2
  ],
  "net_load_kwh_ac": [
    1.86,
    1.1,
    -0.5,
    -1.6
  ],
  "battery_soc": [
    0.75,
    1,
    0.8,
    0.4
  ]
}