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	Datetime		Tidspunkt for hjemtagning af aflæsning
Energi1Varmeenergi	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	Total 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
Enhed8	string		Enhed for flow
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åleren levetid
Enhed10	string		Enhed for maksimal afsat effekt
Målertype	string		Måleren 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	Datetime		Tidspunkt for hjemtagning af aflæsning
Volume	double	Tællerstand	Forbrugt vand
Unit	string		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