Loads API¶

Base paths:

/core/api/communities/{community_id}/loads - measured (actual) loads
/core/api/communities/{community_id}/loads_forecast - forecast loads
/core/api/loads - general utilities (PVGIS generation factors)

Loads are time-series energy records per meter and 15-minute interval: one consumption and one generation value (kWh, both >= 0) for each (community, meter, datetime_timestamp). They are the raw input of market sessions and settlement. Load forecasts have exactly the same shape and endpoints, but are stored separately (table loads_forecasts) and are used by the energy management module instead of measurements.

This page covers the community-level loads and forecast loads. The device-specific load series (EV, water heater, heat pump, storage battery state) are documented in Device Loads.

Common behaviour:

Time zone. Timestamps are stored in UTC and returned in Europe/Lisbon (with the offset, e.g. 2024-01-15T10:00:00+00:00 in winter, +01:00 in summer).
Meters. Every record points to a meter (meter_id, a UUID). See Meters. Meter type is CPE, INTERNAL or AGGREGATOR_METER.
Async uploads. Upload endpoints validate the request synchronously and then hand the data to a Celery worker. They answer 201 with a task_id; poll GET /core/api/communities/{community_id}/tasks/{task_id}?group_task=false (see Communities) until state is SUCCESS or FAILURE. Processing errors (unknown meter, file too large, ...) appear in the task error, not in the upload response.
Upsert semantics. Uploading a record for an existing (meter, timestamp) replaces it.
Granularity. granularity accepts MIN15 (raw, default where optional), HOUR, DAY, MONTH, YEAR. Coarser values are summed (kWh) into buckets labelled with the bucket start (Lisbon local time). See Enums.
Date ranges. start_date and end_date are calendar dates (YYYY-MM-DD) and both are inclusive: the end date is extended to 23:59:59.999999.

Endpoint summary¶

Method	Path	Purpose
POST	`/core/api/communities/{community_id}/loads`	Upload loads as JSON records
POST	`/core/api/communities/{community_id}/loads/file_upload`	Upload loads as a CSV file
GET	`/core/api/communities/{community_id}/loads/pagination`	Table view: raw loads with paging, filters, sorting
GET	`/core/api/communities/{community_id}/loads`	Chart view: community loads aggregated by granularity
GET	`/core/api/communities/{community_id}/loads/loadsbymeter`	Loads per meter between two dates
GET	`/core/api/communities/{community_id}/loads/metrics/kpis`	Consumption / generation KPIs
DELETE	`/core/api/communities/{community_id}/loads`	Delete loads, optionally by date range
GET	`/core/api/loads/pvgis_generation`	PV generation factors from PVGIS
POST	`/core/api/communities/{community_id}/loads_forecast`	Upload load forecasts as JSON records
POST	`/core/api/communities/{community_id}/loads_forecast/file_upload`	Upload load forecasts as a CSV file
GET	`/core/api/communities/{community_id}/loads_forecast/pagination`	Table view: raw forecasts with paging, filters, sorting
GET	`/core/api/communities/{community_id}/loads_forecast`	Chart view: community forecasts aggregated by granularity
GET	`/core/api/communities/{community_id}/loads_forecast/loadsbymeter`	Forecasts per meter between two dates
GET	`/core/api/communities/{community_id}/loads_forecast/metrics/kpis`	Forecast consumption / generation KPIs
DELETE	`/core/api/communities/{community_id}/loads_forecast`	Delete forecasts, optionally by date range

Access rules¶

All endpoints in this page require a Bearer token of a verified user (see Authentication). The is_allowed dependency applies these rules:

Caller	`GET`	`POST` / `DELETE`
Platform super user	Allowed	Allowed
Community admin	Allowed	Allowed
Community member	Allowed	`403` (read-only)
Not a member of the community	`403`	`403`

For members, the table view (/pagination) and per-meter view (/loadsbymeter) are additionally restricted to the meters of the resources the member owns. The chart view and the KPIs are community-wide and are not restricted by ownership.

Measured loads¶

Upload Loads (JSON)¶

POST /core/api/communities/{community_id}/loads

Uploads an array of load records. Use it to push measurements from an integration. The records are processed asynchronously: they are upserted, missing market sessions are created as OPEN, existing sessions for those timestamps are reopened, and the affected sessions are invalidated (see tip).

Auth / permissions: super user or community admin.

Parameter	In	Type	Required	Description
`community_id`	path	UUID	Yes	Community that owns the loads
(body)	body	array of objects	Yes	Non-empty list of records
`[].meter_id`	body	UUID	Yes	Meter the record belongs to
`[].datetime_timestamp`	body	ISO 8601 datetime	Yes	Start of the 15-minute interval. A value without offset is read as UTC
`[].consumption`	body	number `>= 0`	Yes	Energy consumed in the interval (kWh)
`[].generation`	body	number `>= 0`	Yes	Energy generated in the interval (kWh)

Example

curl -X POST https://<host>/core/api/communities/3fa85f64-5717-4562-b3fc-2c963f66afa6/loads \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '[
    {
      "meter_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "datetime_timestamp": "2024-01-15T10:00:00+00:00",
      "consumption": 0.452,
      "generation": 0.0
    },
    {
      "meter_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "datetime_timestamp": "2024-01-15T10:15:00+00:00",
      "consumption": 0.431,
      "generation": 0.0
    }
  ]'

Response (201 Created)

{
  "message": "Processing started",
  "task_id": "b1c3a1f0-5c0f-4a35-9d6c-2f2f6a2c1a77"
}

Tip

An empty array returns 400 with {"message": "No loads provided."}. Negative values or missing fields return 422.
The endpoint does not check that meter_id belongs to the community; a wrong id makes the background task fail (visible in the task status).
The old energy_value / is_estimated fields do not exist. Send consumption and generation separately; to represent net energy use the CSV Energia column instead.
Uploading loads invalidates the market sessions of the affected timestamps: they go back to OPEN and their transactions, offers, allocations and settlement outputs are deleted. Re-run market clearing and settlement afterwards. See Business Validity.
On success the task message is Successfully inserted <n> loads.

Upload Loads (CSV file)¶

POST /core/api/communities/{community_id}/loads/file_upload

Uploads a CSV file with one row per meter and 15-minute interval. Meters are referenced by their identifier (column Contador), not by UUID. Processing is the same as the JSON upload.

Auth / permissions: super user or community admin.

Parameter	In	Type	Required	Description
`community_id`	path	UUID	Yes	Community that owns the loads
`file_upload`	body (multipart)	file (`text/csv`)	Yes	CSV file, see columns below

Accepted headers (exact names and order, comma separated):

Layout	Columns
Net energy (see template_consumos.csv)	`Data,Hora,Contador,Energia`
Consumption and generation	`Data,Hora,Contador,Consumo,Geracao`

Column	Format	Description
`Data`	`DD/MM/YYYY`	Date (Lisbon local)
`Hora`	`HH:MM`	End of the 15-minute interval (`00:15`, `00:30`, ..., as in the templates)
`Contador`	text	Meter `identifier`, matched case-insensitively
`Energia`	number	kWh; positive is consumption, negative is generation (stored as a positive generation value), zero sets both to 0
`Consumo` / `Geracao`	number	kWh consumption / generation for the interval

Example

curl -X POST https://<host>/core/api/communities/3fa85f64-5717-4562-b3fc-2c963f66afa6/loads/file_upload \
  -H "Authorization: Bearer $TOKEN" \
  -F "file_upload=@template_consumos.csv;type=text/csv"

File content:

Data,Hora,Contador,Energia
01/05/2023,00:15,CPE1,75.25
01/05/2023,00:30,CPE1,71.75
01/05/2023,00:45,CPE1,70.5

Response (201 Created)

{
  "message": "Processing started",
  "task_id": "b1c3a1f0-5c0f-4a35-9d6c-2f2f6a2c1a77"
}

Tip

Each row is stored with datetime_timestamp = Data + Hora minus 15 minutes, interpreted in Europe/Lisbon. So the row 01/05/2023,00:15 is stored for the interval starting 00:00. Ambiguous hours at the autumn DST change are resolved from the previous row; non-existent hours at the spring change are shifted forward one hour.
The meter is resolved by identifier using the meter version valid on each row's date (business validity). Unknown or ambiguous identifiers fail the task with No unambiguous meter version exists at the uploaded timestamps for: ....
Maximum 36,000 rows after dropping empty rows (about one year of 15-minute data for one meter); larger files fail the task with File exceeds maximum allowed size....
The file is validated synchronously: a non-text/csv content type returns 404 (Invalid document type), unreadable CSV or a header that does not match one of the two layouts returns 403 (Invalid document).
This route is not listed in the OpenAPI schema (include_in_schema=False) but is available. Sessions are created/reopened and invalidated exactly as in the JSON upload.

List Loads (Table View)¶

GET /core/api/communities/{community_id}/loads/pagination

Returns raw (non-aggregated) loads, one row per meter and interval, with server-side paging, filtering and sorting. Intended for table UIs; the response also carries the distinct values that the table filters can offer.

Auth / permissions: any community member (admin or member) or super user. Members only see loads of meters tied to resources they own.

Parameter	In	Type	Required	Description
`community_id`	path	UUID	Yes	Community
`limit`	query	integer	Yes	Number of rows to return
`offset`	query	integer	Yes	Number of rows to skip
`date`	query	string `YYYY-MM-DD`	No	Keep only this date
`time`	query	string `HH:MM:SS`	No	Keep only this time of day
`meter_id`	query	UUID	No	Keep only this meter
`meter_type`	query	`CPE` / `INTERNAL` / `AGGREGATOR_METER`	No	Keep only meters of this type
`sort_column`	query	string	No	`datetime_timestamp`, `date`, `time`, `meter_id` (sorts by meter identifier), `meter_type`, `consumption`, `generation`
`sort_direction`	query	string	No	`asc` for ascending; any other value (e.g. `desc`) sorts descending. Ignored without `sort_column`
`effective_at`	query	date	No	Date used to resolve which meters a member owns (defaults to today). No effect for admins

Example

curl "https://<host>/core/api/communities/3fa85f64-5717-4562-b3fc-2c963f66afa6/loads/pagination?limit=50&offset=0&sort_column=datetime_timestamp&sort_direction=desc&meter_type=CPE" \
  -H "Authorization: Bearer $TOKEN"

Response (abridged)

{
  "total_count": 2880,
  "data": [
    {
      "datetime_timestamp": "2024-01-15T10:15:00+00:00",
      "consumption": 0.431,
      "generation": 0.0,
      "meter_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "meter_type": "CPE"
    }
  ],
  "distinct_dates": [{ "date": "2024-01-14" }, { "date": "2024-01-15" }],
  "distinct_times": [{ "time": "00:00:00" }, { "time": "00:15:00" }],
  "distinct_meter_identifiers": [{ "meter_identifier": "PT0002000000000000000000001234" }]
}

Tip

Paging uses limit / offset (not skip / order_by). total_count is the number of rows matching the filters, before paging.
Only meters that are currently valid (not deleted, version effective today) are included, so loads of meters that already ended are not shown here; use /loadsbymeter for those.
distinct_dates and distinct_times reflect all active filters; distinct_meter_identifiers ignores the meter_id filter so the meter dropdown does not collapse to the selected meter.
A member who owns nothing gets an empty result, not an error. Users with no role in the community and not super users get 403 Access denied.

Get Aggregated Loads (Chart View)¶

GET /core/api/communities/{community_id}/loads

Returns the community time series: consumption and generation summed over all CPE meters for each interval, then summed into the requested granularity. Use it for community charts.

Auth / permissions: any community member or super user (not restricted by ownership).

Parameter	In	Type	Required	Description
`community_id`	path	UUID	Yes	Community
`start_date`	query	date	Yes	First day (inclusive)
`end_date`	query	date	Yes	Last day (inclusive)
`granularity`	query	`MIN15` / `HOUR` / `DAY` / `MONTH` / `YEAR`	No	Default `MIN15`

Example

curl "https://<host>/core/api/communities/3fa85f64-5717-4562-b3fc-2c963f66afa6/loads?start_date=2024-01-15&end_date=2024-01-16&granularity=HOUR" \
  -H "Authorization: Bearer $TOKEN"

Response (abridged)

[
  { "datetime_timestamp": "2024-01-15T00:00:00+00:00", "consumption": 12.84, "generation": 0.0 },
  { "datetime_timestamp": "2024-01-15T01:00:00+00:00", "consumption": 11.97, "generation": 0.0 }
]

Tip

Only meters of type CPE are included; INTERNAL and aggregator meters are not counted here (use /loadsbymeter or the KPIs for those).
Returns an empty list [] when there is no data in the range.
A missing or malformed start_date / end_date returns 422; an invalid granularity also returns 422.

Get Loads by Meter¶

GET /core/api/communities/{community_id}/loads/loadsbymeter

Returns one series per meter between two dates, with the meter type. Use it for per-meter comparisons and exports.

Auth / permissions: any community member or super user. Members only receive their own meters.

Parameter	In	Type	Required	Description
`community_id`	path	UUID	Yes	Community
`start_date`	query	date	Yes	First day (inclusive)
`end_date`	query	date	Yes	Last day (inclusive)
`granularity`	query	`MIN15` / `HOUR` / `DAY` / `MONTH` / `YEAR`	Yes	Aggregation level (no default on this route)
`meter_type`	query	`CPE` / `INTERNAL` / `AGGREGATOR_METER`	No	Restrict to one type. Default: `CPE` and `INTERNAL`
`effective_at`	query	date	No	Date used to resolve which meters a member owns (defaults to today)

Example

curl "https://<host>/core/api/communities/3fa85f64-5717-4562-b3fc-2c963f66afa6/loads/loadsbymeter?start_date=2024-01-15&end_date=2024-01-15&granularity=DAY&meter_type=CPE" \
  -H "Authorization: Bearer $TOKEN"

Response (abridged)

[
  {
    "datetime_timestamp": "2024-01-15T00:00:00+00:00",
    "consumption": 31.2,
    "generation": 0.0,
    "meter_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "meter_type": "CPE"
  }
]

Tip

granularity is required here, unlike the chart view.
Unlike the table view, this endpoint does not filter by meter validity date, so it also returns loads of meters that have since ended.
Returns [] when nothing matches (including a member who owns no meters).

Get Load KPIs¶

GET /core/api/communities/{community_id}/loads/metrics/kpis

Returns totals for the period, split by meter type: INTERNAL meters and CPE meters. Net consumption is consumption - generation and can be negative.

Auth / permissions: any community member or super user (community-wide, not restricted by ownership).

Parameter	In	Type	Required	Description
`community_id`	path	UUID	Yes	Community
`start_date`	query	date	Yes	First day (inclusive)
`end_date`	query	date	Yes	Last day (inclusive)

Example

curl "https://<host>/core/api/communities/3fa85f64-5717-4562-b3fc-2c963f66afa6/loads/metrics/kpis?start_date=2024-01-01&end_date=2024-01-31" \
  -H "Authorization: Bearer $TOKEN"

Response

{
  "total_consumption_internal": 1250.4,
  "total_generation_internal": 980.1,
  "total_net_consumption_internal": 270.3,
  "meter_highest_consumption_internal": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "total_consumption_cpe": 4310.8,
  "total_generation_cpe": 2105.6,
  "total_net_consumption_cpe": 2205.2,
  "meter_highest_consumption_cpe": "0b9f3a52-6d4f-4d70-8f55-6b7d3d6d5d11"
}

Tip

Totals are in kWh. A type with no data in the range returns 0 for the totals and null for meter_highest_consumption_* (the UUID of the meter with the largest summed consumption).
Aggregator meters are not included in any KPI.

Delete Loads¶

DELETE /core/api/communities/{community_id}/loads

Deletes the measured loads of a community, optionally limited to a date range. Without dates, all loads of the community are deleted.

Auth / permissions: super user or community admin.

Parameter	In	Type	Required	Description
`community_id`	path	UUID	Yes	Community
`start_date`	query	date	No	Delete from this day (inclusive)
`end_date`	query	date	No	Delete up to and including this day

Example

curl -X DELETE "https://<host>/core/api/communities/3fa85f64-5717-4562-b3fc-2c963f66afa6/loads?start_date=2024-01-01&end_date=2024-01-31" \
  -H "Authorization: Bearer $TOKEN"

Response (200 OK)

{ "message": "Loads deleted successfully" }

Tip

The delete is synchronous and permanent. It is applied even if no row matches (the response is always 200 for an existing community).
It only removes load rows: market sessions, transactions and settlement outputs for those timestamps are not touched or invalidated. Re-upload the corrected data (which does invalidate sessions) or rerun the market as needed.
Each bound can be used alone (only start_date deletes from that day onward; only end_date deletes everything up to that day).
Returns 404 if the community does not exist.

General utilities¶

Get PVGIS Generation Factors¶

GET /core/api/loads/pvgis_generation

Fetches hourly photovoltaic generation from the European Commission PVGIS service for a location and returns it as a list of kW values per installed kW. The platform uses it when no meters have generation values, to model PV production.

Auth / permissions: any verified user (the route has no community in its path, so only the authentication/verification check applies).

Parameter	In	Type	Required	Description
`latitude`	query	number	Yes	Latitude in decimal degrees
`longitude`	query	number	Yes	Longitude in decimal degrees
`start_year`	query	integer	Yes	First year of PVGIS data to fetch
`end_year`	query	integer	Yes	Last year of PVGIS data to fetch
`start_date`	query	string `YYYY-MM-DD`	No	With `end_date`, keep only this window and resample to 15 minutes
`end_date`	query	string `YYYY-MM-DD`	No	Last day (inclusive) of the window

Example

curl "https://<host>/core/api/loads/pvgis_generation?latitude=41.1579&longitude=-8.6291&start_year=2020&end_year=2020&start_date=2020-06-01&end_date=2020-06-01" \
  -H "Authorization: Bearer $TOKEN"

Response (abridged; 96 values for one day)

[0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0212, 0.0212, 0.0212, 0.0212]

Tip

The values are kW for a fixed reference system (1 kW peak, crystalline silicon, 0 degree tilt, 0% losses, free-standing), so scale them by the installed capacity.
Without both start_date and end_date the full hourly series for start_year to end_year is returned, not resampled. With both, the window is filtered and each hourly value is repeated four times to give a 15-minute series.
Window filtering compares against the PVGIS timestamps in UTC, not Lisbon time.
If the window contains no data the response is []. If PVGIS cannot be reached or returns nothing (30 s timeout), the endpoint answers 404 with PVGIS data could not be fetched.
This calls an external service on every request; cache the result on the client if you reuse it.

Forecast loads¶

The forecast endpoints mirror the measured-load endpoints above: same parameters, same response shapes, same access rules, same pagination and aggregation behaviour. The differences are listed in each section.

Upload Load Forecasts (JSON)¶

POST /core/api/communities/{community_id}/loads_forecast

Uploads an array of forecast records (same fields as Upload Loads (JSON)). Processing is asynchronous.

Auth / permissions: super user or community admin.

Parameter	In	Type	Required	Description
`community_id`	path	UUID	Yes	Community that owns the forecasts
(body)	body	array of objects	Yes	Non-empty list of records
`[].meter_id`	body	UUID	Yes	Meter the forecast belongs to
`[].datetime_timestamp`	body	ISO 8601 datetime	Yes	Start of the 15-minute interval. A value without offset is read as UTC
`[].consumption`	body	number `>= 0`	Yes	Forecast energy consumed (kWh)
`[].generation`	body	number `>= 0`	Yes	Forecast energy generated (kWh)

Example

curl -X POST https://<host>/core/api/communities/3fa85f64-5717-4562-b3fc-2c963f66afa6/loads_forecast \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '[
    {
      "meter_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "datetime_timestamp": "2024-01-16T00:00:00+00:00",
      "consumption": 0.40,
      "generation": 0.0
    }
  ]'

Response (201 Created)

{
  "message": "Processing started",
  "task_id": "b1c3a1f0-5c0f-4a35-9d6c-2f2f6a2c1a77"
}

Tip

An empty array returns 400 (No loads provided.); invalid values return 422.
Like measured loads, new timestamps get an OPEN market session and existing sessions for those timestamps are set back to OPEN. Unlike measured loads, forecast uploads do not run the invalidation step that deletes transactions and settlement outputs.
On success the task message is Successfully inserted <n> load forecast records.

Upload Load Forecasts (CSV file)¶

POST /core/api/communities/{community_id}/loads_forecast/file_upload

Uploads a forecast CSV. Accepted headers and formats are identical to Upload Loads (CSV file): Data,Hora,Contador,Energia or Data,Hora,Contador,Consumo,Geracao, DD/MM/YYYY dates and HH:MM interval-end times.

Auth / permissions: super user or community admin.

Parameter	In	Type	Required	Description
`community_id`	path	UUID	Yes	Community that owns the forecasts
`file_upload`	body (multipart)	file (`text/csv`)	Yes	CSV file with the columns above

Example

curl -X POST https://<host>/core/api/communities/3fa85f64-5717-4562-b3fc-2c963f66afa6/loads_forecast/file_upload \
  -H "Authorization: Bearer $TOKEN" \
  -F "file_upload=@forecast_consumos.csv;type=text/csv"

File content:

Data,Hora,Contador,Consumo,Geracao
16/01/2024,00:15,CPE1,0.40,0.0
16/01/2024,00:30,CPE1,0.38,0.0

Response (201 Created)

{
  "message": "Processing started",
  "task_id": "b1c3a1f0-5c0f-4a35-9d6c-2f2f6a2c1a77"
}

Tip

Timestamps are derived exactly as for measured loads (interval end minus 15 minutes, Lisbon time, 36,000 row limit) and the same synchronous file validation applies (404 wrong content type, 403 invalid header or unreadable CSV).
Meter identifiers are matched by a plain, case-sensitive comparison against the active meters valid today, not per row date. An identifier that does not match fails the task with Could not find meter_id for the following meter identifiers: ....
Not listed in the OpenAPI schema (include_in_schema=False).

List Load Forecasts (Table View)¶

GET /core/api/communities/{community_id}/loads_forecast/pagination

Same behaviour as List Loads (Table View), reading from the forecast table.

Auth / permissions: any community member or super user; members only see forecasts of meters they own.

Parameter	In	Type	Required	Description
`community_id`	path	UUID	Yes	Community
`limit`	query	integer	Yes	Number of rows to return
`offset`	query	integer	Yes	Number of rows to skip
`date`	query	string `YYYY-MM-DD`	No	Keep only this date
`time`	query	string `HH:MM:SS`	No	Keep only this time of day
`meter_id`	query	UUID	No	Keep only this meter
`meter_type`	query	`CPE` / `INTERNAL` / `AGGREGATOR_METER`	No	Keep only meters of this type
`sort_column`	query	string	No	`datetime_timestamp`, `date`, `time`, `meter_id`, `meter_type`, `consumption`, `generation`
`sort_direction`	query	string	No	`asc` or anything else for descending
`effective_at`	query	date	No	Date used to resolve a member's meters (defaults to today)

Example

curl "https://<host>/core/api/communities/3fa85f64-5717-4562-b3fc-2c963f66afa6/loads_forecast/pagination?limit=50&offset=0&sort_column=datetime_timestamp&sort_direction=asc" \
  -H "Authorization: Bearer $TOKEN"

Response (abridged)

{
  "total_count": 96,
  "data": [
    {
      "datetime_timestamp": "2024-01-16T00:00:00+00:00",
      "consumption": 0.40,
      "generation": 0.0,
      "meter_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "meter_type": "CPE"
    }
  ],
  "distinct_dates": [{ "date": "2024-01-16" }],
  "distinct_times": [{ "time": "00:00:00" }, { "time": "00:15:00" }],
  "distinct_meter_identifiers": [{ "meter_identifier": "CPE1" }]
}

Tip

Paging is limit / offset. Only meters valid today are listed, as in the measured-load table view.

Get Aggregated Load Forecasts (Chart View)¶

GET /core/api/communities/{community_id}/loads_forecast

Community forecast series summed over CPE meters and aggregated by granularity. See Get Aggregated Loads.

Auth / permissions: any community member or super user (not restricted by ownership).

Parameter	In	Type	Required	Description
`community_id`	path	UUID	Yes	Community
`start_date`	query	date	Yes	First day (inclusive)
`end_date`	query	date	Yes	Last day (inclusive)
`granularity`	query	`MIN15` / `HOUR` / `DAY` / `MONTH` / `YEAR`	No	Default `MIN15`

Example

curl "https://<host>/core/api/communities/3fa85f64-5717-4562-b3fc-2c963f66afa6/loads_forecast?start_date=2024-01-16&end_date=2024-01-17&granularity=HOUR" \
  -H "Authorization: Bearer $TOKEN"

Response (abridged)

[
  { "datetime_timestamp": "2024-01-16T00:00:00+00:00", "consumption": 1.62, "generation": 0.0 }
]

Tip

Returns [] when no forecast exists in the range. Only CPE meters are summed.

Get Load Forecasts by Meter¶

GET /core/api/communities/{community_id}/loads_forecast/loadsbymeter

Per-meter forecast series between two dates. See Get Loads by Meter.

Auth / permissions: any community member or super user; members only receive their own meters.

Parameter	In	Type	Required	Description
`community_id`	path	UUID	Yes	Community
`start_date`	query	date	Yes	First day (inclusive)
`end_date`	query	date	Yes	Last day (inclusive)
`granularity`	query	`MIN15` / `HOUR` / `DAY` / `MONTH` / `YEAR`	Yes	Aggregation level
`meter_type`	query	`CPE` / `INTERNAL` / `AGGREGATOR_METER`	No	Default: `CPE` and `INTERNAL`
`effective_at`	query	date	No	Date used to resolve a member's meters (defaults to today)

Example

curl "https://<host>/core/api/communities/3fa85f64-5717-4562-b3fc-2c963f66afa6/loads_forecast/loadsbymeter?start_date=2024-01-16&end_date=2024-01-16&granularity=HOUR" \
  -H "Authorization: Bearer $TOKEN"

Response (abridged)

[
  {
    "datetime_timestamp": "2024-01-16T00:00:00+00:00",
    "consumption": 1.62,
    "generation": 0.0,
    "meter_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "meter_type": "CPE"
  }
]

Tip

granularity is mandatory on this route. Returns [] when nothing matches.

Get Load Forecast KPIs¶

GET /core/api/communities/{community_id}/loads_forecast/metrics/kpis

Forecast totals for the period, split by INTERNAL and CPE meters; same response fields as Get Load KPIs.

Auth / permissions: any community member or super user (community-wide).

Parameter	In	Type	Required	Description
`community_id`	path	UUID	Yes	Community
`start_date`	query	date	Yes	First day (inclusive)
`end_date`	query	date	Yes	Last day (inclusive)

Example

curl "https://<host>/core/api/communities/3fa85f64-5717-4562-b3fc-2c963f66afa6/loads_forecast/metrics/kpis?start_date=2024-01-16&end_date=2024-01-22" \
  -H "Authorization: Bearer $TOKEN"

Response

{
  "total_consumption_internal": 310.2,
  "total_generation_internal": 190.7,
  "total_net_consumption_internal": 119.5,
  "meter_highest_consumption_internal": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "total_consumption_cpe": 1020.4,
  "total_generation_cpe": 512.9,
  "total_net_consumption_cpe": 507.5,
  "meter_highest_consumption_cpe": "0b9f3a52-6d4f-4d70-8f55-6b7d3d6d5d11"
}

Tip

Values are kWh computed from forecast rows only. Empty periods give 0 totals and null meter ids.

Delete Load Forecasts¶

DELETE /core/api/communities/{community_id}/loads_forecast

Deletes the forecast loads of a community, optionally limited to a date range. Without dates, all forecasts of the community are deleted.

Auth / permissions: super user or community admin.

Parameter	In	Type	Required	Description
`community_id`	path	UUID	Yes	Community
`start_date`	query	date	No	Delete from this day (inclusive)
`end_date`	query	date	No	Delete up to and including this day

Example

curl -X DELETE "https://<host>/core/api/communities/3fa85f64-5717-4562-b3fc-2c963f66afa6/loads_forecast?start_date=2024-01-16&end_date=2024-01-22" \
  -H "Authorization: Bearer $TOKEN"

Response (200 OK)

{ "message": "Load forecasts deleted successfully" }

Tip

Permanent and synchronous; sessions are not modified. Measured loads are not affected. Returns 404 if the community does not exist.