EVO Metering API — Snabbguide

Syfte

Detta är en kundguide för hur du hämtar mätarmetadata och tidsbaserade mätvärden (energidata, volym, temperaturer, etc.) från din Elvaco Evo-miljö. API:et är optimerat för frekvent, lättviktig polling och enkel integrering i byggnadsanalyssystem, energidashboards och dataplattformsapplikationer.

Snabba fakta

Autentisering

Alla förfrågningar kräver en Bearer-token. Du måste inkludera den i Authorization-headern.

• Format: Authorization: Bearer <din-token>
• Viktigt: Tokens är tidsbegränsade. Du måste förnya dem innan utgångsdatum via tokenförnyelseprocessen i EVO.

Översikt över slutpunkter

API:et tillhandahåller tre huvudsakliga slutpunkter:

Tillgängliga upplösningar

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

Exempel på kvantiteter

• 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) Hämta mätvärden

POST /api/v1/measurements — Hämta mätvärden för valda mätare och kvantiteter.

Exempel på förfrågan

{
  "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 }
  ]
}

Exempel på svar

[
  {
    "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 }
    ]
  }
]

Fel: 400 Bad Request (ogiltig/saknad kropp).

2) Lista mätare

GET /api/v1/meters — Paginering och filtrering av mätare.

Vanliga filter

Paginering och sortering

• Paginering: page (0-baserad, standard: 0), size (standard: 20).
• Sortering: sort=egenskap,(asc|desc) — kan upprepas.

Exempel på svar

{
  "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
}

Fel: 400 Bad Request (ogiltiga parametrar).

3) Hämta enskild mätare

GET /api/v1/meters/{id} — Fullständiga detaljer för en enskild mätare.

Exempel på svar

{
  "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..."
  }
}

Fel: 404 Not Found (om mätaren inte hittas).

4) Utvecklingsresurser

För fullständig, interaktiv dokumentation och möjlighet till testning, rekommenderar vi att du använder vår Swagger-sida. Den innehåller detaljerade beskrivningar av samtliga slutpunkter, datamodeller och felkoder.

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

Praktiska tips

• Dela upp stora hämtningar i mindre delar för att hålla dig inom gränserna och snabba upp svaren (t.ex. per vecka eller mätargrupp).
• Använd asConsumption=true för kvantiteter som Energi för att få periodförbrukningen. Använd asConsumption=false för att få råa avläsningar (råvärden). Rekommendation är att köra "false".
• Välj den lägsta fungerande upplösningen (t.ex. hour istället för oneMinute) om du inte behöver finare granularitet.
• Felhantering: Fel returnerar en JSON body med fälten message och status. Hantera felkoderna 400 (Bad Request) och 404 (Not Found).

Vid problem med API-åtkomst

För åtkomst, support eller hantering av token, vänligen kontakta Elvacos support.