Skip to content

Device Loads API

Base path: /core/api/communities/{community_id}

Device loads are the time-series inputs of the flexible devices of a community: electric vehicles, stationary batteries, electric water heaters (EWH) and heat pumps (HP). They feed the energy-management optimisation modules; they are not smart-meter readings (for those see Loads).

Each dataset lives under its own sub-path and offers the same two operations: upload (CSV, plus JSON for the heat-pump inputs) and a paginated listing. All data is stored at 15-minute granularity, keyed by (datetime_timestamp, device id, community), and is not versioned by business validity: re-uploading overwrites the same intervals.

Sub-path Device Field Consumed by
ev_battery_state_loads EV charge_state OSTEC Simple, OSTEC Promotor
ev_charging_intervals_forecast EV is_connected OSTEC Simple, OSTEC Promotor
ev_driving_loads EV driving_consumption OSTEC Simple, OSTEC Promotor
storage_battery_state_loads Storage battery charge_state OSTEC Simple, OSTEC Promotor
ewh_usage EWH duration not read by any module today
water_mass_usage_forecast Heat pump mass_value not read by any module today
outside_temp_loads Heat pump temperature not read by any module today

See OSTEC Simple, OSTEC Promotor and the optimisation overview for how each module uses these inputs, and Upload Templates for the CSV templates used in the examples.

Endpoint summary

Method Path Purpose
POST /core/api/communities/{community_id}/ev_battery_state_loads Upload EV Battery State as a CSV file
GET /core/api/communities/{community_id}/ev_battery_state_loads/pagination List EV Battery State rows (paginated, filterable)
POST /core/api/communities/{community_id}/ev_charging_intervals_forecast Upload EV Charging Intervals Forecast as a CSV file
GET /core/api/communities/{community_id}/ev_charging_intervals_forecast/pagination List EV Charging Intervals Forecast rows (paginated, filterable)
POST /core/api/communities/{community_id}/ev_driving_loads Upload EV Driving Loads as a CSV file
GET /core/api/communities/{community_id}/ev_driving_loads/pagination List EV Driving Loads rows (paginated, filterable)
POST /core/api/communities/{community_id}/storage_battery_state_loads Upload Storage Battery State as a CSV file
GET /core/api/communities/{community_id}/storage_battery_state_loads/pagination List Storage Battery State rows (paginated, filterable)
POST /core/api/communities/{community_id}/ewh_usage Upload EWH Usage as a CSV file
GET /core/api/communities/{community_id}/ewh_usage/pagination List EWH Usage rows (paginated, filterable)
POST /core/api/communities/{community_id}/water_mass_usage_forecast Upload Heat Pump Water Mass Usage Forecast as JSON records
POST /core/api/communities/{community_id}/water_mass_usage_forecast/file_upload Upload Heat Pump Water Mass Usage Forecast as a CSV file (hidden from OpenAPI)
GET /core/api/communities/{community_id}/water_mass_usage_forecast/pagination List Heat Pump Water Mass Usage Forecast rows (paginated, filterable)
POST /core/api/communities/{community_id}/outside_temp_loads Upload Heat Pump Outside Temperature as JSON records
POST /core/api/communities/{community_id}/outside_temp_loads/file_upload Upload Heat Pump Outside Temperature as a CSV file (hidden from OpenAPI)
GET /core/api/communities/{community_id}/outside_temp_loads/pagination List Heat Pump Outside Temperature rows (paginated, filterable)

Common behaviour

  • Authentication: every endpoint requires a bearer token of a verified user and the community in the path must exist (404 otherwise). Reads need community membership (any role); uploads need community admin or platform admin (members get 403).
  • Resources are referenced by id in responses and by name in CSV files. CSV uploads use the resource name in the Recurso column; rows and JSON records use the resource UUID (ev_id, storage_id, ewh_id, hp_id). Create the resources first, see Meters and resources and Resources.
  • CSV format: comma separated, header exactly Data,Hora,Recurso,<value column>, Data as DD/MM/YYYY, Hora as HH:MM marking the end of the 15-minute interval. Timestamps are stored shifted back by 15 minutes (interval start) in Europe/Lisbon time.
  • Asynchronous processing: uploads return 201 with a task_id as soon as the task is queued. Check the outcome with GET /core/api/communities/{community_id}/tasks/{task_id}?group_task=false (see Communities).
  • Listing responses share the shape { "total_count", "data", "distinct_dates", "distinct_times" }; see Schemas for general conventions.
  • Units: energy in kWh, temperature in degrees Celsius, water mass in kg, time zone Europe/Lisbon, 15-minute resolution.

EV inputs

Inputs for electric-vehicle (EV) resources: battery state, forecast plug-in windows and driving consumption. The optimisers combine the three to plan EV charging.

EV Battery State (ev_battery_state_loads): Read by OSTEC Simple and OSTEC Promotor (and the legacy setpoint calculation) as the initial EV energy. Only the latest value at or before the start of the optimisation horizon is used, and only if it is at most 4 hours old; otherwise the EV minimum SOC (min_SOC x nominal_capacity) is assumed.

Upload EV Battery State

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

Uploads a CSV file with the state of charge of an electric vehicle battery (charge_state) for one or more EV resources. The file is processed asynchronously. Template: template_bateria.csv.

Auth / permissions: community admin of the target community or platform admin. Plain community members receive 403 (Community members can only perform read operations).

Parameter In Type Required Description
community_id path UUID Yes Community the data belongs to.
file_upload body (multipart) file (text/csv) Yes CSV with columns Data, Hora, Recurso, EstadoCargaBateria, comma-separated.

CSV columns:

Column Meaning
Data Date, DD/MM/YYYY.
Hora End of the 15-minute interval, HH:MM.
Recurso Name of the EV resource in the community.
EstadoCargaBateria Battery charge state of the EV at the timestamp. The optimisers read it as the initial stored energy of the vehicle (kWh).

Example

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

File content (same columns as the template template_bateria.csv):

Data,Hora,Recurso,EstadoCargaBateria
01/05/2023,00:15,Recurso1,14.2
01/05/2023,00:30,Recurso1,14.9
01/05/2023,00:45,Recurso1,15.6

Response (abridged)

{
  "message": "Processing started",
  "task_id": "b1f3c0de-6f0a-4f4e-8d57-1f2c2b8f9a10"
}

Tip

  • Multipart field name is file_upload. The part must have content type text/csv (hence ;type=text/csv in curl), otherwise the call fails with 404 Invalid document type; a header that is not exactly Data,Hora,Recurso,EstadoCargaBateria (this order) fails with 403 Invalid document.
  • 201 only means the file was queued on the Celery file_uploads queue. Parsing, resource lookup and insertion happen asynchronously: poll GET /core/api/communities/{community_id}/tasks/{task_id}?group_task=false (see Communities) and read state, message and error.
  • Data is DD/MM/YYYY, Hora is HH:MM. Hora is the END of the 15-minute interval: the stored datetime_timestamp is Data Hora minus 15 minutes, interpreted in Europe/Lisbon (DST changes handled). 24:00 is not accepted by the parser; write the last interval of a day as 00:00 of the next date.
  • Recurso must equal the name of an existing EV resource in the community; unknown names make the task fail with Could not find resource_id for the following ... identifiers. The matching resource must be of the correct type, since ev_id is a foreign key.
  • At most 36,000 rows per file (about one year of 15-minute data for one resource); completely empty rows are dropped.
  • Upload is an overwrite, not an append: for every (timestamp, resource) pair in the file the existing row is deleted and replaced; pairs not in the file are untouched.
  • Side effect on the local market: sessions are created (status OPEN) for timestamps that have none, and existing sessions at those timestamps are reset to OPEN with the community's current allocation-coefficient method and market rate. See Sessions and market.
  • Only the latest reading before the horizon start matters for the optimisers, so uploading a single row per EV at the current time is enough.

List EV Battery State

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

Returns a page of stored EV Battery State rows for the community, with the total number of matching rows and the distinct dates and times present in the filtered set. This is the endpoint behind the data tables in the web UI.

Auth / permissions: any authenticated, verified member of the community, community admin or platform admin. Admins and platform admins see every (non-deleted) resource of the community; a plain member only sees rows of resources they own.

Parameter In Type Required Description
community_id path UUID Yes Community whose data is read.
limit query integer Yes Page size (number of rows returned).
offset query integer Yes Number of rows to skip.
date query string YYYY-MM-DD No Return only rows whose timestamp falls on this calendar date.
start_date query string YYYY-MM-DD No Lower bound (inclusive) of a date range. Only applied together with end_date and when date is not set.
end_date query string YYYY-MM-DD No Upper bound (inclusive) of a date range. Only applied together with start_date and when date is not set.
time query string HH:MM:SS No Return only rows whose timestamp has this time of day.
resource_id query UUID No Return only rows of this EV resource (ev_id).
sort_column query string No datetime_timestamp, date, time, resource_id (see tip) or the value column. Without it the order is unspecified.
sort_direction query string No asc for ascending; any other value (or omitted) sorts descending. Only used when sort_column is set.
effective_at query date YYYY-MM-DD No Only relevant for community members: the date used to resolve which resources they own (defaults to today). Admins are unaffected.

Example

curl -G https://<host>/core/api/communities/3fa85f64-5717-4562-b3fc-2c963f66afa6/ev_battery_state_loads/pagination \
  -H "Authorization: Bearer $TOKEN" \
  --data-urlencode "limit=100" \
  --data-urlencode "offset=0" \
  --data-urlencode "start_date=2023-05-01" \
  --data-urlencode "end_date=2023-05-07" \
  --data-urlencode "resource_id=7c9e6679-7425-40de-944b-e07fc1f90ae7" \
  --data-urlencode "sort_column=datetime_timestamp" \
  --data-urlencode "sort_direction=asc"

Response (abridged)

{
  "total_count": 96,
  "data": [
    {
      "datetime_timestamp": "2023-05-01T00:00:00+01:00",
      "ev_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "charge_state": 14.2,
      "community_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
    }
  ],
  "distinct_dates": [{ "date": "2023-05-01" }],
  "distinct_times": [{ "time": "00:00:00" }, { "time": "00:15:00" }]
}

Tip

  • limit and offset are required; omitting them returns 422. total_count, distinct_dates and distinct_times are computed over the whole filtered set, not just the returned page.
  • sort_column=resource_id sorts by the resource name (joined from the resources table).
  • date, time and resource_id filters combine with AND. start_date / end_date are ignored unless both are given, and are ignored when date is set.
  • datetime_timestamp is the start of the 15-minute interval (timezone-aware, Europe/Lisbon local offset). The row field is ev_id, not resource_id; the resource_id query parameter filters on it.
  • Returns 404 if the community does not exist and 403 if the caller is not a member of it.

EV Charging Intervals Forecast (ev_charging_intervals_forecast): Read by OSTEC Simple and OSTEC Promotor as the EV availability vector (bin_ev): charging power is forced to zero in intervals where it is 0.

Upload EV Charging Intervals Forecast

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

Uploads a CSV file with the forecast of whether an EV is plugged in and available to charge (is_connected) for one or more EV resources. The file is processed asynchronously. Template: template_charging_intervals_forecast.csv.

Auth / permissions: community admin of the target community or platform admin. Plain community members receive 403 (Community members can only perform read operations).

Parameter In Type Required Description
community_id path UUID Yes Community the data belongs to.
file_upload body (multipart) file (text/csv) Yes CSV with columns Data, Hora, Recurso, Carregar, comma-separated.

CSV columns:

Column Meaning
Data Date, DD/MM/YYYY.
Hora End of the 15-minute interval, HH:MM.
Recurso Name of the EV resource in the community.
Carregar true when the EV is connected (may charge) in the interval, false otherwise. In the CSV the column Carregar carries 1 / 0.

Example

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

File content (same columns as the template template_charging_intervals_forecast.csv):

Data,Hora,Recurso,Carregar
01/05/2023,00:15,Recurso1,1
01/05/2023,00:30,Recurso1,0
01/05/2023,00:45,Recurso1,1

Response (abridged)

{
  "message": "Processing started",
  "task_id": "b1f3c0de-6f0a-4f4e-8d57-1f2c2b8f9a10"
}

Tip

  • Multipart field name is file_upload. The part must have content type text/csv (hence ;type=text/csv in curl), otherwise the call fails with 404 Invalid document type; a header that is not exactly Data,Hora,Recurso,Carregar (this order) fails with 403 Invalid document.
  • 201 only means the file was queued on the Celery file_uploads queue. Parsing, resource lookup and insertion happen asynchronously: poll GET /core/api/communities/{community_id}/tasks/{task_id}?group_task=false (see Communities) and read state, message and error.
  • Data is DD/MM/YYYY, Hora is HH:MM. Hora is the END of the 15-minute interval: the stored datetime_timestamp is Data Hora minus 15 minutes, interpreted in Europe/Lisbon (DST changes handled). 24:00 is not accepted by the parser; write the last interval of a day as 00:00 of the next date.
  • Recurso must equal the name of an existing EV resource in the community; unknown names make the task fail with Could not find resource_id for the following ... identifiers. The matching resource must be of the correct type, since ev_id is a foreign key.
  • At most 36,000 rows per file (about one year of 15-minute data for one resource); completely empty rows are dropped.
  • Upload is an overwrite, not an append: for every (timestamp, resource) pair in the file the existing row is deleted and replaced; pairs not in the file are untouched.
  • Side effect on the local market: sessions are created (status OPEN) for timestamps that have none, and existing sessions at those timestamps are reset to OPEN with the community's current allocation-coefficient method and market rate. See Sessions and market.
  • Use 1 for connected and 0 for not connected; the optimisers cast the stored boolean to an integer.

List EV Charging Intervals Forecast

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

Returns a page of stored EV Charging Intervals Forecast rows for the community, with the total number of matching rows and the distinct dates and times present in the filtered set. This is the endpoint behind the data tables in the web UI.

Auth / permissions: any authenticated, verified member of the community, community admin or platform admin. Admins and platform admins see every (non-deleted) resource of the community; a plain member only sees rows of resources they own.

Parameter In Type Required Description
community_id path UUID Yes Community whose data is read.
limit query integer Yes Page size (number of rows returned).
offset query integer Yes Number of rows to skip.
date query string YYYY-MM-DD No Return only rows whose timestamp falls on this calendar date.
start_date query string YYYY-MM-DD No Lower bound (inclusive) of a date range. Only applied together with end_date and when date is not set.
end_date query string YYYY-MM-DD No Upper bound (inclusive) of a date range. Only applied together with start_date and when date is not set.
time query string HH:MM:SS No Return only rows whose timestamp has this time of day.
resource_id query UUID No Return only rows of this EV resource (ev_id).
sort_column query string No datetime_timestamp, date, time, resource_id (see tip) or the value column. Without it the order is unspecified.
sort_direction query string No asc for ascending; any other value (or omitted) sorts descending. Only used when sort_column is set.
effective_at query date YYYY-MM-DD No Only relevant for community members: the date used to resolve which resources they own (defaults to today). Admins are unaffected.

Example

curl -G https://<host>/core/api/communities/3fa85f64-5717-4562-b3fc-2c963f66afa6/ev_charging_intervals_forecast/pagination \
  -H "Authorization: Bearer $TOKEN" \
  --data-urlencode "limit=100" \
  --data-urlencode "offset=0" \
  --data-urlencode "start_date=2023-05-01" \
  --data-urlencode "end_date=2023-05-07" \
  --data-urlencode "resource_id=7c9e6679-7425-40de-944b-e07fc1f90ae7" \
  --data-urlencode "sort_column=datetime_timestamp" \
  --data-urlencode "sort_direction=asc"

Response (abridged)

{
  "total_count": 96,
  "data": [
    {
      "datetime_timestamp": "2023-05-01T00:00:00+01:00",
      "ev_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "is_connected": true,
      "community_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
    }
  ],
  "distinct_dates": [{ "date": "2023-05-01" }],
  "distinct_times": [{ "time": "00:00:00" }, { "time": "00:15:00" }]
}

Tip

  • limit and offset are required; omitting them returns 422. total_count, distinct_dates and distinct_times are computed over the whole filtered set, not just the returned page.
  • sort_column=resource_id is unreliable on this endpoint: the code joins .resource on the load model, which is not defined there, so expect a server error (500). Sort by datetime_timestamp, date or time instead.
  • date, time and resource_id filters combine with AND. start_date / end_date are ignored unless both are given, and are ignored when date is set.
  • datetime_timestamp is the start of the 15-minute interval (timezone-aware, Europe/Lisbon local offset). The row field is ev_id, not resource_id; the resource_id query parameter filters on it.
  • Returns 404 if the community does not exist and 403 if the caller is not a member of it.

EV Driving Loads (ev_driving_loads): Read by OSTEC Simple and OSTEC Promotor as the trip consumption of the EV (trip_ev), using abs(driving_consumption) for each interval of the horizon.

Upload EV Driving Loads

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

Uploads a CSV file with the energy an EV consumes while driving (driving_consumption) for one or more EV resources. The file is processed asynchronously. Template: template_driving_loads.csv.

Auth / permissions: community admin of the target community or platform admin. Plain community members receive 403 (Community members can only perform read operations).

Parameter In Type Required Description
community_id path UUID Yes Community the data belongs to.
file_upload body (multipart) file (text/csv) Yes CSV with columns Data, Hora, Recurso, Energia, comma-separated.

CSV columns:

Column Meaning
Data Date, DD/MM/YYYY.
Hora End of the 15-minute interval, HH:MM.
Recurso Name of the EV resource in the community.
Energia Energy consumed by driving in the interval (kWh). The template uses negative numbers; the optimisers take the absolute value.

Example

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

File content (same columns as the template template_driving_loads.csv):

Data,Hora,Recurso,Energia
01/05/2023,00:15,Recurso1,-75.25
01/05/2023,00:30,Recurso1,-71.75
01/05/2023,00:45,Recurso1,-70.5

Response (abridged)

{
  "message": "Processing started",
  "task_id": "b1f3c0de-6f0a-4f4e-8d57-1f2c2b8f9a10"
}

Tip

  • Multipart field name is file_upload. The part must have content type text/csv (hence ;type=text/csv in curl), otherwise the call fails with 404 Invalid document type; a header that is not exactly Data,Hora,Recurso,Energia (this order) fails with 403 Invalid document.
  • 201 only means the file was queued on the Celery file_uploads queue. Parsing, resource lookup and insertion happen asynchronously: poll GET /core/api/communities/{community_id}/tasks/{task_id}?group_task=false (see Communities) and read state, message and error.
  • Data is DD/MM/YYYY, Hora is HH:MM. Hora is the END of the 15-minute interval: the stored datetime_timestamp is Data Hora minus 15 minutes, interpreted in Europe/Lisbon (DST changes handled). 24:00 is not accepted by the parser; write the last interval of a day as 00:00 of the next date.
  • Recurso must equal the name of an existing EV resource in the community; unknown names make the task fail with Could not find resource_id for the following ... identifiers. The matching resource must be of the correct type, since ev_id is a foreign key.
  • At most 36,000 rows per file (about one year of 15-minute data for one resource); completely empty rows are dropped.
  • Upload is an overwrite, not an append: for every (timestamp, resource) pair in the file the existing row is deleted and replaced; pairs not in the file are untouched.
  • Side effect on the local market: sessions are created (status OPEN) for timestamps that have none, and existing sessions at those timestamps are reset to OPEN with the community's current allocation-coefficient method and market rate. See Sessions and market.
  • The sign is not validated: both -75.25 (as in the template) and 75.25 are accepted, and both are used as 75.25 by the optimisers.

List EV Driving Loads

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

Returns a page of stored EV Driving Loads rows for the community, with the total number of matching rows and the distinct dates and times present in the filtered set. This is the endpoint behind the data tables in the web UI.

Auth / permissions: any authenticated, verified member of the community, community admin or platform admin. Admins and platform admins see every (non-deleted) resource of the community; a plain member only sees rows of resources they own.

Parameter In Type Required Description
community_id path UUID Yes Community whose data is read.
limit query integer Yes Page size (number of rows returned).
offset query integer Yes Number of rows to skip.
date query string YYYY-MM-DD No Return only rows whose timestamp falls on this calendar date.
start_date query string YYYY-MM-DD No Lower bound (inclusive) of a date range. Only applied together with end_date and when date is not set.
end_date query string YYYY-MM-DD No Upper bound (inclusive) of a date range. Only applied together with start_date and when date is not set.
time query string HH:MM:SS No Return only rows whose timestamp has this time of day.
resource_id query UUID No Return only rows of this EV resource (ev_id).
sort_column query string No datetime_timestamp, date, time, resource_id (see tip) or the value column. Without it the order is unspecified.
sort_direction query string No asc for ascending; any other value (or omitted) sorts descending. Only used when sort_column is set.
effective_at query date YYYY-MM-DD No Only relevant for community members: the date used to resolve which resources they own (defaults to today). Admins are unaffected.

Example

curl -G https://<host>/core/api/communities/3fa85f64-5717-4562-b3fc-2c963f66afa6/ev_driving_loads/pagination \
  -H "Authorization: Bearer $TOKEN" \
  --data-urlencode "limit=100" \
  --data-urlencode "offset=0" \
  --data-urlencode "start_date=2023-05-01" \
  --data-urlencode "end_date=2023-05-07" \
  --data-urlencode "resource_id=7c9e6679-7425-40de-944b-e07fc1f90ae7" \
  --data-urlencode "sort_column=datetime_timestamp" \
  --data-urlencode "sort_direction=asc"

Response (abridged)

{
  "total_count": 96,
  "data": [
    {
      "datetime_timestamp": "2023-05-01T00:00:00+01:00",
      "ev_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "driving_consumption": -3.75,
      "community_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
    }
  ],
  "distinct_dates": [{ "date": "2023-05-01" }],
  "distinct_times": [{ "time": "00:00:00" }, { "time": "00:15:00" }]
}

Tip

  • limit and offset are required; omitting them returns 422. total_count, distinct_dates and distinct_times are computed over the whole filtered set, not just the returned page.
  • sort_column=resource_id is unreliable on this endpoint: the code joins .resource on the load model, which is not defined there, so expect a server error (500). Sort by datetime_timestamp, date or time instead.
  • date, time and resource_id filters combine with AND. start_date / end_date are ignored unless both are given, and are ignored when date is set.
  • datetime_timestamp is the start of the 15-minute interval (timezone-aware, Europe/Lisbon local offset). The row field is ev_id, not resource_id; the resource_id query parameter filters on it.
  • Returns 404 if the community does not exist and 403 if the caller is not a member of it.

Storage battery inputs

Inputs for stationary storage-battery (STORAGE) resources.

Storage Battery State (storage_battery_state_loads): Read by OSTEC Simple and OSTEC Promotor (and the legacy setpoint calculation) as the initial battery energy (init_e). Only the latest value at or before the start of the horizon is used, and only if it is at most 4 hours old; otherwise min_SOC / 100 x nominal_capacity is assumed.

Upload Storage Battery State

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

Uploads a CSV file with the state of charge of a stationary storage battery (charge_state) for one or more STORAGE resources. The file is processed asynchronously. Template: template_bateria.csv.

Auth / permissions: community admin of the target community or platform admin. Plain community members receive 403 (Community members can only perform read operations).

Parameter In Type Required Description
community_id path UUID Yes Community the data belongs to.
file_upload body (multipart) file (text/csv) Yes CSV with columns Data, Hora, Recurso, EstadoCargaBateria, comma-separated.

CSV columns:

Column Meaning
Data Date, DD/MM/YYYY.
Hora End of the 15-minute interval, HH:MM.
Recurso Name of the STORAGE resource in the community.
EstadoCargaBateria Battery charge state of the storage resource at the timestamp. The optimisers read it as the initial stored energy (kWh).

Example

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

File content (same columns as the template template_bateria.csv):

Data,Hora,Recurso,EstadoCargaBateria
01/05/2023,00:15,Recurso1,42.5
01/05/2023,00:30,Recurso1,43.1
01/05/2023,00:45,Recurso1,43.8

Response (abridged)

{
  "message": "Processing started",
  "task_id": "b1f3c0de-6f0a-4f4e-8d57-1f2c2b8f9a10"
}

Tip

  • Multipart field name is file_upload. The part must have content type text/csv (hence ;type=text/csv in curl), otherwise the call fails with 404 Invalid document type; a header that is not exactly Data,Hora,Recurso,EstadoCargaBateria (this order) fails with 403 Invalid document.
  • 201 only means the file was queued on the Celery file_uploads queue. Parsing, resource lookup and insertion happen asynchronously: poll GET /core/api/communities/{community_id}/tasks/{task_id}?group_task=false (see Communities) and read state, message and error.
  • Data is DD/MM/YYYY, Hora is HH:MM. Hora is the END of the 15-minute interval: the stored datetime_timestamp is Data Hora minus 15 minutes, interpreted in Europe/Lisbon (DST changes handled). 24:00 is not accepted by the parser; write the last interval of a day as 00:00 of the next date.
  • Recurso must equal the name of an existing STORAGE resource in the community; unknown names make the task fail with Could not find resource_id for the following ... identifiers. The matching resource must be of the correct type, since storage_id is a foreign key.
  • At most 36,000 rows per file (about one year of 15-minute data for one resource); completely empty rows are dropped.
  • Upload is an overwrite, not an append: for every (timestamp, resource) pair in the file the existing row is deleted and replaced; pairs not in the file are untouched.
  • Side effect on the local market: sessions are created (status OPEN) for timestamps that have none, and existing sessions at those timestamps are reset to OPEN with the community's current allocation-coefficient method and market rate. See Sessions and market.
  • Only the latest reading before the horizon start matters for the optimisers, so uploading a single row per battery at the current time is enough.

List Storage Battery State

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

Returns a page of stored Storage Battery State rows for the community, with the total number of matching rows and the distinct dates and times present in the filtered set. This is the endpoint behind the data tables in the web UI.

Auth / permissions: any authenticated, verified member of the community, community admin or platform admin. Admins and platform admins see every (non-deleted) resource of the community; a plain member only sees rows of resources they own.

Parameter In Type Required Description
community_id path UUID Yes Community whose data is read.
limit query integer Yes Page size (number of rows returned).
offset query integer Yes Number of rows to skip.
date query string YYYY-MM-DD No Return only rows whose timestamp falls on this calendar date.
time query string HH:MM:SS No Return only rows whose timestamp has this time of day.
resource_id query UUID No Return only rows of this STORAGE resource (storage_id).
sort_column query string No datetime_timestamp, date, time, resource_id (see tip) or the value column. Without it the order is unspecified.
sort_direction query string No asc for ascending; any other value (or omitted) sorts descending. Only used when sort_column is set.
effective_at query date YYYY-MM-DD No Only relevant for community members: the date used to resolve which resources they own (defaults to today). Admins are unaffected.

Example

curl -G https://<host>/core/api/communities/3fa85f64-5717-4562-b3fc-2c963f66afa6/storage_battery_state_loads/pagination \
  -H "Authorization: Bearer $TOKEN" \
  --data-urlencode "limit=100" \
  --data-urlencode "offset=0" \
  --data-urlencode "date=2023-05-01" \
  --data-urlencode "resource_id=7c9e6679-7425-40de-944b-e07fc1f90ae7" \
  --data-urlencode "sort_column=datetime_timestamp" \
  --data-urlencode "sort_direction=asc"

Response (abridged)

{
  "total_count": 96,
  "data": [
    {
      "datetime_timestamp": "2023-05-01T00:00:00+01:00",
      "storage_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "charge_state": 42.5,
      "community_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
    }
  ],
  "distinct_dates": [{ "date": "2023-05-01" }],
  "distinct_times": [{ "time": "00:00:00" }, { "time": "00:15:00" }]
}

Tip

  • limit and offset are required; omitting them returns 422. total_count, distinct_dates and distinct_times are computed over the whole filtered set, not just the returned page.
  • sort_column=resource_id sorts by the resource name (joined from the resources table).
  • date, time and resource_id filters combine with AND. This endpoint has no start_date / end_date range filter; filter by single date or page through the data.
  • datetime_timestamp is the start of the 15-minute interval (timezone-aware, Europe/Lisbon local offset). The row field is storage_id, not resource_id; the resource_id query parameter filters on it.
  • Returns 404 if the community does not exist and 403 if the caller is not a member of it.

Electric water heater inputs

Inputs for electric water heater (EWH) resources.

EWH Usage (ewh_usage): No energy-management module currently reads this table: the code that would pass it to the optimiser as the EWH dataset (start / duration) is commented out in energy_management/service.py, and OSTEC Simple sets the EWH dataset to None. Data is stored and can be queried, but it does not influence setpoints today.

Upload EWH Usage

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

Uploads a CSV file with the hot-water usage events of an electric water heater (duration) for one or more EWH resources. The file is processed asynchronously. Template: template_ewh_usage.csv.

Auth / permissions: community admin of the target community or platform admin. Plain community members receive 403 (Community members can only perform read operations).

Parameter In Type Required Description
community_id path UUID Yes Community the data belongs to.
file_upload body (multipart) file (text/csv) Yes CSV with columns Data, Hora, Recurso, Duracao, comma-separated.

CSV columns:

Column Meaning
Data Date, DD/MM/YYYY.
Hora End of the 15-minute interval, HH:MM.
Recurso Name of the EWH resource in the community.
Duracao Duration of the hot-water usage starting at the timestamp. The code does not define the unit; follow the unit convention of the EWH model you are feeding.

Example

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

File content (same columns as the template template_ewh_usage.csv):

Data,Hora,Recurso,Duracao
01/05/2023,00:15,Recurso1,10
01/05/2023,00:30,Recurso1,10
01/05/2023,00:45,Recurso1,1

Response (abridged)

{
  "message": "Processing started",
  "task_id": "b1f3c0de-6f0a-4f4e-8d57-1f2c2b8f9a10"
}

Tip

  • Multipart field name is file_upload. The part must have content type text/csv (hence ;type=text/csv in curl), otherwise the call fails with 404 Invalid document type; a header that is not exactly Data,Hora,Recurso,Duracao (this order) fails with 403 Invalid document.
  • 201 only means the file was queued on the Celery file_uploads queue. Parsing, resource lookup and insertion happen asynchronously: poll GET /core/api/communities/{community_id}/tasks/{task_id}?group_task=false (see Communities) and read state, message and error.
  • Data is DD/MM/YYYY, Hora is HH:MM. Hora is the END of the 15-minute interval: the stored datetime_timestamp is Data Hora minus 15 minutes, interpreted in Europe/Lisbon (DST changes handled). 24:00 is not accepted by the parser; write the last interval of a day as 00:00 of the next date.
  • Recurso must equal the name of an existing EWH resource in the community; unknown names make the task fail with Could not find resource_id for the following ... identifiers. The matching resource must be of the correct type, since ewh_id is a foreign key.
  • At most 36,000 rows per file (about one year of 15-minute data for one resource); completely empty rows are dropped.
  • Upload is an overwrite, not an append: for every (timestamp, resource) pair in the file the existing row is deleted and replaced; pairs not in the file are untouched.
  • Side effect on the local market: sessions are created (status OPEN) for timestamps that have none, and existing sessions at those timestamps are reset to OPEN with the community's current allocation-coefficient method and market rate. See Sessions and market.
  • Each row is a usage event (start = timestamp, duration = how long), not a continuous series.

List EWH Usage

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

Returns a page of stored EWH Usage rows for the community, with the total number of matching rows and the distinct dates and times present in the filtered set. This is the endpoint behind the data tables in the web UI.

Auth / permissions: any authenticated, verified member of the community, community admin or platform admin. Admins and platform admins see every (non-deleted) resource of the community; a plain member only sees rows of resources they own.

Parameter In Type Required Description
community_id path UUID Yes Community whose data is read.
limit query integer Yes Page size (number of rows returned).
offset query integer Yes Number of rows to skip.
date query string YYYY-MM-DD No Return only rows whose timestamp falls on this calendar date.
time query string HH:MM:SS No Return only rows whose timestamp has this time of day.
resource_id query UUID No Return only rows of this EWH resource (ewh_id).
sort_column query string No datetime_timestamp, date, time, resource_id (see tip) or the value column. Without it the order is unspecified.
sort_direction query string No asc for ascending; any other value (or omitted) sorts descending. Only used when sort_column is set.
effective_at query date YYYY-MM-DD No Only relevant for community members: the date used to resolve which resources they own (defaults to today). Admins are unaffected.

Example

curl -G https://<host>/core/api/communities/3fa85f64-5717-4562-b3fc-2c963f66afa6/ewh_usage/pagination \
  -H "Authorization: Bearer $TOKEN" \
  --data-urlencode "limit=100" \
  --data-urlencode "offset=0" \
  --data-urlencode "date=2023-05-01" \
  --data-urlencode "resource_id=7c9e6679-7425-40de-944b-e07fc1f90ae7" \
  --data-urlencode "sort_column=datetime_timestamp" \
  --data-urlencode "sort_direction=asc"

Response (abridged)

{
  "total_count": 96,
  "data": [
    {
      "datetime_timestamp": "2023-05-01T00:00:00+01:00",
      "ewh_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "duration": 10.0,
      "community_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
    }
  ],
  "distinct_dates": [{ "date": "2023-05-01" }],
  "distinct_times": [{ "time": "00:00:00" }, { "time": "00:15:00" }]
}

Tip

  • limit and offset are required; omitting them returns 422. total_count, distinct_dates and distinct_times are computed over the whole filtered set, not just the returned page.
  • sort_column=resource_id is unreliable on this endpoint: the code joins .resource on the load model, which is not defined there, so expect a server error (500). Sort by datetime_timestamp, date or time instead.
  • date, time and resource_id filters combine with AND. This endpoint has no start_date / end_date range filter; filter by single date or page through the data.
  • datetime_timestamp is the start of the 15-minute interval (timezone-aware, Europe/Lisbon local offset). The row field is ewh_id, not resource_id; the resource_id query parameter filters on it.
  • Returns 404 if the community does not exist and 403 if the caller is not a member of it.

Heat pump inputs

Inputs for heat pump (HP) resources: forecast hot-water demand and outside temperature. Both are accepted as JSON records (programmatic use) or as CSV files. No energy-management module reads these tables yet; they are stored for the heat-pump models. Unlike the other datasets, the JSON endpoint is the primary one and the CSV endpoint is a hidden alternative.

Upload Heat Pump Water Mass Usage Forecast (JSON)

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

Uploads the forecast mass of hot water demanded from a heat pump (mass_value, kg) as a JSON array of records, for programmatic integrations. The records are processed asynchronously. The CSV equivalent is Upload Heat Pump Water Mass Usage Forecast (CSV).

Auth / permissions: community admin of the target community or platform admin. Plain community members receive 403.

Parameter In Type Required Description
community_id path UUID Yes Community the data belongs to.
(body) body array of records Yes Non-empty JSON array.
[].datetime_timestamp body datetime (ISO 8601) Yes Start of the interval. Include a UTC offset; a value without one is treated as UTC.
[].hp_id body UUID Yes Id of the heat pump resource (foreign key to hps.id). Note: this is the resource id, not its name.
[].mass_value body number No Forecast hot-water demand (mass in kg) in the interval. This is a forecast, not a historical record.

Example

curl -X POST https://<host>/core/api/communities/3fa85f64-5717-4562-b3fc-2c963f66afa6/water_mass_usage_forecast \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '[
    { "datetime_timestamp": "2023-05-01T00:00:00+01:00", "hp_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "mass_value": 12.5 },
    { "datetime_timestamp": "2023-05-01T00:15:00+01:00", "hp_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "mass_value": 12.5 }
  ]'

Response (abridged)

{
  "message": "Processing started",
  "task_id": "b1f3c0de-6f0a-4f4e-8d57-1f2c2b8f9a10"
}

Tip

  • An empty array returns 400 No records provided.; a malformed body returns 422.
  • datetime_timestamp is stored as given (converted to UTC): unlike the CSV upload there is no Europe/Lisbon conversion and no 15-minute shift, so send the real interval start.
  • 201 only means the task was queued. Poll GET /core/api/communities/{community_id}/tasks/{task_id}?group_task=false (see Communities); the task fails if a hp_id does not exist (foreign key).
  • Upsert semantics: existing rows for the same (community, timestamp, hp_id) are deleted and replaced; other rows are untouched.
  • Unlike the CSV upload, this endpoint does not create or reopen market sessions.
  • There is no row limit in the code for this endpoint; send reasonable batch sizes.

Upload Heat Pump Water Mass Usage Forecast (CSV)

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

Uploads a CSV file with the forecast mass of hot water demanded from a heat pump (mass_value, kg). Same asynchronous processing as the JSON endpoint, but resources are referenced by name. Template: template_hp_water_mass_usage_forecast.csv.

Warning

This route is declared with include_in_schema=False: it works, but it is not listed in the OpenAPI schema or Swagger UI.

Auth / permissions: community admin of the target community or platform admin. Plain community members receive 403.

Parameter In Type Required Description
community_id path UUID Yes Community the data belongs to.
file_upload body (multipart) file (text/csv) Yes CSV with columns Data, Hora, Recurso, Massa_Agua, comma-separated.

Example

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

File content (same columns as the template template_hp_water_mass_usage_forecast.csv):

Data,Hora,Recurso,Massa_Agua
01/05/2023,00:15,Recurso1,10
01/05/2023,00:30,Recurso1,10
01/05/2023,00:45,Recurso1,1

Response (abridged)

{
  "message": "Processing started",
  "task_id": "b1f3c0de-6f0a-4f4e-8d57-1f2c2b8f9a10"
}

Tip

  • Multipart field name is file_upload. The part must have content type text/csv (hence ;type=text/csv in curl), otherwise the call fails with 404 Invalid document type; a header that is not exactly Data,Hora,Recurso,Massa_Agua (this order) fails with 403 Invalid document.
  • 201 only means the file was queued on the Celery file_uploads queue. Parsing, resource lookup and insertion happen asynchronously: poll GET /core/api/communities/{community_id}/tasks/{task_id}?group_task=false (see Communities) and read state, message and error.
  • Data is DD/MM/YYYY, Hora is HH:MM. Hora is the END of the 15-minute interval: the stored datetime_timestamp is Data Hora minus 15 minutes, interpreted in Europe/Lisbon (DST changes handled). 24:00 is not accepted by the parser; write the last interval of a day as 00:00 of the next date.
  • Recurso must equal the name of an existing HP resource in the community; unknown names make the task fail with Could not find resource_id for the following ... identifiers. The matching resource must be of the correct type, since hp_id is a foreign key.
  • At most 36,000 rows per file (about one year of 15-minute data for one resource); completely empty rows are dropped.
  • Upload is an overwrite, not an append: for every (timestamp, resource) pair in the file the existing row is deleted and replaced; pairs not in the file are untouched.
  • Side effect on the local market: sessions are created (status OPEN) for timestamps that have none, and existing sessions at those timestamps are reset to OPEN with the community's current allocation-coefficient method and market rate. See Sessions and market.

List Heat Pump Water Mass Usage Forecast

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

Returns a page of stored Heat Pump Water Mass Usage Forecast rows for the community, with the total number of matching rows and the distinct dates and times present in the filtered set. This is the endpoint behind the data tables in the web UI.

Auth / permissions: any authenticated, verified member of the community, community admin or platform admin. Admins and platform admins see every (non-deleted) resource of the community; a plain member only sees rows of resources they own.

Parameter In Type Required Description
community_id path UUID Yes Community whose data is read.
limit query integer Yes Page size (number of rows returned).
offset query integer Yes Number of rows to skip.
date query string YYYY-MM-DD No Return only rows whose timestamp falls on this calendar date.
time query string HH:MM:SS No Return only rows whose timestamp has this time of day.
resource_id query UUID No Return only rows of this HP resource (hp_id).
sort_column query string No datetime_timestamp, date, time, resource_id (see tip) or the value column. Without it the order is unspecified.
sort_direction query string No asc for ascending; any other value (or omitted) sorts descending. Only used when sort_column is set.
effective_at query date YYYY-MM-DD No Only relevant for community members: the date used to resolve which resources they own (defaults to today). Admins are unaffected.

Example

curl -G https://<host>/core/api/communities/3fa85f64-5717-4562-b3fc-2c963f66afa6/water_mass_usage_forecast/pagination \
  -H "Authorization: Bearer $TOKEN" \
  --data-urlencode "limit=100" \
  --data-urlencode "offset=0" \
  --data-urlencode "date=2023-05-01" \
  --data-urlencode "resource_id=7c9e6679-7425-40de-944b-e07fc1f90ae7" \
  --data-urlencode "sort_column=datetime_timestamp" \
  --data-urlencode "sort_direction=asc"

Response (abridged)

{
  "total_count": 96,
  "data": [
    {
      "datetime_timestamp": "2023-05-01T00:00:00+01:00",
      "hp_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "mass_value": 12.5,
      "community_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
    }
  ],
  "distinct_dates": [{ "date": "2023-05-01" }],
  "distinct_times": [{ "time": "00:00:00" }, { "time": "00:15:00" }]
}

Tip

  • limit and offset are required; omitting them returns 422. total_count, distinct_dates and distinct_times are computed over the whole filtered set, not just the returned page.
  • sort_column=resource_id is unreliable on this endpoint: the code orders by the resource name but joins the heat-pump table, not the resource table, so the ordering and row count can be wrong. Prefer datetime_timestamp, date or time.
  • date, time and resource_id filters combine with AND. This endpoint has no start_date / end_date range filter; filter by single date or page through the data.
  • datetime_timestamp is the start of the 15-minute interval (timezone-aware, Europe/Lisbon local offset). The row field is hp_id, not resource_id; the resource_id query parameter filters on it.
  • Returns 404 if the community does not exist and 403 if the caller is not a member of it.

Upload Heat Pump Outside Temperature (JSON)

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

Uploads the outside temperature associated with a heat pump (temperature, degrees Celsius) as a JSON array of records, for programmatic integrations. The records are processed asynchronously. The CSV equivalent is Upload Heat Pump Outside Temperature (CSV).

Auth / permissions: community admin of the target community or platform admin. Plain community members receive 403.

Parameter In Type Required Description
community_id path UUID Yes Community the data belongs to.
(body) body array of records Yes Non-empty JSON array.
[].datetime_timestamp body datetime (ISO 8601) Yes Start of the interval. Include a UTC offset; a value without one is treated as UTC.
[].hp_id body UUID Yes Id of the heat pump resource (foreign key to hps.id). Note: this is the resource id, not its name.
[].temperature body number No Outside temperature (degrees Celsius) used as an abstract parameter for the heat pump; it is not tied to the geographic position of the heat pump.

Example

curl -X POST https://<host>/core/api/communities/3fa85f64-5717-4562-b3fc-2c963f66afa6/outside_temp_loads \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '[
    { "datetime_timestamp": "2023-05-01T00:00:00+01:00", "hp_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "temperature": 14.3 },
    { "datetime_timestamp": "2023-05-01T00:15:00+01:00", "hp_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "temperature": 14.3 }
  ]'

Response (abridged)

{
  "message": "Processing started",
  "task_id": "b1f3c0de-6f0a-4f4e-8d57-1f2c2b8f9a10"
}

Tip

  • An empty array returns 400 No records provided.; a malformed body returns 422.
  • datetime_timestamp is stored as given (converted to UTC): unlike the CSV upload there is no Europe/Lisbon conversion and no 15-minute shift, so send the real interval start.
  • 201 only means the task was queued. Poll GET /core/api/communities/{community_id}/tasks/{task_id}?group_task=false (see Communities); the task fails if a hp_id does not exist (foreign key).
  • Upsert semantics: existing rows for the same (community, timestamp, hp_id) are deleted and replaced; other rows are untouched.
  • Unlike the CSV upload, this endpoint does not create or reopen market sessions.
  • There is no row limit in the code for this endpoint; send reasonable batch sizes.

Upload Heat Pump Outside Temperature (CSV)

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

Uploads a CSV file with the outside temperature associated with a heat pump (temperature, degrees Celsius). Same asynchronous processing as the JSON endpoint, but resources are referenced by name. Template: template_hp_outside_temperature.csv.

Warning

This route is declared with include_in_schema=False: it works, but it is not listed in the OpenAPI schema or Swagger UI.

Auth / permissions: community admin of the target community or platform admin. Plain community members receive 403.

Parameter In Type Required Description
community_id path UUID Yes Community the data belongs to.
file_upload body (multipart) file (text/csv) Yes CSV with columns Data, Hora, Recurso, Temperatura, comma-separated.

Example

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

File content (same columns as the template template_hp_outside_temperature.csv):

Data,Hora,Recurso,Temperatura
01/05/2023,00:15,Recurso1,10
01/05/2023,00:30,Recurso1,10
01/05/2023,00:45,Recurso1,1

Response (abridged)

{
  "message": "Processing started",
  "task_id": "b1f3c0de-6f0a-4f4e-8d57-1f2c2b8f9a10"
}

Tip

  • Multipart field name is file_upload. The part must have content type text/csv (hence ;type=text/csv in curl), otherwise the call fails with 404 Invalid document type; a header that is not exactly Data,Hora,Recurso,Temperatura (this order) fails with 403 Invalid document.
  • 201 only means the file was queued on the Celery file_uploads queue. Parsing, resource lookup and insertion happen asynchronously: poll GET /core/api/communities/{community_id}/tasks/{task_id}?group_task=false (see Communities) and read state, message and error.
  • Data is DD/MM/YYYY, Hora is HH:MM. Hora is the END of the 15-minute interval: the stored datetime_timestamp is Data Hora minus 15 minutes, interpreted in Europe/Lisbon (DST changes handled). 24:00 is not accepted by the parser; write the last interval of a day as 00:00 of the next date.
  • Recurso must equal the name of an existing HP resource in the community; unknown names make the task fail with Could not find resource_id for the following ... identifiers. The matching resource must be of the correct type, since hp_id is a foreign key.
  • At most 36,000 rows per file (about one year of 15-minute data for one resource); completely empty rows are dropped.
  • Upload is an overwrite, not an append: for every (timestamp, resource) pair in the file the existing row is deleted and replaced; pairs not in the file are untouched.
  • Side effect on the local market: sessions are created (status OPEN) for timestamps that have none, and existing sessions at those timestamps are reset to OPEN with the community's current allocation-coefficient method and market rate. See Sessions and market.

List Heat Pump Outside Temperature

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

Returns a page of stored Heat Pump Outside Temperature rows for the community, with the total number of matching rows and the distinct dates and times present in the filtered set. This is the endpoint behind the data tables in the web UI.

Auth / permissions: any authenticated, verified member of the community, community admin or platform admin. Admins and platform admins see every (non-deleted) resource of the community; a plain member only sees rows of resources they own.

Parameter In Type Required Description
community_id path UUID Yes Community whose data is read.
limit query integer Yes Page size (number of rows returned).
offset query integer Yes Number of rows to skip.
date query string YYYY-MM-DD No Return only rows whose timestamp falls on this calendar date.
time query string HH:MM:SS No Return only rows whose timestamp has this time of day.
resource_id query UUID No Return only rows of this HP resource (hp_id).
sort_column query string No datetime_timestamp, date, time, resource_id (see tip) or the value column. Without it the order is unspecified.
sort_direction query string No asc for ascending; any other value (or omitted) sorts descending. Only used when sort_column is set.
effective_at query date YYYY-MM-DD No Only relevant for community members: the date used to resolve which resources they own (defaults to today). Admins are unaffected.

Example

curl -G https://<host>/core/api/communities/3fa85f64-5717-4562-b3fc-2c963f66afa6/outside_temp_loads/pagination \
  -H "Authorization: Bearer $TOKEN" \
  --data-urlencode "limit=100" \
  --data-urlencode "offset=0" \
  --data-urlencode "date=2023-05-01" \
  --data-urlencode "resource_id=7c9e6679-7425-40de-944b-e07fc1f90ae7" \
  --data-urlencode "sort_column=datetime_timestamp" \
  --data-urlencode "sort_direction=asc"

Response (abridged)

{
  "total_count": 96,
  "data": [
    {
      "datetime_timestamp": "2023-05-01T00:00:00+01:00",
      "hp_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "temperature": 14.3,
      "community_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
    }
  ],
  "distinct_dates": [{ "date": "2023-05-01" }],
  "distinct_times": [{ "time": "00:00:00" }, { "time": "00:15:00" }]
}

Tip

  • limit and offset are required; omitting them returns 422. total_count, distinct_dates and distinct_times are computed over the whole filtered set, not just the returned page.
  • sort_column=resource_id is unreliable on this endpoint: the code orders by the resource name but joins the heat-pump table, not the resource table, so the ordering and row count can be wrong. Prefer datetime_timestamp, date or time.
  • date, time and resource_id filters combine with AND. This endpoint has no start_date / end_date range filter; filter by single date or page through the data.
  • datetime_timestamp is the start of the 15-minute interval (timezone-aware, Europe/Lisbon local offset). The row field is hp_id, not resource_id; the resource_id query parameter filters on it.
  • Returns 404 if the community does not exist and 403 if the caller is not a member of it.