Weather

If your Home Assistant has a weather.* entity wired up (most installs do), push the hourly forecast once daily so the optimizer plans against your local weather rather than a generic fallback. The Hungry Machines app does this for you automatically; custom integrations should set up a daily rest_command.

Each push is stored for the next optimization run and retained as history that later helps fill outdoor-temperature gaps. If no fresh push is available when the overnight run happens (older than 24 hours, or never pushed), a fallback weather source is used for that account.

POST /api/v1/weather

Auth: Required (Bearer JWT)

Required vs. optional

Only forecast.hourly_temps_f (24–72 values) is required. forecast.hourly_humidity and forecast.hourly_wind_mph are optional — send them when your weather entity exposes them.

Example

curl -X POST https://api.hungrymachines.io/api/v1/weather \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "forecast": {
      "hourly_temps_f": [54.2, 53.8, "...(24-72 values)"],
      "hourly_humidity": [62, 64, "..."],
      "hourly_wind_mph":  [3.1, 2.8, "..."]
    }
  }'

Request body

{
  "forecast": {
    "hourly_temps_f": [54.2, 53.8, 53.5, "..."],
    "hourly_humidity": [62, 64, 65, "..."],
    "hourly_wind_mph": [3.1, 2.8, 2.5, "..."]
  }
}

Field	Type	Required	Validation
forecast.hourly_temps_f	array[float]	Yes	24–72 hourly values, each in [-50, 150] °F. Starts at hour 0 of the push date and walks forward.
forecast.hourly_humidity	array[float] | null	No	Same length as hourly_temps_f. Each value in [0, 100] percent. Omit or send null to skip.
forecast.hourly_wind_mph	array[float] | null	No	Same length as hourly_temps_f. Each value in [0, 200] mph. Omit or send null to skip.

Tip

The minimum 24 hours covers the next day’s nightly optimization. Pushing 48–72 hours is fine — Home Assistant’s weather.get_forecasts typically returns 3 days, and the extra hours give the weekly model refit more outdoor-temp data to gap-fill from.

Response (201)

{
  "accepted_hours": 48,
  "pushed_at": "2025-11-18T03:30:00+00:00"
}

Field	Type	Notes
accepted_hours	integer	Number of hourly entries stored from hourly_temps_f
pushed_at	string	UTC ISO 8601 timestamp when the row was saved

Errors

Status	Detail	Cause
400	"forecast.hourly_temps_f must contain between 24 and 72 hourly values"	Array length out of bounds
400	"forecast.hourly_temps_f[<i>]=<v> is outside the allowed range [-50, 150]"	Value out of range or non-finite
400	"forecast.hourly_humidity length must match hourly_temps_f"	Array lengths disagree
401	"Not authenticated"	Missing or invalid token
503	"Database unavailable"	Database not reachable
503	"Failed to store weather forecast"	DB write failed

When to push

Push once per day, before the account’s overnight optimization run. Any push from the last 24 hours counts as fresh, so missing a single day simply falls back to a server-side weather source (or the most recent prior push).

A typical Home Assistant rest_command + automation:

rest_command:
  hm_push_weather:
    url: "https://api.hungrymachines.io/api/v1/weather"
    method: POST
    headers:
      Authorization: "Bearer !secret hm_access_token"
      Content-Type: "application/json"
    payload: >
      {
        "forecast": {
          "hourly_temps_f": {{ state_attr('weather.home', 'forecast') | map(attribute='temperature') | list | tojson }}
        }
      }

automation:
  - alias: "HM — push weather forecast at 03:30 UTC"
    trigger:
      - platform: time
        at: "03:30:00"
    action:
      - service: rest_command.hm_push_weather

Adjust the entity (weather.home) and forecast attribute path to match what your weather integration exposes. Open-Meteo’s HA integration returns forecast as a list of dicts with a temperature field; some integrations use templow/temperature per day instead — verify in Developer Tools → States first.