bemserver-api-client 0.21.1

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.

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("user@email.com", "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."
    #      ]
    #  }