Skip to content

Latest commit

 

History

History
375 lines (308 loc) · 26.5 KB

README.rst

File metadata and controls

375 lines (308 loc) · 26.5 KB
Raw

BEMServer API client

Latest version Python versions Build status pre-commit.ci status Code coverage

BEMServer is a free Building Energy Management software platform.

Its purpose is to store data collected in buildings and produce useful information such as performance indicators or alerts.

This package is a client for BEMServer API, based on requests.

API client usage

from bemserver_api_client import BEMServerApiClient

# Get an instance of API client, setting the API host and the authentication method used for API requests.
api_client = BEMServerApiClient(
    "localhost:5000",
    authentication_method=BEMServerApiClient.make_http_basic(
        "[email protected]", "password"
    ),
)

Entry points

API resources are accessible through dedicated entry points (python attributes) in API client instance.

For example, /sites/ resources are requestable using the sites attribute but /energy_consumption_timeseries_by_sites/ can be requested using energy_cons_ts_by_sites (which name is a little shorter than the original).

# Get a list of all the sites available for the authenticated user.
sites_resp = api_client.sites.getall()

Most of the API client entry points has common functions (CF) to request the API endpoints (actions on resources):

  • getall to GET a list of resources

  • getone to GET one specific resource (by its ID)

  • create to POST a new resource

  • update to UPDATE one specific resource

  • delete to DELETE one specific resource

    Pay attention that, as described in the API documentation, some actions are not available on certain API resources (see /timeseries_data/). Other API resources have additional actions, like on sites where it is possible to call get_degree_days and download_weather_data functions.

The tables below shows the correspondance between API endpoint uris and API client entry points with their available functions.

CF mentions that the entry point described implements all common functions (getall, getone, create, update, delete). CF - update means that all common functions are implemented less the update one.

Authentication

API resources API client entry points API client entry point actions
/auth/ auth get_tokens, refresh_tokens

General

API resources API client entry points API client entry point actions
/about/ about getall
/users/ users CF, set_admin, set_active
/users_by_user_groups/ user_by_user_groups CF - update
/user_groups/ user_groups CF
/user_groups_by_campaigns/ user_groups_by_campaigns CF - update
/user_groups_by_campaign_scopes/ user_groups_by_campaign_scopes CF - update
/campaigns/ campaigns CF
/campaign_scopes/ campaign_scopes CF
/io/ io upload_sites_csv, upload_timeseries_csv

Structural elements

API resources API client entry points API client entry point actions
/sites/ sites CF, download_weather_data, get_degree_days
/buildings/ buildings CF
/storeys/ storeys CF
/spaces/ spaces CF
/zones/ zones CF
/structural_element_properties/ structural_element_properties CF
/site_properties/ site_properties CF - update
/site_property_data/ site_property_data CF
/building_properties/ building_properties CF - update
/building_property_data/ building_property_data CF
/storey_properties/ storey_properties CF - update
/storey_property_data/ storey_property_data CF
/space_properties/ space_properties CF - update
/space_property_data/ space_property_data CF
/zone_properties/ zone_properties CF - update
/zone_property_data/ zone_property_data CF

Timeseries

API resources API client entry points API client entry point actions
/timeseries/ timeseries CF
/timeseries_properties/ timeseries_properties CF
/timeseries_property_data/ timeseries_property_data CF
/timeseries_by_sites/ timeseries_by_sites CF - update
/timeseries_by_buildings/ timeseries_by_buildings CF - update
/timeseries_by_storeys/ timeseries_by_storeys CF - update
/timeseries_by_spaces/ timeseries_by_spaces CF - update
/timeseries_by_zones/ timeseries_by_zones CF - update
/timeseries_by_events/ timeseries_by_events CF - update
/weather_timeseries_by_sites/ weather_ts_by_sites CF

Timeseries data

API resources API client entry points API client entry point actions
/timeseries_data_states/ timeseries_datastates CF
/timeseries_data/ timeseries_data delete, delete_by_names, get_stats, upload, upload_by_names, download, download_by_names, download_aggregate, download_aggregate_by_names

Analysis

API resources API client entry points API client entry point actions
/analysis/ analysis get_completeness, get_energy_consumption_breakdown
/energies/ energies getall
/energy_end_uses/ energy_end_uses getall
/energy_consumption_timeseries_by_sites/ energy_cons_ts_by_sites CF
/energy_consumption_timeseries_by_buildings/ energy_cons_ts_by_buildings CF
/energy_production_technologies/ energy_prod_technologies getall
/energy_production_timeseries_by_sites/ energy_prod_ts_by_sites CF
/energy_production_timeseries_by_buildings/ energy_prod_ts_by_buildings CF

Events and notifications

API resources API client entry points API client entry point actions
/events/ events CF
/events_by_sites/ event_by_sites CF - update
/events_by_buildings/ event_by_buildings CF - update
/events_by_storeys/ event_by_storeys CF - update
/events_by_spaces/ event_by_spaces CF - update
/events_by_zones/ event_by_zones CF - update
/event_categories/ event_categories CF
/event_categories_by_users/ event_categories_by_users CF
/notifications/ notifications CF, count_by_campaign, mark_all_as_read

Services

API resources API client entry points API client entry point actions
/st_cleanups_by_campaigns/ st_cleanup_by_campaign CF, get_full
/st_cleanups_by_timeseries/ st_cleanup_by_timeseries create, update, delete, get_full
/st_check_missings_by_campaigns/ st_check_missing_by_campaign CF, get_full
/st_check_outliers_by_campaigns/ st_check_outlier_by_campaign CF, get_full
/st_download_weather_data_by_sites/ st_download_weather_by_site CF, get_full
/st_download_weather_forecast_data_by_sites/ st_download_weather_forecast_by_site CF, get_full

Usage example

Remember to rely on API documentation, as it fully describes all API endpoints: query arguments required, data format in payloads and responses content (status codes, data format...).
import datetime as dt

from bemserver_api_client import BEMServerApiClient
from bemserver_api_client.enums import DegreeDaysPeriod
from bemserver_api_client.exceptions import (
    BEMServerAPINotFoundError,
    BEMServerAPIValidationError,
)

# Get an instance of API client, setting the API host.
api_client = BEMServerApiClient("localhost:5000")

# Get the authentication bearer access and refresh tokens (JWT).
auth_resp = api_client.auth.get_tokens("[email protected]", "password")
if auth_resp.data["status"] == "failure":
    # User could not be authenticated (no access/refresh tokens are returned).
    # Raise exception, ...
    pass
# At this point (auth_resp.data["status"] == "success"), the user is authenticated.
#  auth_resp.data contains access and refresh tokens:
#  {
#      "status": "success",
#      "access_token": "...",
#      "refresh_token": "..."
#  }

# Set authentication method (bearer token authentication) in API client instance,
#  in order to call private API endpoints.
api_client.set_authentication_method(
    BEMServerApiClient.make_bearer_token_auth(
        auth_resp.data["access_token"], auth_resp.data["refresh_token"]
    )
)

# NOTE: When expired access token is automatically refreshed inside API client
#  and requests goes on. Else `BEMServerAPIAuthenticationError` is raised and
#  a new authentication is needed to continue calling private API endpoints.

# Get a list of all the sites available (for the authenticated user).
sites_resp = api_client.sites.getall()
# sites_resp is an instance of `BEMServerApiClientResponse` class,
#  which has processed yet API response data
# sites_resp.data contains sites list:
#  [
#      {
#          "id": 0,
#          "name": "A",
#          "latitude": -90,
#          "longitude": -180,
#          "description": "AAAAAA",
#          "ifc_id": "AAAAAA",
#          "campaign_id": 0
#      }
#  ]

# Get the heating degree days data of a specific site.
dd_resp = api_client.sites.get_degree_days(
    1,
    dt.date(2024, 1, 1).isoformat(),
    dt.date(2025, 1, 1).isoformat(),
    period=DegreeDaysPeriod.month,
)
# dd_resp.data contains:
#  {
#      "degree_days": {
#          "2024-01-01T00:00:00+01:00": 76.05166666666668,
#          "2024-02-01T00:00:00+01:00": 85.16583333333332,
#          "2024-03-01T00:00:00+01:00": 65.69916666666667,
#          "2024-04-01T00:00:00+02:00": 11.920000000000002,
#          "2024-05-01T00:00:00+02:00": 0,
#          "2024-06-01T00:00:00+02:00": 0,
#          "2024-07-01T00:00:00+02:00": 0,
#          "2024-08-01T00:00:00+02:00": 0,
#          "2024-09-01T00:00:00+02:00": 0,
#          "2024-10-01T00:00:00+02:00": 0,
#          "2024-11-01T00:00:00+01:00": 2.098333333333331,
#          "2024-12-01T00:00:00+01:00": null
#      }
#  }

# Get a specific site, that does not exists (status code 404).
# In this case, the API error response is processed and api client raises an exception.
try:
    sites_resp = api_client.sites.getone(42)
except BEMServerAPINotFoundError:
    # Manage resource not found error.
    pass

# Some kind of errors, like BEMServerAPIValidationError, includes details on what occured.
try:
    sites_resp = api_client.sites.create({"campaign_id": 1})
except BEMServerAPIValidationError as exc:
    # Manage validation error.
    print(exc.errors)
    # exc.errors actually contains a dict of validation messages:
    #  {
    #      "name": [
    #          "Missing data for required field."
    #      ]
    #  }