Specifikation för ett API för Elnätstariffer i Sverige. Specifikationen har sitt ursprung i Norge, varför mycket av dokumentationen just nu är på norska. Efterhand som specifikationen mognar och växer kommer även dokumentationen anpassas efter den svenska varianten.
| Dato | Versjon | Endring |
|---|---|---|
| 27.10.21 | 0.8 | Init |
| 17.11.21 | 0.9 | Soft release |
| 01.12.21 | 1.0 | Offisiell versjon |
DIGINprosjektet 'Nettariff API' jobbet med utvikling av en standard for deling av nettariffdata med brukere og tredjepartsaktører i kraftsystemet. Det var ikke innenfor prosjektets mandat å standardisere hvilke nettariffmodeller som skulle benyttes.
Hensikten med APIet er å støtte styring ved hjelp av smarthusteknologi og dermed stimulere til økt utnyttelse av fleksibilitet fra sluttbrukere. APIet er ikke ment å brukes til å få et korrekt historisk datagrunnlag for sluttbrukeres nettariff.
Dette betyr for eksempel at APIet leverer ut et GridTariff-objekt med kobling mellom en tariff og et målepunkt som er korrekt på tidspunktet for funksjonskallet. Hvis tidsperioden går lenger tilbake enn startdato for målepunktets kontrakt, så gjenspeiles ikke dette i APIet.
Altså er prishistorikken i responsen koblet til tariffen, ikke målepunktet.
Prosjektet leverer standardiserte skjema, med tilhørende dokumentasjon, for utveksling av nettariffdata. Legg merke til at det er opp til det enkelte nettselskap hvordan APIet skal implementeres, så prosjektet leverer ikke programvare for implementasjon.
Denne versjonen av standard for 'Nettariff API' tar ikke hensyn til kunder med redusert elavgift. Disse kundene må selv sørge for å trekke fra sin reduksjon av elavgift for å få korrekte priser.
Arbeidet i DIGIN er nå flyttet til ElBits AS. Se https://www.elbits.no for mer informasjon. Denne versjonen av standard for 'Nettariff API' tar ikke hensyn til kunder med redusert elavgift. Disse kundene må selv sørge for å trekke fra sin reduksjon av elavgift for å få korrekte priser.
Dokumentasjon for implementasjon av et "de facto" standard API for utveksling av Nettariff data for styring/smarthus.
API - Application programming interface
DN - DistribusjonsNett
HS - Høyspent nettilknytning
Implementasjon/Service - En tjeneste hos et nettselskap som leverer nettariff data etter DIGIN Nettariff spesifikasjonen.
Konsument/Klient - En applikasjon som konsumerer data fra et API. I denne sammenheng, typisk en 3. partsleverandør som skal hente nettariff data fra en eller flere nettselskap.
LS - Lavspent nettilknytning
MPID - Målepunkt-Id som finnes på faktura fra Nettselskapet eller på Min side (et logisk nummer som ikke er det samme som målernummer)
OpenAPI - Standard for API-spesifikasjoner, se referanser.
RN - RegionalNett (NB. DEKKES IKKE AV APIet)
Unique id - En unik id som er garantert unik innenfor responsen fra ett nettselskap. Dette kan være for eksempel en GUID (Global Unique IDentifier) eller et løpenummer som unikt identifiserer elementet i responsen. Denne er ikke garantert unik på tvers av flere nettselskaper.
Følgende versjoner finnes av DIGIN Nettariff API spesifikasjonen.
| Versjon | Type | Beskrivelse | Kommentar |
|---|---|---|---|
| 1.0 | Offisiell | Offisiell versjon som skal implementeres | Publisert 01.12.2021 |
| 0.9 | Arbeid | Arbeidsversjon etter innspill | Ikke utgitt |
| 0.8 | Arbeid | Versjon for innspill fra aktører | Publisert 27.10.2021 |
| 0.7 | Arbeid | Arbeidsversjon | Skal ikke publiseres |
Spesifikasjonen er opprettet ved bruk av standarden OpenAPI, https://www.openapis.org/.
Spesifikasjonen består av 2 json filer.
DiginGridTariffAPI.v1_0.json
Dette er OpenAPI spesifikasjonsfilen. Denne inneholder metoder og skjemadefinisjoner.
gridtariffapi.v1_0.common.schema.json
Inneholder definisjoner for input- og outputobjekter brukt av metoder.
OpenApi json filer kan vises som SWAGGER dokumentasjon. En måte å gjøre dette er å benytte Microsoft Visual Studio Code (gratis).
Importer OpenApi utvidelsen.
Åpne begge json filene i Visual Studio Code.
Velg utvidelsen OpenAPI (Rød sirkel rundt) og trykk på knappen "Show Preview using default render" (Rød sirkel rundt)
Dette vil vise SWAGGER-dokumentasjon som vist i bildet under.
ElBits leverer ikke en ferdig implementasjon av APIet. ElBits leverer spesifikasjon for implementasjon.
DiginGridTariffAPI.gridcompany-mapping.json
Nettselskap som implementerer Nettariff API melder inn sine MPID-serier, navn på nettselskap, organisasjonsnummer, url til api og url til brukerdokumentasjon eller epost-adresse til ElBits på epost-adresse [email protected].
Filen inneholder mapping av MPID (fra - til), nettselskapsnavn, nettselskapets organisasjonsnummer, url til api og url til brukerdokumentasjon eller epost-adresse.
https://github.com/3lbits/API-nettleie-for-styring/blob/main/doc/DiginGridTariffAPI.gridcompany-mapping.json
Dersom du opplever at målepunkt-id´er som skulle vært i en range hos et nettselskap ikke returneres som forventet, så kan det sjekkes hvilket nettselskap et målepunkt-id tilhører ved å bruke Elhub sitt metering-points API-endepunkt. Se https://api.elhub.no/api/energy-data for mer informasjon. Dersom du har innspill til forbedringer på dette endepunktet for å dekke dine behov, ta kontakt med Elhub eller send en epost til [email protected].
GridTariffAPI-3part-registration-and-use-of-api_v1_0.jpg
Sekvensdiagram som beskriver rutine for 3.-parts registerering av bruker og utstedelse av api-key.
https://github.com/3lbits/API-nettleie-for-styring/blob/main/doc/GridTariffAPI-3part-registration-and-use-of-api_v1_0.jpg
Spesifikasjonsfilene kan benyttes til å generere klient og service.
OpenAPI, https://www.openapis.org/, nevner flere verktøy som kan benyttes til dette.
Hvis en bruker Microsoft Visual Studio kan en generere en klient.
Dette gjøres i Visual Studio ved å legge til en "Service Reference", velge OpenAPI og så velge filen DiginGridTariffAPI.v1_0.json.
Merk at filene DiginGridTariffAPI.v1_0.json og gridtariffapi.v1_0.common.schema.json må være i samme mappe.
Det finnes open source implementasjoner av tidligere arbeids-versjon av denne spesifikasjonen, som f.eks. Elvias implementasjon:
https://github.com/3lvia/grid-tariff-api
I første versjon av APIet er det kun PULL som støttes, med anbefalt kallfrekvens på én gang per døgn. PUSH vurderes støttet i fremtidige versjoner!
Implementasjon hos nettselskapene eller deres leverandører kan bli "hostet" flere steder og på forskjellige måter.
Det er 3 store skyløsninger: Microsoft Azure, Google Cloud, Amazon Web Services.
Samt nettselskapene eller leverandørene kan "hoste" implementasjonen på lokale "on prem" web servere.
Vi har derfor sett det vanskelig å spesifisere hvilken modell av sikkerhet som kan passe alle.
ElBits kommer med følgende anbefalinger for implementering av GridTariffAPI:
- Enhver implementasjon bør sikres med autorisering og autentisering av innkommende forespørsler.
Hvordan dette gjøres er opp til hver nettselskap/leverandør, men det anbefales fra ElBits at det anvendes:
- HTTPS
- Gyldig sertifikat utgitt av godkjent leverandør
Med dette menes sertifikatet bør være godkjent av en "Certificate Authority, CA" - API key (name: X-API-Key) som request header
Mer om bruk av API key her: https://swagger.io/docs/specification/authentication/api-keys/
og her: https://cloud.google.com/endpoints/docs/openapi/when-why-api-key - API key utstedes per klient(for eksempel en smarthusleverandør eller en privat bruker) med registrert epost
API key bør ha en gyldighet på flere år (for eksempel 5 år)
Registrert epost brukes til å varsle klient ved invalidering av API key eller i god tid før automatisk utløp av API key
- Alle innkommende forespørsler og implementasjoner/installasjoner bør valideres i henhold til OWASP TOP 10, https://owasp.org/www-project-top-ten
Alle angivelser av dato og tid i spørringer og responser skal være i henhold til Elhubs Edielstandard.
https://dok.elhub.no/ediel/datetime-elements-37751603.html
I en tidsperiode, feks angitt av startDate og endDate, så er startDate inkludert og endDate ikke inkludert. Dvs endDate betyr at prisen gjelder inntil denne datoen.
Eksempel for en tidsperiode som gjelder hele januar, så angis dette av:
startDate = 2022-01-01
endDate = 2022-02-01
Dette gjelder alle tidsperioder med mindre annet er spesifisert.
Intitative, OPEN API. 2021. OPEN API. October. https://www.openapis.org/.
2021. SWAGGER. October. https://swagger.io/.
Visual Studio Code https://code.visualstudio.com/
OWASP https://owasp.org
Elhub Edielstandard. https://dok.elhub.no/ediel/edielstandard-37751483.html
Nettselskapene velger selv hvordan nettariffene bygges opp, innenfor visse rammer.
Fra og med 01.01.2022 endres kravene og i praksis gjelder følgende:
Fastledd:
- Fastleddet skal differensieres etter kundens etterspørsel etter kapasitet/effekt og vil dermed variere for kunder med årsforbruk under 100.000 kWh.
- I praksis vil de fleste tariffene baseres på makstime(r) pr dag eller måned, eller være sikringsbasert.
- Sikringsbasert: nivået på fastleddet er basert på størrelse på hovedsikring.
- Makstimebasert: nivået på fastleddet er basert på de(n) timen(e) i døgnet, også kalt "døgnmaks", eller måneden(e), også kalt "månedsmaks", der forbruket målt i kW(eller kWh/h) er høyest.
Effektledd:
- Effektledd er kun tillatt for bedriftskunder med årsforbruk over 100.000 kWh.
Eksempler på prising av forskjellige tariffer og link til eksempelfiler:
1. Månedsmaks ("monthlymax" med differensiert fastledd)
Type: LS kunde < 100.000 kWh
Nettnivå: LS DN
Link eksempel: https://github.com/3lbits/API-nettleie-for-styring/blob/main/doc/DiginGridTariffAPI.v1_0_meteringpointsgridtariffs_json_output_monthlymax_example1.json
2. Døgnmaks (med differensiert fastledd) (priser er inkludert mva og avgifter)
Type: LS kunde < 100.000 kWh
Nettnivå: LS DN
Link eksempel: https://github.com/3lbits/API-nettleie-for-styring/blob/main/doc/DiginGridTariffAPI.v1_0_meteringpointsgridtariffs_json_output_dailymax_example1.json
3. Sikringsbasert (med differensiert fastledd)
Type: LS kunde < 100.000 kWh
Nettnivå: LS DN
Link eksempel: https://github.com/3lbits/API-nettleie-for-styring/blob/main/doc/DiginGridTariffAPI.v1_0_meteringpointsgridtariffs_json_output_fusesize_example1.json
4. Effekttariff LS DN
Type: Tariff med effektledd.
Nettnivå: LS DN
Link eksempel: https://github.com/3lbits/API-nettleie-for-styring/blob/main/doc/DiginGridTariffAPI.v1_0_meteringpointsgridtariffs_json_output_LSDN_example1.json
5. Effekttariff LS DN med differensiert effektledd
Type: Tariff med effektledd.
Nettnivå: LS DN
Link eksempel: https://github.com/3lbits/API-nettleie-for-styring/blob/main/doc/DiginGridTariffAPI.v1_0_meteringpointsgridtariffs_json_output_LSDN_example2.json
6. Effekttariff HS DN med effektledd
Type: Tariff med effektledd.
Nettnivå: HS DN
Link eksempel: https://github.com/3lbits/API-nettleie-for-styring/blob/main/doc/DiginGridTariffAPI.v1_0_meteringpointsgridtariffs_json_output_HSDN_example1.json
Eksempler input:
Input with range parameter: https://github.com/3lbits/API-nettleie-for-styring/blob/main/doc/DiginGridTariffAPI.v1_0_meteringpointsgridtariffs_json_input_example_range.json
Input with startTime and endTime parameters: https://github.com/3lbits/API-nettleie-for-styring/blob/main/doc/DiginGridTariffAPI.v1_0_meteringpointsgridtariffs_json_input_example_startTime_endTime.json
21.12.2023: Dokumentasjon endret etter flytting fra DIGIN til ElBits:
- README: oppdatert etter flytting av github repo fra DIGIN-Energi til ElBits. DiginGridTariffAPI.gridcompany-mapping.json: lagt til informasjon om API hos Lede AS og fjernet duplikate oppføringer for Norgesnett.
- DiginGridTariffAPI.v1_0: Lagt til input parameter Product(for internt bruk for nettselskap) som er Exclusive OR med TariffKey. TariffKey ikke lenger definert required.
- DiginGridTariffAPI.v1_0.json: Endret description for StartTime, EndTime og Range i tag TariffQuery.
- gridtariffapi.v1_0.common.schema.json og alle eksempelfiler: Endret MeteringPointsAndPriceLevels til å inneholde currentFixedPriceLevel og meteringPoints, for å koble lastUpdated til meteringPoints og ikke currentFixedPriceLevel.
Endret CurrentFixedPriceLevel.levelId.description og MeteringPointDetails.lastUpdated.description.
Endret FixedPrices.pricelevel til FixedPrices.pricelevels og fra PowerPrices.pricelevel til PowerPrices.pricelevels.