Implementing ESG Metrics Retrieval

note

You are currently looking at a work in progress version of the Relynk API documentation. Consider the underlying APIs and messaging formats as stable, but we strive to make the documentation as developer friendly as possible. If you feel anything is missing please reach out to hello@relynk.io, any feedback would be much appreciated.

Implementing ESG Metrics Retrieval with Relynk API

This guide is designed for developers looking to use the Relynk API to fetch Environmental, Social, and Governance (ESG) metrics for buildings. We'll cover how to retrieve key metrics such as energy, water, and waste for any given building using the Relynk API. The process involves two primary steps: obtaining the building ID and fetching the ESG metrics based on that ID.

caution

Prerequisites

Before diving into the API calls, ensure you have:

• Read about the Data Model to understand the structure of the data you will be working with.
• Familiarized yourself with the Introduction to Relynk API and the Authentication process required for making API requests.
• Reviewed the Query API to learn about the available query parameters and response structure.

Step 1: Retrieving the List of Buildings

To fetch ESG metrics, you first need the ID of the building you're interested in. You can obtain a list of all buildings available by making a request to the /building endpoint. The endpoint also supports filtering on various properties. See the API Reference for more information. Here is an example using curl:

curl -X GET 'https://api.relynk.io/v4.0.0.24/query' \
-H 'Authorization: Bearer YOUR_ACCESS_TOKEN'

This request will return a list of all buildings in the system. To see all the Building IDs and names, look at the @id and name fields in the hydra:member array of the response.

{
  "hydra:member": [
    {
      "@id": "f88810e6-1466-53a4-a476-b744eb0ab005",
      "name": "Building 1"
    },
    {
      "@id": "ce6e07e3-f987-5fad-be02-e62095871937",
      "name": "Building 2"
    },
    ...
  ],
  ...
}

Step 2: Fetching ESG Metrics for a Building

Once you have the ID of your target building, you can filter on the resource_id of the building and the specific point_subtypes for energy, water, and waste metrics. The process involves creating a query payload that specifies these filters and sending a request to the /query endpoint. Here's how to structure your requests for each metric:

Energy Metrics

To fetch the latest energy consumption for a building, use the resource_id of the building and filter for energy point subtype. For example:

{
  "filters": [
    {
      "filter_on": "resource_id",
      "value": [
        "BUILDING_ID" // This is the resource id of the building
      ]
    },
    {
      "filter_on": "point_subtype",
      "value": ["https://brickschema.org/schema/Brick#Energy_Sensor"]
    }
  ],
  "group_on": "https://w3id.org/rec#Building",
  "resolution": "1 hour",
  "is_timeseries": true,
  "only_latest_value": true
}

Water Metrics

To retrieve the latest water usage, adjust the point_subtype filter:

{
  "filters": [
    {
      "filter_on": "resource_id",
      "value": [
        "BUILDING_ID" // This is the resource id of the building
      ]
    },
    {
      "filter_on": "point_subtype",
      "value": ["https://brickschema.org/schema/Brick#Water_Usage_Sensor"]
    }
  ],
  "group_on": "https://w3id.org/rec#Building",
  "resolution": "1 hour",
  "is_timeseries": true,
  "only_latest_value": true
}

Waste Metrics

To retrieve latest waste metrics, adjust the point_subtype filter:

{
  "filters": [
    {
      "filter_on": "resource_id",
      "value": [
        "BUILDING_ID" // This is the resource id of the building
      ]
    },
    {
      "filter_on": "point_subtype",
      "value": [
        "https://relynk.io/ontology/extentions#Total_Sorted_Waste_Weight_Sensor",
        "https://relynk.io/ontology/extentions#Total_Unsorted_Waste_Weight_Sensor"
      ]
    }
  ],
  "group_on": "https://w3id.org/rec#Building",
  "resolution": "1 hour",
  "is_timeseries": true,
  "only_latest_value": true
}

note

The examples above are simplified to demonstrate the process of retrieving specific ESG metrics. Depending on the available data and your specific needs, you may need to adjust the filters, resolution, or other parameters accordingly.

Conclusion

Retrieving ESG metrics for buildings using the Relynk API involves obtaining the building ID and then making targeted queries. By following the steps outlined above and adjusting parameters as needed for your specific use case, you can effectively gather valuable ESG data for analysis or reporting.