Petter Reinholdtsen

Litt informasjon om Bitfactorys Bensinpris-API
28th May 2012

I fjor lanserte Bitfactory en mobilapp for å få tilgang til bensinpriser på landets bensinstasjoner ved å samle inn prisene på dugnad ved hjelp av mobilapp-ens brukere. Informasjonen app-ens brukere har samlet inn har så langt kun vært tilgjengelig for brukerne av app-ene, og API for å hente ut informasjonen fra andre plattformer har ikke vært publisert. Da løsningen kom spurte jeg utviklerne om de kunne publisere API-dokumentasjon og de skulle se på saken, men det har ikke skjedd så langt. Jeg antar de har vært for travelt opptatt til å publisere API-dokumentasjon.

Utrolig nok er det i følge Dagens Næringsliv og Finnmark Dagblad bensinstasjoner som nekter å oppgi prisene sine på telefon, slik at det ikke finnes en fornuftig måte å få tak i prisene på uten å samle dem inn på stedet. Flere har dugnader på gang for å samle inn prisinformasjon om bensin, men så vidt jeg kan se er det kun dinside.no og Bitfactorys App som får regelmessige oppdateringer. Dinsides oversikt er tilgjengelig på web for de som vil følge med, mens bitfactorys informasjon ikke er like enkelt tilgjengelig.

Jeg tok meg derfor litt tid for å revers-utvikle protokollen for Bitfactorys mobilapp for å gjøre den innsamlede informasjonen mer tilgjengelig for flere. Protokollen bruker HTTP og normal forms-notasjon for POST. Jeg lot en telefon koble seg til mitt trådløsnett, og satte opp tcpdump til å samle all trafikken mot www.bitfactory.no, og deretter tittet på alle HTTP-kallene ved hjelp av wireshark. Her er API-kallene jeg har identifisert så langt.

stasjonsDatabaseUpdateStamp

GET http://www.bitfactory.no/Bensin/ver1.1.stasjonsDatabaseUpdateStamp

Vet ikke helt hva dette API-kallet gjør, men navnet gjør at jeg tror den rapporterer når listen over stasjoner sist ble endret. Returverdien er et tall som pr. 2011-12-09 er 1319145491 og pr. 2012-05-28 er 1336420693. Mitt gjett er at dette er sekunder siden 1. januar 1970 ala det en finner på Linux, som kan konverteres til en leselig dato med perl -e 'print scalar(localtime(1319145491)), "\n"'. Den første verdien konverterer da til "Thu Oct 20 23:18:11 2011", mens den andre konverteres til "Mon May 7 21:58:13 2012".

GetXMLDatabase

echo password=XYZXYZXYZXYZX | POST http://www.bitfactory.no/Bensin/GetXMLDatabase.php

Henter ned listen med stasjoner på XML-format. Argumentet er password som muligens følger med i programpakken og eventuelt genereres av app-en. Nedlasting med samme passord flere ganger ser ikke ut til å fungere. Innholdet er ca. 1600 stasjoner, men manglet bensinstasjonen i min hjemkommune Ballangen da jeg sjekket, så den er ikke komplett. Formatet på selve listen ser slik ut (klippet):

<?xml version="1.0" encoding="UTF-8"?>
<STASJONSDATABASE>
<STASJON>
<NAME></NAME>
<ADDRESS></ADDRESS>
<ID>0</ID>
<LATITUDE>0.000000</LATITUDE>
<LONGITUDE>0.000000</LONGITUDE>
<COMPANY></COMPANY>
</STASJON>
<STASJON>
<NAME>Statoil Best Eidsvoll Verk</NAME>
<ADDRESS>Gamle Trondheimsvei 339 2074 Eidsvoll Verk</ADDRESS>
<ID>1</ID>
<LATITUDE>60.303902</LATITUDE>
<LONGITUDE>11.168100</LONGITUDE>
<COMPANY>Best</COMPANY>
</STASJON>
[...]
<STASJON>
<NAME>Esso Andenes</NAME>
<ADDRESS>Falcksgate 9, 8480 Andenes</ADDRESS>
<ID>1822</ID>
<LATITUDE>69.320999</LATITUDE>
<LONGITUDE>16.118700</LONGITUDE>
<COMPANY>Esso</COMPANY>
</STASJON>
</STASJONSDATABASE>

GetBanStatus

echo UDID=Android-123456789012345 | POST http://www.bitfactory.no/Bensin/ver1.1.GetBanStatus.php

Vet heller ikke helt hva dette API-kallet gjør. Navnet gjør at jeg tror den rapporterer om telefonen med UDID oppgitt som argument er bannlyst fra tjenesten. Bannlysning gjør antagelig at telefonen ikke kan brukes til å registrere bensinpriser, men det er også mulig det blokkerer for å se på priser. Eneste POST-argument er UDID, som ser ut til å være den unike ID-en til en mobil-enhet. Returnverdi er 'NO' for alle UDID-verdier jeg har testet. Gjetter på at alternativ returverdi er 'YES', men har ikke sett en slik verdi så langt.

PriserVedStasjoner

echo 'stasjoner=810,364&day=0' | POST http://www.bitfactory.no/Bensin/ver1.1.PriserVedStasjoner.php

Dette kallet henter ut priser registrert på en eller flere bensinstasjoner. Den tar to POST-argumenter, "stasjoner" som er kommaseparert liste over stasjons-IDer (numeriske), og "day" som bør settes til "0" for å få ut informasjon om priser. Usikker på hva day-tallet betyr, men mistenker det har med hvor langt tilbake i tid det skal hentes ut informasjon.

Resultatet som kommer tilbake er en kommaseparert liste for hver enkelt stasjon, med <br> som skillemarkør mellom hver stasjon. Ikke helt sikker på hva alle feltene er. Her er mine gjett:

FeltBeskrivelse
1Bensinstasjons-ID
2Pris for blyfri 95 oktan, flyttall med punktum som desimalskille.
3Klokkeslett da prisen ble oppdatert, format HH:MM.
4Telefon-ID på formen Android-123456789012345 eller hex-kodet streng/MD5-sum
5tall, uviss betydning. muligens relatert til day-verdien. Oppdatering 2012-06-02: Denne verdien er antall bekreftelser en gitt pris har fått.
6Pris for blyfri 98-oktan?
7samme som felt 3
8samme som felt 4
9samme som felt 5
10Pris for disel
11Samme som felt 3
12Samme som felt 4
13Samme som felt 5

En stasjonsoppføring består dermed av av bensinstasjons-ID og deretter tre blokker for 95-oktan bensin, 98-oktan bensin og disel.

PriserVedStasjon

echo 'id=736&day=0' | POST http://www.bitfactory.no/Bensin/ver1.1.PriserVedStasjon.php

Ser ut til å returnere informasjon for en enkelt bensinstasjon. Formatet er dato på formen "08_12_2011" for 2011-12-08, og noe som ser ut som samme format som fra PriserVedStasjoner. For stasjoner der intet er registrert returnerer den "NO RESULTS".

AllePriser

echo day=0 | POST http://www.bitfactory.no/Bensin/ver1.1.AllePriser.php

Returnere liste med av alle stasjoner det er registrert oppdaterte priser på siste 24 timer (eller er det fra ca. midnatt dagen før?). Returnerer "NO RESULTS" når listen er tom. Ellers returnerer den en dato på formen "Thursday_09_12_2011" fulgt av <br> og deretter en liste med stasjoner på samme format som PriserVedStasjoner.

Tags: drivstoffpriser, norsk.

Created by Chronicle v4.6