flexmeasures.api.v3_0.assets

Functions

flexmeasures.api.v3_0.assets.get_accessible_accounts() → list[Account]

Classes

class flexmeasures.api.v3_0.assets.AssetAPI

This API view exposes generic assets.

asset_sensors(id: int, asset: GenericAsset | None, page: int | None = None, per_page: int | None = None, filter: list[str] | None = None, sort_by: str | None = None, sort_dir: str | None = None)

List all sensors under an asset.

This endpoint returns all sensors under an asset.

The endpoint supports pagination of the asset list using the page and per_page query parameters.

  • If the page parameter is not provided, all sensors are returned, without pagination information. The result will be a list of sensors.

  • If a page parameter is provided, the response will be paginated, showing a specific number of assets per page as defined by per_page (default is 10).

The response schema for pagination is inspired by https://datatables.net/manual/server-side#Returned-data

Example response

An example of one asset being returned in a paginated response:

{
    "data" : [
        {
          "id": 1,
          "name": "Test battery",
          "latitude": 10,
          "longitude": 100,
          "account_id": 2,
          "generic_asset_type": {"id": 1, "name": "battery"}
        }
    ],
    "num-records" : 1,
    "filtered-records" : 1

}

If no pagination is requested, the response only consists of the list under the “data” key.

Reqheader Authorization:

The authentication token

Reqheader Content-Type:

application/json

Resheader Content-Type:

application/json

Status 200:

PROCESSED

Status 400:

INVALID_REQUEST

Status 401:

UNAUTHORIZED

Status 403:

INVALID_SENDER

Status 422:

UNPROCESSABLE_ENTITY

auditlog(id: int, asset: GenericAsset, page: int | None = None, per_page: int | None = None, filter: list[str] | None = None, sort_by: str | None = None, sort_dir: str | None = None)

API endpoint to get history of asset related actions.

The endpoint is paginated and supports search filters.

  • If the page parameter is not provided, all audit logs are returned paginated by per_page (default is 10).

  • If a page parameter is provided, the response will be paginated, showing a specific number of assets per page as defined by per_page (default is 10).

  • If sort_by (field name) and sort_dir (“asc” or “desc”) are provided, the list will be sorted.

  • If a search ‘filter’ is provided, the response will filter out audit logs where each search term is either present in the event or active user name. The response schema for pagination is inspired by https://datatables.net/manual/server-side

Example response

Reqheader Authorization:

The authentication token

Reqheader Content-Type:

application/json

Resheader Content-Type:

application/json

Status 200:

PROCESSED

Status 400:

INVALID_REQUEST, REQUIRED_INFO_MISSING, UNEXPECTED_PARAMS

Status 401:

UNAUTHORIZED

Status 403:

INVALID_SENDER

Status 422:

UNPROCESSABLE_ENTITY

delete(id: int, asset: GenericAsset)

Delete an asset given its identifier.

This endpoint deletes an existing asset, as well as all sensors and measurements recorded for it.

Reqheader Authorization:

The authentication token

Reqheader Content-Type:

application/json

Resheader Content-Type:

application/json

Status 204:

DELETED

Status 400:

INVALID_REQUEST, REQUIRED_INFO_MISSING, UNEXPECTED_PARAMS

Status 401:

UNAUTHORIZED

Status 403:

INVALID_SENDER

Status 422:

UNPROCESSABLE_ENTITY

fetch_one(id, asset)

Fetch a given asset.

This endpoint gets an asset.

Example response

{
    "generic_asset_type_id": 2,
    "name": "Test battery",
    "id": 1,
    "latitude": 10,
    "longitude": 100,
    "account_id": 1,
}
Reqheader Authorization:

The authentication token

Reqheader Content-Type:

application/json

Resheader Content-Type:

application/json

Status 200:

PROCESSED

Status 400:

INVALID_REQUEST, REQUIRED_INFO_MISSING, UNEXPECTED_PARAMS

Status 401:

UNAUTHORIZED

Status 403:

INVALID_SENDER

Status 422:

UNPROCESSABLE_ENTITY

get_chart(id: int, asset: GenericAsset, **kwargs)

GET from /assets/<id>/chart

get_chart_data(id: int, asset: GenericAsset, **kwargs)

GET from /assets/<id>/chart_data

Data for use in charts (in case you have the chart specs already).

get_jobs(id: int, asset: GenericAsset)

API endpoint to get all jobs of an asset.

The response will be a list of jobs. Note that jobs in Redis have a limited TTL, so not all past jobs will be listed.

Example response

Reqheader Authorization:

The authentication token

Reqheader Content-Type:

application/json

Resheader Content-Type:

application/json

Status 200:

PROCESSED

Status 400:

INVALID_REQUEST, REQUIRED_INFO_MISSING, UNEXPECTED_PARAMS

Status 401:

UNAUTHORIZED

Status 403:

INVALID_SENDER

Status 422:

UNPROCESSABLE_ENTITY

get_kpis(id: int, asset: GenericAsset, start, end)

API endpoint to get KPIs for an asset.

Gets statistics for sensors for the given time range. The sensors are expected to have a daily resolution, suitable for KPIs. Each sensor has a preferred function to downsample the daily values to the KPI value.

Example request

{
    "start": "2015-06-02T10:00:00+00:00",
    "end": "2015-06-02T12:00:00+00:00"
}

Example response

{
    "data": [
        {
            "sensor": 145046,
            "title": "My KPI",
            "unit": "MW",
            "downsample_value": 0,
            "downsample_function": "sum",
        },
        {
            "sensor": 141053,
            "title": "Raw PowerKPI",
            "unit": "kW",
            "downsample_value": 816.67,
            "downsample_function": "sum",
        }
    ]
}

This endpoint returns a list of kpis for the asset.

Reqheader Authorization:

The authentication token

Reqheader Content-Type:

application/json

Resheader Content-Type:

application/json

Status 200:

PROCESSED

Status 400:

INVALID_DATA

Status 401:

UNAUTHORIZED

Status 403:

INVALID_SENDER

Status 405:

INVALID_METHOD

Status 422:

UNPROCESSABLE_ENTITY

index(account: Account | None, all_accessible: bool, include_public: bool, page: int | None = None, per_page: int | None = None, filter: list[str] | None = None, sort_by: str | None = None, sort_dir: str | None = None)

List all assets owned by user’s accounts, or a certain account or all accessible accounts.

This endpoint returns all accessible assets by accounts. The account_id query parameter can be used to list assets from any account (if the user is allowed to read them). Per default, the user’s account is used. Alternatively, the all_accessible query parameter can be used to list assets from all accounts the current_user has read-access to, plus all public assets. Defaults to false. The include_public query parameter can be used to include public assets in the response. Defaults to false.

The endpoint supports pagination of the asset list using the page and per_page query parameters.

  • If the page parameter is not provided, all assets are returned, without pagination information. The result will be a list of assets.

  • If a page parameter is provided, the response will be paginated, showing a specific number of assets per page as defined by per_page (default is 10).

  • If a search ‘filter’ such as ‘solar “ACME corp”’ is provided, the response will filter out assets where each search term is either present in their name or account name. The response schema for pagination is inspired by https://datatables.net/manual/server-side#Returned-data

Example response

An example of one asset being returned in a paginated response:

{
    "data" : [
        {
          "id": 1,
          "name": "Test battery",
          "latitude": 10,
          "longitude": 100,
          "account_id": 2,
          "generic_asset_type": {"id": 1, "name": "battery"}
        }
    ],
    "num-records" : 1,
    "filtered-records" : 1

}

If no pagination is requested, the response only consists of the list under the “data” key.

Reqheader Authorization:

The authentication token

Reqheader Content-Type:

application/json

Resheader Content-Type:

application/json

Status 200:

PROCESSED

Status 400:

INVALID_REQUEST

Status 401:

UNAUTHORIZED

Status 403:

INVALID_SENDER

Status 422:

UNPROCESSABLE_ENTITY

patch(asset_data: dict, id: int, db_asset: GenericAsset)

Update an asset given its identifier.

This endpoint sets data for an existing asset. Any subset of asset fields can be sent.

The following fields are not allowed to be updated: - id - account_id

Example request

{
    "latitude": 11.1,
    "longitude": 99.9,
}

Example response

The whole asset is returned in the response:

{
    "generic_asset_type_id": 2,
    "id": 1,
    "latitude": 11.1,
    "longitude": 99.9,
    "name": "Test battery",
    "account_id": 2,
}
Reqheader Authorization:

The authentication token

Reqheader Content-Type:

application/json

Resheader Content-Type:

application/json

Status 200:

UPDATED

Status 400:

INVALID_REQUEST, REQUIRED_INFO_MISSING, UNEXPECTED_PARAMS

Status 401:

UNAUTHORIZED

Status 403:

INVALID_SENDER

Status 422:

UNPROCESSABLE_ENTITY

post(asset_data: dict)

Create new asset.

This endpoint creates a new asset.

Example request A

{
    "name": "Test battery",
    "generic_asset_type_id": 2,
    "account_id": 2,
    "latitude": 40,
    "longitude": 170.3,
}

The newly posted asset is returned in the response.

Example request B

Alternatively, set the parent_asset_id to make the new asset a child of another asset. For example, to set asset 10 as its parent:

{
    "name": "Test battery",
    "generic_asset_type_id": 2,
    "account_id": 2,
    "parent_asset_id": 10,
    "latitude": 40,
    "longitude": 170.3,
}
Reqheader Authorization:

The authentication token

Reqheader Content-Type:

application/json

Resheader Content-Type:

application/json

Status 201:

CREATED

Status 400:

INVALID_REQUEST

Status 401:

UNAUTHORIZED

Status 403:

INVALID_SENDER

Status 422:

UNPROCESSABLE_ENTITY

public()

Return all public assets.

This endpoint returns all public assets.

Reqheader Authorization:

The authentication token

Reqheader Content-Type:

application/json

Resheader Content-Type:

application/json

Status 200:

PROCESSED

Status 400:

INVALID_REQUEST

Status 401:

UNAUTHORIZED

Status 422:

UNPROCESSABLE_ENTITY

trigger_schedule(asset: GenericAsset, start_of_schedule: datetime, duration: timedelta, belief_time: datetime | None = None, flex_model: dict | None = None, flex_context: dict | None = None, sequential: bool = False, **kwargs)

Trigger FlexMeasures to create a schedule for a collection of flexible and inflexible devices.

Trigger FlexMeasures to create a schedule for this asset. The flex-model references the power sensors of flexible devices, which must belong to the given asset, either directly or indirectly, by being assigned to one of the asset’s (grand)children.

In this request, you can describe:

  • the schedule’s main features (when does it start, what unit should it report, prior to what time can we assume knowledge)

  • the flexibility models for the asset’s relevant sensors (state and constraint variables, e.g. current state of charge of a battery, or connection capacity)

  • the flexibility context which the asset operates in (other sensors under the same EMS which are relevant, e.g. prices)

For details on flexibility model and context, see Describing flexibility. Below, we’ll also list some examples.

Note

This endpoint supports scheduling an EMS with multiple flexible devices at once. It can do so jointly (the default) or sequentially (considering previously scheduled sensors as inflexible). To use sequential scheduling, use sequential=true in the JSON body.

The length of the schedule can be set explicitly through the ‘duration’ field. Otherwise, it is set by the config setting FLEXMEASURES_PLANNING_HORIZON, which defaults to 48 hours. If the flex-model contains targets that lie beyond the planning horizon, the length of the schedule is extended to accommodate them. Finally, the schedule length is limited by max_planning_horizon_config, which defaults to 2520 steps of each sensor’s resolution. Targets that exceed the max planning horizon are not accepted.

The appropriate algorithm is chosen by FlexMeasures (based on asset type). It’s also possible to use custom schedulers and custom flexibility models, see Plugin Customization.

If you have ideas for algorithms that should be part of FlexMeasures, let us know: https://flexmeasures.io/get-in-touch/

Example request

This message triggers a schedule for a storage asset (with power sensor 931), starting at 10.00am, when the state of charge (soc) should be assumed to be 12.1 kWh, and also schedules a curtailable production asset (with power sensor 932), whose production forecasts are recorded under sensor 760.

Aggregate consumption (of all devices within this EMS) should be priced by sensor 9, and aggregate production should be priced by sensor 10, where the aggregate power flow in the EMS is described by the sum over sensors 13, 14, 15, and the two power sensors (931 and 932) of the flexible devices being optimized (referenced in the flex-model).

The battery consumption power capacity is limited by sensor 42 and the production capacity is constant (30 kW). Finally, the site consumption capacity is limited by sensor 32.

{
    "start": "2015-06-02T10:00:00+00:00",
    "flex-model": [
        {
            "sensor": 931,
            "soc-at-start": 12.1,
            "soc-unit": "kWh",
            "power-capacity": "25kW",
            "consumption-capacity" : {"sensor": 42},
            "production-capacity" : "30 kW"
        },
        {
            "sensor": 932,
            "consumption-capacity": "0 kW",
            "production-capacity": {"sensor": 760},
        }
    ],
    "flex-context": {
        "consumption-price-sensor": 9,
        "production-price-sensor": 10,
        "inflexible-device-sensors": [13, 14, 15],
        "site-power-capacity": "100kW",
        "site-production-capacity": "80kW",
        "site-consumption-capacity": {"sensor": 32}
    }
}

Example response

This message indicates that the scheduling request has been processed without any error. A scheduling job has been created with some Universally Unique Identifier (UUID), which will be picked up by a worker. The given UUID may be used to obtain the resulting schedule for each flexible device: see /sensors/<id>/schedules/<uuid>.

{
    "status": "PROCESSED",
    "schedule": "364bfd06-c1fa-430b-8d25-8f5a547651fb",
    "message": "Request has been processed."
}
Reqheader Authorization:

The authentication token

Reqheader Content-Type:

application/json

Resheader Content-Type:

application/json

Status 200:

PROCESSED

Status 400:

INVALID_DATA

Status 401:

UNAUTHORIZED

Status 403:

INVALID_SENDER

Status 405:

INVALID_METHOD

Status 422:

UNPROCESSABLE_ENTITY

update_default_asset_view(**kwargs)

Update the default asset view for the current user session.

Example request

{
    "default_asset_view": "Graphs",
    "use_as_default": true
}

Example response

This endpoint sets the default asset view for the current user session if use_as_default is true. If use_as_default is false, it clears the session variable for the default asset view.

Reqheader Authorization:

The authentication token

Reqheader Content-Type:

application/json

Resheader Content-Type:

application/json

Status 200:

PROCESSED

Status 400:

INVALID_REQUEST, REQUIRED_INFO_MISSING, UNEXPECTED_PARAMS

Status 401:

UNAUTHORIZED

Status 403:

INVALID_SENDER

Status 422:

UNPROCESSABLE_ENTITY