BuildingMinds Metering System Integration Prerequisites

This document serves as a comprehensive guide for third-party metering solution providers aiming to establish new data connections with the BuildingMinds Platform. Two primary data integration methods are supported:

• API (preferred)  
• Flat file transfer  

API requirements 

• Accessibility: The API is publicly accessible and secured via HTTPS.
• Data Access: Must provide access to historical data as real-time streaming is not supported.
• Documentation: Comprehensive API documentation should detail all significant endpoints.
• Testing Environment: Access to actual meters and data or a set of test data is required. A sandbox environment is recommended for integration testing.
• Authentication: Preferred methods are JWT bearer token or API Key.
• Endpoints:
  • Retrieve meters and their master data.
  • Obtain filtered meter readings based on input parameters.

Flat file transfer requirements 

• Format Compliance: Data must adhere to the format specified in the API documentation for each entity. API Documentation. 
• Template Usage: Use the flat file template based on conclusions from integration scoping discussions.
• Accepted Formats: CSV, XLS, and XLSX.

Data model requirements 

The following requirements apply to both integration methods. Data should remain unaggregated and untransformed at the provider's side to maintain quality:

Meter master data 

**Static information about meters:

• Meter Identifier: Unique ID number (e.g., MPAN, MPRN).
• Connection Classification: Type of installation premises (e.g., Rental unit, Shared space).
• Area coverage: Location, type, (e.g., Hallway, Common area).
• Utility Information: Category and subtypes (e.g., Electricity, Gas, Grid Electricity, Green contract).
• Unit of consumption: Meter reading values with units of consumption (e.g., 500 kWh).
• Procurement Entity: Responsible party (e.g., Landlord procured, Tenant procured).
• Operational Measurement: Name of the resource measured (e.g., heating, Electricity or Gas).
• Data Source and Intervals: Source and frequency of readings (e.g., Smart meter 30 min interval or Utility provider Monthly interval).
• Historic Data Availability: Availability of past months consumption information.
• Reading Value Type: Cumulative or delta values.
• Contract Type: Type of utility contract (e.g., Green, Brown contract).

Additional useful attributes

• Main-Meters: To be able to query the number of main-meters installed in a building.
• Sub-Meters: To be able to query the number of sub-meters installed in a building.
• Meter Mapping: A clear meter mapping information informing how the meters are mapped within the building.

Meter reading data 

This refers to the dynamic information collected from a meter at regular intervals, which records the consumption of a utility (electricity, gas, or water).

Meter reading data is updated frequently (daily, monthly, or at other specified intervals) and is used for billing purposes, monitoring usage patterns, and detecting anomalies or issues with the meter or utility supply. Below is a sample data point with examples:

• Meter Identifier: Unique ID number (e.g., MPAN, MPRN).
• Measurement Timestamp: Date of the reading in UTC (e.g., 2021-12-01T12:00:00Z).
• Timestamp Range: Time range for which the reading is valid (e.g., 2021-12-01T12:00:00Z - 2021-12-01T12:15:00Z).
• Data Interval: Frequency of meter reading (e.g., 15, 30, 60 minute interval).
• Utility category: Resource consumed (e.g., Water, Electricity, Gas etc).
• Measurement Units: kWh, m3, kg.
• Value Measured: Type of value measured Delta, Incremental or Gauge.
• Value Status: Status of value measured if it is actually metered or measured.
• Accuracy/Tolerances: Reading accuracy (e.g., ±2%)

Maintenance and Error handling requirements 

• Additional information/errors to be sent via connected meter read-outs: 

• System is not able to detect meter changes. 

• Negative values in the data point result due to resetting. 

• System is unable to distinguish between manual and meter reading. 

• System is unable to read meters resetting. 

• System is able to flag null values and pass those data points.

• System is able to flag meters returning null values.

• System is able to detect meter resets and pass that information.

• System is able to deal with negative values? E.g. Negative values in the data point result due to resetting.