# Time windows for controllable loads

(Professional accounts only)

If you have controllable loads, you can use this route to determine time windows in which switching processes can be automated based on the solar production forecast.

## URL

https://api.forecast.solar/:apikey/timewindows/:lat/:lon/:az/:dec/:kw https://api.forecast.solar/:apikey/timewindows/:lat/:lon/:dec1/:az1/:kwp1/:dec2/:az2/:kwp2 https://api.forecast.solar/:apikey/timewindows/:lat/:lon/:dec1/:az1/:kwp1/:dec2/:az2/:kwp2/:dec3/:az3/:kwp3 https://api.forecast.solar/:apikey/timewindows/:lat/:lon/:dec1/:az1/:kwp1/:dec2/:az2/:kwp2/:dec3/:az3/:kwp3/:dec4/:az4/:kwp4

## Areas of application

The following scenarios can be covered:

- Appliances that need to be switched on for a
**certain amount of time without interruption**(dishwasher, washing machine, etc.). - Appliances that need to be provided with a
**certain amount of watt hours**(battery, EV wall box). - Scenario 1 & 2 can be combined, if a time window is to be found in which a certain watt hours is also needed, e.g. for a dryer.
- Appliances with known
**constant power consumption**that can be switched on and off at any time, without a minimum running time (e.g. cartridge heater).

For scenarios 1, 2 & 3, the **earliest** and **latest** possible time windows in the course of the day that meet the criteria are determined respectively.
Also the **best** time window with the most watt hours is determined.

## Parameters

All parameters are optional and defaults to `0`

, so if no parameters are specified at all, the only time window is just sunrise to sunset, with the max. watts and max. watt hours of the day.

### Base load

Only watts above this value is considered usable.

baseload= (in watts)

For **scenario 4**, **add** the **required watts** to your normal **base load** here.

If a time window is then found, the required watts should be available above your normal base load.

### Required time window length

For scenario 1 & 3

period= (in minutes)

### Required watt hours

For scenario 2 & 3

watthours= (in watt hours)

### End time

**( planned)**

For scenario 2 & (possibly) 4

For example, if you plan to charge an electric vehicle and know when you need it, you can set an end time by which the windows should be calculated.

end= (HH:MM in 24h format, 00:00 … 23:59)

- If the end time is
**after**your local time, the end time is considered for**today**. - If the end time is
**before**your local time, the end time is considered for the**next day**.*It will work for the next day in Germany only after 2 PM after the exchange prices for the next day have been set.*

## Result

Set of time windows in the `result`

section of the response.

[ { start: ..., end: ..., watts: ... watthours: ... }, ... ]

`start`

and`end`

of the found time window- max. excepted
`watts`

above base load in this time window - excepted
`watt hours`

above needed for base load in this time window

If minimum window required (scenario 1 or 3):

- The
**earliest**possible time window for each day - The
**best**time window with max. watt hours for each day (only if watts hours are**higher**than in first and latest time window) - The
**latest**possible time window for each day

If no minimum time window length is required (scenario 2 or 4):

**All time windows**above base load, min. 15 minutes

For the **current day**, only time windows for the **rest of the day** are calculated.

## Examples

### No query parameters

[ ... { "start": "2023-08-11 06:00:00", "end": "2023-08-11 20:30:00", "watts": 5870, "watthours": 52704 }, .... ]

### Only base load 1 kW

`baseload=1000`

[ ... { "start": "2023-08-11 06:00:00", "end": "2023-08-11 18:45:00", "watts": 4870, "watthours": 38988 }, .... ]

### Base load 1 kW and 2 hours time windows

`baseload=1000&period=120`

[ ... { "start": "2023-08-11 06:00:00", "end": "2023-08-11 08:00:00", "watts": 2348, "watthours": 2649 }, { "start": "2023-08-11 11:15:00", "end": "2023-08-11 13:15:00", "watts": 4870, "watthours": 9591 }, { "start": "2023-08-11 16:45:00", "end": "2023-08-11 18:45:00", "watts": 2008, "watthours": 2157 }, .... ]

### Base load 1kW, 2 hours time windows with at least 5 kWh

`baseload=1000&period=120&watthours=5000`

[ ... { "start": "2023-08-11 07:15:00", "end": "2023-08-11 09:15:00", "watts": 3550, "watthours": 5166 }, { "start": "2023-08-11 11:15:00", "end": "2023-08-11 13:15:00", "watts": 4870, "watthours": 9591 }, { "start": "2023-08-11 15:15:00", "end": "2023-08-11 17:15:00", "watts": 3456, "watthours": 5018 }, .... ]

## More examples

### Base load of 1 kW and no time window needed

`?baseload=1000`

- 06:30 - 14:45, max. excess power abt. 6500 W
- 15:30 - 16:30, max. excess power abt. 200 W

### Base load of 1 kW and 2 h time window needed

`?baseload=1000&period=120`

- earliest 06:30 - 08:30, max. excess power abt. 4500 W
- optimal 10:30 - 12:30, max. excess power abt. 6500 W
- latest 12:45 - 14:45, max. excess power abt. 4000 W