API for adgang til målerdata 

Her kan du læse om, hvordan du får adgang til målerdata via API. Der benyttes de samme dataservices til både fjernaflæste vandmålere og fjernaflæste varmemålere.

Introduktion 

Målerdata via API er en system-til-system-integration, hvor der implementeres en IT-service, som kan kalde og hente data fra Aalborg Forsyning. IT-servicen, som der kan kobles op mod og hentes data fra, er REST-baseret og svaret er JSON-formateret. Det er således nødvendigt med et vist IT-kendskab for at implementere servicen. 


Øvrige forhold vedr. tilgængelighed af data

Der returneres ved kald til dataservicen fjernaflæste timebaserede målinger. Servicen kan kaldes tre gange i døgnet og returnerer data for de tre seneste døgn (eller kortere). Data vil typisk være maks. tre timer forsinket i forhold til realtidsdata. (Data set direkte på måleren kontra de samme data tilgængelige på dataservicen.)  

Data fra de fjernaflæste målere vil være tilgængelige efterhånden, som datahjemtagningen påbegyndes til Aalborg Forsyning. Det vil fremgå ved tilmelding af den enkelte måler, hvorvidt vi har regelmæssige data til rådighed.

API-kald: Fælles for både data fra fjernaflæste vand- og varmemålere

Følgende services udstilles

https://services.aalborgforsyning.dk/Token (POST: Angiv brugernavn og password for at få autorisations-token retur )

https://services.aalborgforsyning.dk/api/data/Meters (GET: Angiv autorisations-token for at få liste med målerid retur)

https://services.aalborgforsyning.dk/api/data?meterid=999999999 (GET: Angiv autorisations-token og få aktuelle målerværdier retur)

API for adgang til fjernaflæste varmemålere:
Aflæsningsdata og typer:

  • Tællerstand: Fortløbende tæller i måleren, der aflæses nuværende værdi
  • Punktaflæsning: Målerens tilstand på aflæsningstidspunktet
  • Midlet aflæsning: Beregnet værdi baseret på måleren tilstand over tid
Felt
Datatype / Aflæsningstype
Beskrivelse
Kundenummer
Integer
Identifikation af kundeforhold
MeterID
Integer
Måleren serienummer
Aflæsningstidspunkt
Datatime
Tidspunkt for hjemtagning af aflæsning
Energi Varmeenergi
Double/Tællerstand
Forbrugt energi
Enhed
String
Enhed for forbrugt energi
Volumen
Double / Tællerstand
Forbrugt vand i m3
Enhed2
String
Enhed for forbrugt vand
Timetæller
Integer / Tællerstand
Antal timer måleren har været i drift
Enhed3
String
Enhed for antal timer måleren har været i drift
Energi8
Double / Tællerstand
Totalt fremført energi
Enhed4
String
Enhed for fremført energi
Energi9
Double / Tællerstand
Total tilbageført energi
Enhed5
String
Enhed for tilbageført energi
Temperatur1
Double / Punktaflæsning
Fremløbstemperatur
Enhed6
String
Enhed for fremløbstemperatur
Temperatur2
Double / Punktaflæsning
Returløbs temperatur
Enhed7
String
Enhed for returløbstemperatur
Flow1
Double / Midlet afløsning
Flow sidste time
Enhed 8
String
Enhed for effekt
Infokoder
String
Anvendes ikke
Effekt1
Double / Punktaflæsning
Nuværende afsat effekt
Enhed9
String
Enhed for effekt
MaksEffekt1
Double / Punktaflæsning
Maksimal afsat effekt i målerens levetid
Enhed10
String
Enhed for maksimal afsat effekt
Målertype
String
Målerens type
Felt

Datatype / Aflæsningstype

Integer

Beskrivelse

Identifikation af kundeforhold

Datatype / Aflæsningstype

Integer

Beskrivelse

Måleren serienummer

Datatype / Aflæsningstype

Datatime

Beskrivelse

Tidspunkt for hjemtagning af aflæsning

Datatype / Aflæsningstype

Double/Tællerstand

Beskrivelse

Forbrugt energi

Datatype / Aflæsningstype

String

Beskrivelse

Enhed for forbrugt energi

Datatype / Aflæsningstype

Double / Tællerstand

Beskrivelse

Forbrugt vand i m3

Datatype / Aflæsningstype

String

Beskrivelse

Enhed for forbrugt vand

Datatype / Aflæsningstype

Integer / Tællerstand

Beskrivelse

Antal timer måleren har været i drift

Datatype / Aflæsningstype

String

Beskrivelse

Enhed for antal timer måleren har været i drift

Datatype / Aflæsningstype

Double / Tællerstand

Beskrivelse

Totalt fremført energi

Datatype / Aflæsningstype

String

Beskrivelse

Enhed for fremført energi

Datatype / Aflæsningstype

Double / Tællerstand

Beskrivelse

Total tilbageført energi

Datatype / Aflæsningstype

String

Beskrivelse

Enhed for tilbageført energi

Datatype / Aflæsningstype

Double / Punktaflæsning

Beskrivelse

Fremløbstemperatur

Datatype / Aflæsningstype

String

Beskrivelse

Enhed for fremløbstemperatur

Datatype / Aflæsningstype

Double / Punktaflæsning

Beskrivelse

Returløbs temperatur

Datatype / Aflæsningstype

String

Beskrivelse

Enhed for returløbstemperatur

Datatype / Aflæsningstype

Double / Midlet afløsning

Beskrivelse

Flow sidste time

Datatype / Aflæsningstype

String

Beskrivelse

Enhed for effekt

Datatype / Aflæsningstype

String

Beskrivelse

Anvendes ikke

Datatype / Aflæsningstype

Double / Punktaflæsning

Beskrivelse

Nuværende afsat effekt

Datatype / Aflæsningstype

String

Beskrivelse

Enhed for effekt

Datatype / Aflæsningstype

Double / Punktaflæsning

Beskrivelse

Maksimal afsat effekt i målerens levetid

Datatype / Aflæsningstype

String

Beskrivelse

Enhed for maksimal afsat effekt

Datatype / Aflæsningstype

String

Beskrivelse

Målerens type

Eksempel på returnerede data ved kald til dataservice er:

[

    {

        "kundenummer": xxxxxx,

        "meterID": xxxxxxxx,

        "aflæsningstidspunkt": "2020-02-10T23:48:00",

        "energi1Varmeenergi": 1088.03,

        "enhed": "MWh",

        "volumen1": 25064.6,

        "enhed2": "m3",

        "timetæller": 25048,

        "enhed3": "h",

        "energi8": 1847120,

        "enhed4": "m3xC x 0.1",

        "energi9": 886310,

        "enhed5": "m3xC x 0.1",

        "temperatur1": 70.16,

        "enhed6": "C",

        "temperatur2": 34.43,

        "enhed7": "C",

        "flow1": 1.24,

        "enhed8": "m3/h",

        "infoKoder": null,

        "effekt1": 50.4,

        "enhed9": "kW",

        "maksEffekt1": 230.6,

        "enhed10": "kW",

        "målertype": "MULTICAL 403"

    },

    {

        "kundenummer": xxxxxx,

        "meterID": xxxxxxxx,

        "aflæsningstidspunkt": "2020-02-10T22:50:00",

        "energi1Varmeenergi": 1087.98,

        "enhed": "MWh",

        "volumen1": 25063.4,

        "enhed2": "m3",

        "timetæller": 25047,

        "enhed3": "h",

        "energi8": 1847040,

        "enhed4": "m3xC x 0.1",

        "energi9": 886260,

        "enhed5": "m3xC x 0.1",

        "temperatur1": 69.31,

        "enhed6": "C",

        "temperatur2": 34.16,

        "enhed7": "C",

        "flow1": 1.02,

        "enhed8": "m3/h",

        "infoKoder": null,

        "effekt1": 40.8,

        "enhed9": "kW",

        "maksEffekt1": 230.6,

        "enhed10": "kW",

        "målertype": "MULTICAL 403"

    }

API for adgang til fjernaflæste vandmålere:
Aflæsningsdata og typer: 

Tællerstand: Fortløbende tæller i måleren, der aflæser nuværende værdi.

Felt
Datatype / Aflæsningstype
Beskrivelse
Kundenummer
Integer
Identifikation af installationsnummer
MeterID
Integer
Målerens serienummer
ReadTime
Datatime
Tidspunkt for hjemtagning af aflæsning
Volume
Double / Tællerstand
Forbrugt vand
Unit
String
Enhed for Volume vand
Felt

Datatype / Aflæsningstype

Integer

Beskrivelse

Identifikation af installationsnummer

Datatype / Aflæsningstype

Integer

Beskrivelse

Målerens serienummer

Datatype / Aflæsningstype

Datatime

Beskrivelse

Tidspunkt for hjemtagning af aflæsning

Datatype / Aflæsningstype

Double / Tællerstand

Beskrivelse

Forbrugt vand

Datatype / Aflæsningstype

String

Beskrivelse

Enhed for Volume vand

Eksempel på returnerede data ved kald til dataservice er:

[

    {

        "kundenummer": xxxxxx,

        "meterID": xxxxxxxx,

        "readTime": "2021-07-02T08:01:00",

        "volume": 592.54,

        "unit": "m3"

    },

    {

        "kundenummer": xxxxxx,

        "meterID": xxxxxxxx,

        "readTime": "2021-07-02T07:01:00",

        "volume": 592.33,

        "unit": "m3"

    },

    {

        "kundenummer": xxxxxx,

        "meterID": xxxxxxxx,

        "readTime": "2021-07-02T06:01:00",

        "volume": 591.91,

        "unit": "m3"
    },

    {

        "kundenummer": xxxxxx,

        "meterID": xxxxxxxx,

        "readTime": "2021-07-02T05:01:00",

        "volume": 591.88,

        "unit": "m3"

    },

    {

        "kundenummer": xxxxxx,

 

Test setup

Testgrænseflade

Til testformål kan følgende legitimationsoplysninger bruges ved kalde til Token service.

Brugernavn: test@test.dk

Adgangskode: TestKode1

Det vil være muligt at hente oplysninger for 6 målere med følgende ID:

  • 999999999 -> (varmemåler)
  • 999999992 -> (varmemåler)
  • 999999993 -> (varmemåler)
  • 999999994 -> (vandmåler)
  • 999999995 -> (vandmåler)
  • 999999996 -> (vandmåler)

Da det kun er en testopsætning, så vil det være det samme statiske datasæt, som returneres hver gang datatjenesten kaldes.  For de første 3 målere returneres Varme data og for de resterende 3 målere returneres Vand data.

Til produktionsbrug skal der defineres et nyt “Brugernavn” og “Adgangskode” og konfigurere de “rigtige live målere”, hvorfra dataene hentes.

 

Flow

"Flowet", som kan implementeres, er noget lignende nedenstående:

  • Få adgangs token ved at kalde Token servicen. Her implementeres Bearer-token.
  • Brug Bearer-token til at kalde Meters servicen. Her returneres en liste over alle målere, der er adgang til.
  • Brug Bearer-token til at få adgang til Data servicen. (Kaldes for hvert meter-id, der returneres af getmeters servicen).
  • Modtagne måleraflæsninger skal sorteres for duplikatværdier, hvis data tidligere (inden for de seneste 3 døgn) er hentet for den specifikke måler. Hver gang Data servicen kaldes, returneres alle måleraflæsninger i op til 3 dage. Det er muligt at indstille et kortere interval i serviceopkaldet, hvis det ønskes
  • Importer de hentede værdier til det system der ønskes. Eks. eget energi eller forbrugsanalysesystem.

Eksempler på http kald til services - API funktioner

Gældende for data fra både fjernaflæste vand- og varmemålere:

”Token”

Returnerer et access token, der giver adgang til at hente data fra Data funktionen. Access token har en levetid på to timer.

Request:

POST /Token HTTP/1.1

Host: services.aalborgforsyning.dk

Content-Type: application/x-www-form-urlencoded

grant_type=password&username=test@test.dk&password=TestKode1

”Meters”

Returnerer liste i JSON format med målere der er givet adgang til.

GET /api/data/Meters HTTP/1.1

Host: services.aalborgforsyning.dk

Authorization: Bearer faw-0dYlyBH6xBZ8GAUgQeu354HPuksQ2ZEwg5NYSJlzsRyny0BOl-PvAWRnQYRz5_ZJmUKWUByaHcNIcuCTkCQUhXoA1WFMXrRnxKJ4lVXBdrJ38sbx3pahWvXvBQdt4P5aacC1qHzvGfbXnfcwI8cL_XWa_UkuUYYreTNmeustTTwSn1JLJAgfXg63XCAX3DfBTr_s0zGNB00gN0vr013rftHWGf8iSaWyhpywPpDADwqz_rhS0XtRy_3RQEzf19m231j_8PGGwKXRX3RfrfD4wgFMHQadsDMv27kZMVjXVXGwD33zPOrMUIk9AY1iEuV4q7FXoQgpPqhpBzRzvEpA7S8dkTLkx3efORRjM2erbhsSR89lxAzbGOXs25n3vZ1k-8gS-wzdPympNoqpBI0nVfFdDlYGJVfMwCacytSUZ8rYtEQ1bj6-cOOE7dwnnjVG2-_J3t93njzAZrgtT1bZeLbD_rls3RtzTjAeMu0

”Data”

Returnerer forbrugsdata i JSON format for de seneste tre døgn for en given måler. I http headeren ”Authorization” angives Bearer + access_token returneret fra Token funktionen, og i Query parameteren ”meterid” angives målernummeret.

Request:

GET /api/data?meterid=999999993 HTTP/1.1

Host: services.aalborgforsyning.dk

Authorization: Bearer faw-0dYlyBH6xBZ8GAUgQeu354HPuksQ2ZEwg5NYSJlzsRyny0BOl-PvAWRnQYRz5_ZJmUKWUByaHcNIcuCTkCQUhXoA1WFMXrRnxKJ4lVXBdrJ38sbx3pahWvXvBQdt4P5aacC1qHzvGfbXnfcwI8cL_XWa_UkuUYYreTNmeustTTwSn1JLJAgfXg63XCAX3DfBTr_s0zGNB00gN0vr013rftHWGf8iSaWyhpywPpDADwqz_rhS0XtRy_3RQEzf19m231j_8PGGwKXRX3RfrfD4wgFMHQadsDMv27kZMVjXVXGwD33zPOrMUIk9AY1iEuV4q7FXoQgpPqhpBzRzvEpA7S8dkTLkx3efORRjM2erbhsSR89lxAzbGOXs25n3vZ1k-8gS-wzdPympNoqpBI0nVfFdDlYGJVfMwCacytSUZ8rYtEQ1bj6-cOOE7dwnnjVG2-_J3t93njzAZrgtT1bZeLbD_rls3RtzTjAeMu