--- title: "Optimize Storage Dispatch Schedules (Beta)" method: POST path: "/spark/storage_optimization/schedules" tags: ["Spark"] --- # Optimize Storage Dispatch Schedules (Beta) `POST /spark/storage_optimization/schedules` 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. ## Headers - `Arcadia-Version` string, required ## Request body - StorageOptimizationSchedulesRequestParams - `main_tariff_id` string, required — The Genability 'masterTariffId' unique identifier for this tariff, prefixed with `gen_mtid_`. See [Genability documentation](https://developer.genability.com/api-reference/tariff-api/tariff/) for details. - `tariff_property_inputs` object[] — Genability `propertyInputs` applicable to the specified tariff that may affect the cost structure being optimized against. See [Genability documentation](https://developer.genability.com/api-reference/calculation-api/cost-calculation) for details on how to set these inputs for specific tariffs. Use Genability-defined input format. - `keyName` string, required - `dataValue` union, required - boolean - number - string - `from_date_time` string, 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_ac` number[], required — Timeseries representing how much AC consumption needs to be met at each timestep (kWh AC). - `solar_generation_curve_kwh_dc` number[] — 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`. - `dispatch_strategy` DispatchStrategy - `optimize` boolean — If `true`, find the optimal dispatch schedule for the given tariff, solar, and consumption curves, assuming perfect forecasts. - `chargeOnSurplus` boolean — If `true`, charge whenever solar production exceeds consumption and discharge to meet consumption otherwise. - `fixedSchedule` FixedSchedule - `chargeTous` TimeOfUse[], required — TOU schedule for charging the storage system. - `season` TouSeason - `seasonFromDay` integer — Day of the month on which this season begins (1 - 31). - `seasonToDay` integer — Day of the month after which this season ends (1 - 31). - `seasonFromMonth` integer, required — Month of the year on which this season begins (1 - 12). - `seasonToMonth` integer, required — Month of the year after which this season ends (1 - 12). End month is included in the season. - `touPeriods` TouPeriod[], required — Set of TOU periods defining the schedule. - `fromDayOfWeek` integer — Day of the week on which this period begins (0 - 6, Monday - Sunday). - `toDayOfWeek` integer — Day of the week after which this period ends (0 - 6, Monday - Sunday). End day is included in the period. - `fromHour` integer, required — Hour of the day on which this period begins (0 - 23). - `toHour` integer, required — Hour of the day before which this period ends (0 - 24). End hour is not included in the period. - `dischargeTous` TimeOfUse[], required — TOU schedule for discharging the storage system. - `season` TouSeason - `seasonFromDay` integer — Day of the month on which this season begins (1 - 31). - `seasonToDay` integer — Day of the month after which this season ends (1 - 31). - `seasonFromMonth` integer, required — Month of the year on which this season begins (1 - 12). - `seasonToMonth` integer, required — Month of the year after which this season ends (1 - 12). End month is included in the season. - `touPeriods` TouPeriod[], required — Set of TOU periods defining the schedule. - `fromDayOfWeek` integer — Day of the week on which this period begins (0 - 6, Monday - Sunday). - `toDayOfWeek` integer — Day of the week after which this period ends (0 - 6, Monday - Sunday). End day is included in the period. - `fromHour` integer, required — Hour of the day on which this period begins (0 - 23). - `toHour` integer, required — Hour of the day before which this period ends (0 - 24). End hour is not included in the period. - `timezone` string — Timezone in which the schedule is defined. Defaults to tariff timezone. - `solar_dc_to_ac_efficiency` number — How efficiently the solar inverter converts outgoing DC power to AC (`0.0` - `1.0`). - `allow_grid_to_battery` boolean — 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_battery` boolean — 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_grid` boolean — 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_grid` boolean — 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_coupled` boolean — 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_efficiency` number — How efficiently the battery inverter converts incoming AC power to DC (`0.0` - `1.0`). - `battery_dc_to_ac_efficiency` number — How efficiently the battery inverter converts outgoing DC power to AC (`0.0` - `1.0`) - `battery_input_efficiency` number — 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_power` number — The maximum amount of power that can instantaneously flow into or out of the battery (kW DC). - `battery_nameplate_capacity` number — Maximum charge that the battery can hold (kWh DC). - `battery_min_soc` number — Minimum state of charge of the battery (`0.0` - `1.0`). - `battery_max_soc` number — Maximum state of charge of the battery (`0.0` - `1.0`). - `battery_initial_soc` number — Initial state of charge of the battery (`0.0` - `1.0`). - `battery_degradation_cost_per_discharge_kwh` number — Optionally impose a cost on total discharge from the battery as a simplified degradation model ($/kWh). - `export_limit_kwh_ac` number — 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. ## Response `200` Success - StorageOptimizationSchedulesResponse - `from_date_time` string, 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_ac` number[], required — Amount of electricity flowing to site load from the grid (kWh AC). - `grid_to_battery_kwh_ac` number[], 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_dc` number[], 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_ac` number[], 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_ac` number[], 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_dc` number[], required — Amount of electricity from solar that goes unused (kWh DC). - `battery_to_site_kwh_ac` number[], 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_ac` number[], required — Amount of electricity flowing to the grid from battery, after conversion with `battery_dc_to_ac_efficiency` (kWh AC). - `net_load_kwh_ac` number[] — 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_soc` number[], 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. --- [API](https://skmtc.dev/arcadia/apis/arcadia-api-reference.md) · [All operations](https://skmtc.dev/arcadia/apis/arcadia-api-reference/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/arcadia/arcadia-api-reference/revisions/468f1c903722/schema)