EVO Metering API — Quick Manual

Purpose

This is a customer-facing guide for fetching meter metadata and time-series measurements (energy data, volume, temperatures, etc.) from your Elvaco Evo environment. The API is optimized for frequent, lightweight polling and easy integration into building analytics, energy dashboards, and data platforms.

Quick Facts

Authentication

All requests require a Bearer token. You must include it in the Authorization header.

• Format: Authorization: Bearer <your-token>
• Important: Tokens are time-limited. You must renew them before expiry via the token-renewal process in Evo.

Endpoints Overview

The API provides three main endpoints:

Available Resolutions

all, hour, day, month, oneMinute, fiveMinute, tenMinute, fifteenMinute, thirtyMinute

Example Quantities

• Energy (kWh/MWh)
• Volume (m³)
• Flow (m³/h)
• Power (W/kW)
• Forward/Return/Δ Temperature (°C/K)
• External temperature (°C)
• Relative humidity (%)
• Energy return
• Energy cooling
• CO₂ (ppm)
• RSSI (dBm)

1) Get Measurements

POST /api/v1/measurements — Retrieve measurement values for selected meters and quantities.

Request Body (Example)

{  
    "ids": [
        "b1c9e3b1-1111-2222-3333-7f9b6c1a0001", 
        "b1c9e3b1-1111-2222-3333-7f9b6c1a0002"
    ],  
    "reportAfter": "2025-10-01T00:00:00Z",  
    "reportBefore": "2025-10-31T23:59:59Z",  
    "resolution": "hour",  
    "quantities": [    
        { "name": "Energy", "unit": "kWh", "asConsumption": true },    
        { "name": "Forward temperature", "unit": "°C", "asConsumption": false }  
    ]
}

Response (Shape)

[  
    {    
        "id": "b1c9e3b1-1111-2222-3333-7f9b6c1a0001",    
        "quantity": "Energy",    
        "unit": "kWh",    
        "facility": "FAC-123",    
        "meterName": "Main heat meter",    
        "medium": "District heating",    
        "values": [      
            { "when": "2025-10-01T00:00:00Z", "value": 42.7 },      
            { "when": "2025-10-01T01:00:00Z", "value": 41.9 }    
        ]  
    }
]

Errors: 400 Bad Request (invalid/missing body).

2) List Meters

GET /api/v1/meters — Paginated list of meters with filtering and sorting.

Common Filters

Pagination and Sorting

• Pagination: page (0-based, default: 0), size (default: 20).
• Sorting: sort=property,(asc|desc) — repeatable.

Response (Shape)

{  
    "content": [    
        {      
            "id": "f2c0…",      
            "facility": "FAC-123",      
            "meterName": "Main heat meter",      
            "location": {        
                "country": "SE", "city": "Kungsbacka", "address": "Kabelgatan 2T",        
                "zip": "43437", "latitude": 57.5, "longitude": 12.0, "confidence": 0.9      
            },      
            "medium": "District heating",      
            "manufacturer": "Elvaco",      
            "readIntervalMinutes": 60,      
            "gatewaySerial": "GW123456",      
            "isReported": false,      
            "alarms": [{ "code": 101, "description": "Battery low" }]    
        }  
    ],  
    "totalElements": 123,  
    "totalPages": 7
}

Errors: 400 Bad Request (invalid parameters).

3) Get a Single Meter

GET /api/v1/meters/{id} — Full details for one meter.

Response (Shape)

{  
    "id": "f2c0…",  
    "facility": "FAC-123",  
    "meterName": "Main heat meter",  
    "medium": "District heating",  
    "manufacturer": "Elvaco",  
    "created": "2025-01-15T12:34:56Z",  
    "isReported": false,  
    "readIntervalMinutes": 60,  
    "location": {    
        "country": "SE", "city": "Kungsbacka", "address": "Kabelgatan 2T",    
        "zip": "43437", "latitude": 57.5, "longitude": 12.0, "confidence": 0.9  
    },  
    "alarms": [{ "code": 101, "description": "Battery low" }],  
    "revision": 2,  
    "mbusDeviceType": 3,  
    "gateway": { 
        "productModel": "CMe3100", 
        "serial": "GW123456", 
        "ip": "192.0.2.10", 
        "phoneNumber": "+4670..." 
    }
}

Errors: 404 Not Found (if not found).

4) Developer Resources

For complete, interactive documentation and testing capabilities, we recommend using our Swagger page. It provides detailed descriptions of all endpoints, data models, and error codes.

Swagger Documentation: https://evo.elvaco.se/api-doc/swagger-ui/index.html?configUrl=%2Fapi-doc%2Fswagger-config&urls.primaryName=Metering

Practical Tips

• Split large pulls into smaller chunks to stay under limits and speed up responses (e.g., by week or by meter group).
• Use asConsumption=true for quantities like Energy to get period consumption. Use asConsumption=false to get raw readouts. Recommended is to use "false".
• Choose the lowest workable resolution (e.g., hour instead of oneMinute) unless you need finer granularity.
• Error Handling: Errors return a JSON body with message and status fields. Handle 400 (Bad Request) and 404 (Not Found) errors as described per endpoint.

API Access Issues

For access, support, or token management, please contact Elvaco support.