Integrasjonsdokumentasjon

Transkript

1 Integrasjonsdokumentasjon Integrasjonsdokumentasjon for microdata strømprodukter Integrasjonsdokumentasjon for microdata strømprodukter Versjonering Innledning Bakgrunn Målgruppe Ordbok Bruksområde som dekkes av denne guiden Teknisk målbilde Brukseksempel Bruk av microdata Beskrivelse av format og integrasjon Gyldige verdier for boolean Elementer det kan være utfordrende å vise til kunde Rapporteringskrav Kilder / Mer informasjon / Nyttige lenker Tilleggsinformasjon Appendix 1 - eksempler på bruk NorgesEnergi Gul E-spot Hafslund webspot Appendix 2 - Parsing av microdata Versjonering Forfatter Versjon Merknad Ola Hast og Heikki Henriksen Kantega AS 0.9 Initiell versjon for godkjenning fra Forbrukerrådet Innledning Denne integrasjonsguiden er i utgangspunktet for strømleverandører og deres IT-avdeling/underleverandører som skal integrere microdata i leverandørens sider slik at Forbrukerportalen kan hente ut dette maskinelt. Guiden beskriver både funksjonelle krav som stilles til strømleverandørene og formatet på dataene som skal merkes med HTML Microdata. Bakgrunn Konkurransetilsynet har drevet en sammenlikningstjeneste for strømpriser på internett siden I 2014 fikk Forbrukerrådet i oppdrag å overta tjenesten. Nettstedet Forbrukerrådet bygger, vil ha en liknende innretning som Konkurransetilsynets tjeneste Kraftprisoversikten: Den nye tjenesten vil inneholde de samme produktene, men i tillegg er det et mål å inkludere alle avtaler som tilbys forbrukerne. Det er intensjonen at denne innsamlingen skal bli så omfattende som mulig, men med minst mulig innvirkning og utvikling hos strømleverandørenes hjemmesider. Siden det er et stort spenn i både IT-avdelinger og størrelse på de forskjellige leverandørene så er det ikke ønskelig at hver enkelt leverandør må gjøre store endringer i sine IT-systemer. Målgruppe Målgruppe for dette dokumentet er tekniske ressurser, arkitekter, utviklere og web designere som har som ansvar å implementere løsningen hos de respektive strømleverandører. Ordbok Ord scraping Betydning Å maskinelt lese nettsider med et skript. For eksempel for å indeksere siden for søk eller å hente ut informasjon fra siden.

2 Microdata WHATGW W3C En spesifikasjon for å legge inn Metadata i HTML, utviklet av WHATGW-gruppen En gruppe med medlemmer fra Apple, Mozilla og Opera som ble opprettet i kjølvannet av et møte i W3C World Wide Web Consortium, arbeidsgruppen som er ansvarlige for å vedlikeholde og videreutvikle HTML-standarden. Bruksområde som dekkes av denne guiden Dette dokumentet beskriver hvordan det er tenkt at strømleverandører som har som ansvar å tilgjengeliggjøre strømpriser skal gjøre dette. Etter å ha lest dette dokumentet skal leseren ha fått en innføring i hvordan total-løsningen er tenkt å fungere, hvordan integrere microdata i sine egne sider og hvordan dette skal rapporteres inn. Teknisk målbilde Det skal lages en nettside som skal vise strømpriser i en kalkulator. Prisene vil bli hentet fra en fra en database med innsamlede priser. Data i denne databasen blir hentet ut fra strømleverandørenes nettsider ved hjelp av en automatisk robot/scraper som vil sjekke for oppdateringer x antall ganger daglig/ukentlig/månedlig. Intensjonen er at det er samme priser og vilkår som vises til kunde på leverandørens hjemmesider som skal vises i forbrukerportalens kalkulator. I tillegg så er det ønskelig at den tekniske implementasjonen hos den enkelte leverandør skal være så liten og enkel som mulig. Det er antatt at å legge til koder i HTML er enklere enn å lage en backend integrasjon ved hjelp av f.eks web services og mindre arbeid enn manuell rapportering. Det er også en løsning som er uavhengig av strømleverandørs teknologivalg, og som kan løses ved hjelp av CMS-plugins, manuell koding og har ingen påvirkning på nettsidens "look and feel" Tegning 1. Skisse viser en oversikt over tenkt teknisk løsning Brukseksempel Bruk av microdata HTML Microdata er et format for strukturert innhold i nettsider. Standarden er utviklet av gruppen WHATWG og er utviklet med tanke på å kunne legge inn metadata i HTML som vil kunne hjelpe automatiserte innsamlingsroboter, søkemotorer og også nettlesere å bedre kunne vise strukturerte data. Disse kan da hente ut dataene som er merket og gi brukerne en bedre brukeropplevelse. Det har blitt opprettet et felles vokabular som er tilgjengeliggjort via Schema.org med Google, Microsoft og Yahoo! som pådrivere. Vi vurderte om det var mulig å gjenbruke vokabularet for produkt, men vi fant ut at det er et behov for et eget vokabular for strømpriser. Hele spesifikasjonen er tilgjengelig fra Microdata har følgende tags som kan benyttes: itemscope Oppretter et microdata-element og indikerer at alle underelementer inneholder informasjon om det.

3 itemtype En gyldig URL om et vokabular som beskriver elementet og verdiene som tilhører. itemid En unik nøkkel for elementet. itemprop Indikerer at tilhørende HTML-tag inneholder en verdi som har relevans for det gitte microdata-elementet. Alle itemprop-verdier står beskrevet i vokabularet. Inneholder som regel tekststreng-verdier men kan også bruke f.eks URL'er fra href-attributter fra <a>elementer eller src fra <img> elementer. itemref Verdier som ikke er underverdier av det gitte itemscope kan knyttes til et annet HTML element ved hjelp av denne verdien og elementets id (Ikke itemid). eksempel <div itemscope itemtype=" Vårt produkt heter <span itemprop="productname">variabel pris</span> Produktet er av typen <span itemprop="producttype">variabel</span> Oppstartsgebyret er <span itemprop="startupfee">100,00</span> og månedsgebyret er <span itemprop="monthlyfee">49,00</span> Kilowattpris i Nord-Norge er <span itemprop="kwpriceregionno4">0,30</span> og ellers <span itemprop="kwpriceregionno1 kwpriceregionno2 kwpriceregionno3 kwpriceregionno5">0,35</span> </div> Itemscope skal legges så høyt oppe i html-hierarkiet som mulig på et produkt, slik at den omslutter hele produktet. Itemtype skal være orbrukerradet.no/electricityproducts, som er namespace for vokabularet. Alle elementer som skal merkes skal merkes med riktig tag i henhold til formatet beskrevet under. Alle priselementer skal være på format kroner,øre med unntak av kilowatt-priser og andre priser hvor det er naturlig med øre,deler av øre. Eksempelet over vil produsere følgende JSON-streng dersom man parser det med en Microdata-parser:

4 { resultat "items": [ { "type": [ " "properties": { "monthlyfee": [ "49,00" "kwpriceregionno4": [ "0,30" "kwpriceregionno1 kwpriceregionno2 kwpriceregionno3 kwpriceregionno5": [ "0,35" "productname": [ "Variabel pris" "producttype": [ "Variabel" "startupfee": [ "100,00" ] ] Det har blitt utviklet en eksempelside hvor Microdata er implementert for en fiktiv strømleverandør: Denne ligger tilgjengelig på: (brukernavn/passord: kraftwerk/kantega2014) Her ligger også flere eksempler på HTML kode: Beskrivelse av format og integrasjon Det er et krav at strømprodukter blir merket med følgende vokabular. Vokabular for Navn Beskrivelse Format Microdata-tag Obligatorisk Produktnavn Produkttype Navnet på produktet slik det selges for kunde Type produkt, følgende verdier er gyldige verdier: Fastpris Variabel pris Spotpris Innkjøpspris Annen prismodell Ren tekstlig beskrivelse productname Ja Tekst producttype Ja

5 Beskrivelse av produktet (fritt tekstfelt, maks 400 tegn?) Fornybar Bindingstid Startgebyr Månedsgebyr Påslag per KW En tekstlig beskrivelse av produktet og hva det inneholder Har produktet et sertifikat som sier at kraften er fra en fornybar kilde? Dersom produktet har en bindingstid så oppgis det i antall måneder. Produktets oppstartspris dersom det har det. Produktets månedspris dersom det har det. Påslag per kilowatt-time dersom leverandør legger på dette. tekstfelt, maks 400 tegn productdescription Nei boolean (true/false certifiedreneweable Nei, default false int - antall måneder agreementtime Nei, default 0 dec (kroner, øre) startupfee Nei, default 0 dec (kroner, øre) monthlyfee Nei, default 0 dec (øre, øre) addonprice Nei, default 0 (hvis det er gyldig parameter for produkt) Kilowattpris forrige måned per område (enten 5 eller 136 områder) Oppgitt pris for forrige måned per kilowatt dec (øre, øre) Dersom det er fem regioner: kwpricelastmonthr egionno1 - Sørøst-Norge kwpricelastmonthr egionno2 - Sørvest-Norge kwpricelastmonthr egionno3 - Midt-Norge kwpricelastmonthr egionno4 - Nord-Norge kwpricelastmonthr egionno5 - Vest-Norge Ja, man oppgir de regioner man leverer strøm til. Dersom man leverer til alle fem regioner så må alle være oppgitt. Dersom det er snakk om 136 mindre lokalnett så kan man heller bruke kwpricelastmontharea< NettKvalifikator> som tag. Man oppgir bare de regionene eller lokalnettene man leverer til. På denne måten så kan også tilbyderne oppgi hvilke regioner de faktisk selger til og ikke.

6 Kilowattpris fram i tid per forsyningsområde Oppgitt pris fram i tid per forsyningsområde. Dersom det er spotpris eller innkjøpspris så er det ikke nødvendig å fylle inn dette feltet siden det hentes fra Nordpool. dec (øre, øre) Dersom det er fem regioner: kwpriceregionno1 - Sørøst-Norge kwpriceregionno2 - Sørvest-Norge kwpriceregionno3 - Midt-Norge kwpriceregionno4 - Nord-Norge kwpriceregionno5 - Vest-Norge Dersom det er Fastpris eller Variabel pris så skal det oppgis for de regionene man leverer til. Dersom det er snakk om 136 mindre lokalnett så kan man heller bruke kwpricearea<nettkvalifi kator> som tag. Man oppgir bare de regionene eller lokalnettene man leverer til. På denne måten så kan også tilbyderne oppgi hvilke regioner de faktisk selger til og ikke. Maksimalt antall kilowatt-timer per år Maksimalt forbruk dersom produktet spesifiserer maks forbruk per år. int maxkwyear Nei Merforbruk ut over maks. ant. Kwt (øre/kwt) frem i tid Kilowattpris dersom man bruker over spesifisert maks antall kilowatt-timer per år. kwpriceexcessusage Nei Merforbruk ut over maks. ant. Kwt (øre/kwt) forrige mnd Kilowattpris for overforbruk forrige måned, dersom produktet spesifiserer en maksgrense kwpriceexcessusagela stmonth Nei Eventuell tilgift Hvis leverandør har lagd en produktpakke som inneholder et produkt som ikke er strømrelatert så skal det oppgis her. Typisk avisabonnement, sesongkort eller kaffemaskin etc. (tekstfelt) packagedproduct evt bundledproduct Nei Leverandørens verdianslag for tilgift (kr) Leverandørens anslag på hvor mye tilgiften er verd. Dersom det er et abonnement eller løpende produkt skal årlig verdi oppgis. dec (kroner, øre) packagedproductestima tedvalue evt bundledproductestimate dvalue Ja, dersom packagedproduct er satt Kan tegnes av nye kunder? Ja/nei Kan produktet tegnes av nye kunder? boolean (true/false) applicabletonewcusto mers Nei, default true Betalingstid (forskudd/etterskudd/gje nnomsnitt) Fakturagebyr ved avtalegiro Betales det på forskudd, etterskudd eller snitt over periode Dersom det er gebyr for betaling med avtalegiro oppgis det her som kroner og øre enumerator feetype Ja dec (kroner, øre) feeavtalegiro Nei, default 0

7 Fakturagebyr ved efaktura Fakturagebyr ved faktura per e-post Fakturagebyr ved faktura i vanlig post Medlemskap Andre betingelser (tekstfelt) Hva som skjer om betingelser ikke oppfylles (tekstfelt) Dersom det er gebyr for betaling med efaktura oppgis det her som kroner og øre Dersom det er gebyr for å motta faktura per e-post oppgis det her som kroner og øre Dersom det er gebyr for å motta faktura per brev oppgis det her som kroner og øre Dersom et produkt fordrer at du er medlem i en eller flere foreninger eller lag så skal de oppgis her. Hvis produktet har betingelser knyttet til seg, f.eks knyttet til elektronisk faktura osv. skal det oppgis her. I dette feltet skal det fylles ut hva som faktisk skjer dersom andre betingelser ikke blir møtt. Dette feltet trenger kun å fylles ut dersom andre betingelser er utfylt. dec (kroner, øre) feeefaktura Nei, default 0 dec (kroner, øre) fee Nei, default 0 dec (kroner, øre) fe Nei, default 0 tekstfelt memberships Nei tekstfelt otherconditions Nei tekstfelt otherconditionsnotmet Ja, dersom otherconditions er utfylt Gyldige verdier for boolean Siden det skal være tekst som også skal vises til kunder så må det finnes flere gyldige verdier for boolske uttrykk. Verdiene er selvsagt ikke case-sensitive slik at det er mulig å bruke både store og små bokstaver. For true/ja så vil følgende være gyldige verdier Ja Yes True Y 1 For false/nei er følgende verdier gyldige: Nei No False N 0 Alternativt så kan meta-tag med content benyttes <meta itemprop="certifiedrenewable" content="true"/ >Du må være medlem av NITO for å benytte deg av dette tilbudet Elementer det kan være utfordrende å vise til kunde Det er mulig å definere skjulte elementer med <meta> tags men det er ikke anbefalt. Det kan være en løsning for f.eks boolske uttrykk og informasjon som det kan være vanskelig å tilpasse i en vanlig tekststreng:

8 <div itemscope itemtype=" Vårt produkt heter <span itemprop="productname">variabel pris</span> Produktet er av typen <span itemprop="producttype">variabel</span> Oppstartsgebyret er <span itemprop="startupfee">100,00</span> og månedsgebyret er <span itemprop="monthlyfee">49,00</span> Kilowattpris i Nord-Norge er <span itemprop="kwpriceregionno4">0,30</span> og ellers <span itemprop="kwpriceregionno1 kwpriceregionno2 kwpriceregionno3 kwpriceregionno5">0,35</span> <meta itemprop="feeavtalegiro" content="0" /> <meta itemprop="fe " content="100" /> <span itemprop="memberships">nord-norge <meta itemprop="memberships" content="nito"/> <meta itemprop="memberships" content="tekna"/>du må være medlem av NITO eller Tekna for å benytte dette tilbudet </span> </div> Det er også ønskelig å at informasjon om organisasjonen er tagget. Det er utviklet et mindre vokabular for å støtte dette. Dette kan legges på en side som inneholder informasjon om selskapet. Vokabular for Navn Beskrivelse Format Microdata-tag Obligatorisk navn Navnet på selskapet tekststreng companyname Ja hovedeier Hvem er hovedeier i selskapet tekststreng mainshareholder Nei hovedeierandel Hvor stor andel eier hovedeier heltall (0-100) mainshareholderpercen tage Nei administrerendedirektør Navn på administrerende direktør tekststreng ceo Nei styreformann Navn på styreformann tekststreng chairman Nei orgnummer Organisasjonsnummer heltall, behandles som streng (åtte siffer) organizationnumber Ja Stiftelsesår Kontaktinformasjon Hvilket år ble selskapet startet? Fritekstfelt med kontaktinformasjon heltall formationyear Nei tekststreng contactinformation Ja Rapporteringskrav Roboten vil i utgangspunktet søke gjennom hele nettsiden, men det kan være aktuelt at det rapporteres inn enkeltsider som skal gjennomsøkes i stedet. Kilder / Mer informasjon / Nyttige lenker WHATGW - HTML Microdata standard - Schema.org - Andre aktuelle microdata-vokabularer - W3C - HTML Best practices - Tilleggsinformasjon Appendix 1 - eksempler på bruk

9 NorgesEnergi Gul E-spot Norgesenergis sider har alle data tilgjengelige for Gul E-spot. Siden de fire sidene på forsiden i praksis er et html-dokument så er det mulig å hente ut det meste. Det er noen begreper som mangler, som f.eks betalingstid, hvor de har valgt begrepet A-konto. Navn Microdata-tag Verdi Produktnavn productname Gul E-Spot Produkttype producttype Spotpris Startgebyr startupfee 0 Månedsgebyr MonthlyFee 14,00 Kilowattpris forrige måned per område (enten 5 regioner eller 136 områder) kwpricelastmonthregionno1 kwpricelastmonthregionno2 kwpricelastmonthregionno3 kwpricelastmonthregionno5 kwpricelastmonthregionno4 28,53 28,53 33,72 27,09 28,53 Kan tegnes av nye kunder? Ja/nei applicabletonewcustomers Ja Betalingstid (forskudd/etterskudd/gjennomsnitt) paymenttype forskudd Andre betingelser (tekstfelt) otherconditions Må betale via efaktura eller AvtaleGiro Hva som skjer om betingelser ikke oppfylles (tekstfelt) Beskrivelse av produktet (fritt tekstfelt, maks 400 tegn?) Kunde flyttes over til ordinær spot productdescription GUL e-spot - kun 14 kroner/mnd 3 måneder gratis fastbeløp Strøm til innkjøpspris Kun 14 kr i månedlig fastbeløp efaktura og AvtaleGiro som betalingsform* Bestill nå så spanderer vi fastbeløpet på deg de første 3 månedene!** Hafslund webspot Ved å legge til microdata-tags på Hafslund sin produktside for webspot - vil følgende JSON kunne hentes ut: Merk at alle obligatoriske felter med unntak av to er utfylte. 1. Betalingsmåte, feetype, mangler (forskudd, etterskudd eller gjennomsnitt) og 2. Dersom vilkårene ikke blir møtt: otherconditionsnotmet mangler også. Ellers har produktsidene det som er nødvendig allerede med små endringer i HTML-kode.

10 { "items": [ { "type": [ " "properties": { "productdescription": [ "En av landets billigste spotprisavtaler for deg som \u00f8nsker alt 100 % elektronisk." "otherconditions": [ "Avtalen kan kun\u00a0bestilles p\u00e5 web. Avtalen forutsetter elektronisk fakturering og AvtaleGiro, og at du administrerer kundeforholdet ditt ved hjelp av Min side." "productname": [ "webspot" "monthlyfee": [ "15,90" "kwpricelastmonthregionno1 kwpricelastmonthregionno2 kwpricelastmonthregionno3": [ "28,53" "producttype": [ "Spotpris" ] ] Appendix 2 - Parsing av microdata Det finnes mange eksisterende løsninger for parsing av strukturerte data for de fleste programmeringsspråk. Her er et eksempel på hvordan det kan testes ved hjelp av Python. Vi har valgt å ta med et eksempel på parsing fordi det kan brukes som et verktøy for å verifisere implementasjonen. Python og pip må installeres på maskinen som det skal testes med. Se her for beskrivelse for ditt operativsystem: Etter at begge deler er installert så kan følgende kommando kjøres for å installere microdata.py, som er testverktøyet i dette eksempelet: > pip install microdata Når dette er utført så kan følgende kommando kjøres fra kommandolinjen: > microdata.py Dette vil hente ut mikrodata med omtaler og informasjon om gatekjøkkenet "illegal burger" i oslo. URL kan selvsagt endres til andre sider eller lokale filstier. Mer informasjon om microdata.py kan finnes her: