blog/data/2012-05-28-bensinpris.txt

   1 Title: Litt informasjon om Bitfactorys Bensinpris-API
   2 Tags: norsk, drivstoffpriser
   3 Date: 2012-05-28 23:55
   4
   5 <p>I fjor lanserte Bitfactory en
   6 <a href="http://www.bitfactory.no/bensinpris.html">mobilapp for å få
   7 tilgang til bensinpriser</a> på landets bensinstasjoner ved å samle
   8 inn prisene på dugnad ved hjelp av mobilapp-ens brukere.
   9 Informasjonen app-ens brukere har samlet inn har så langt kun vært
  10 tilgjengelig for brukerne av app-ene, og API for å hente ut
  11 informasjonen fra andre plattformer har ikke vært publisert.  Da
  12 løsningen kom spurte jeg utviklerne om de kunne publisere
  13 API-dokumentasjon og de skulle se på saken, men det har ikke skjedd så
  14 langt.  Jeg antar de har vært for travelt opptatt til å publisere
  15 API-dokumentasjon.</p>
  16
  17 <p>Utrolig nok er det i følge
  18 <a href="http://www.dn.no/energi/article2194526.ece">Dagens
  19 Næringsliv</a> og
  20 <a href="http://www.finnmarkdagblad.no/nyheter/article5323140.ece">Finnmark
  21 Dagblad</a> bensinstasjoner som nekter å oppgi prisene sine på
  22 telefon, slik at det ikke finnes en fornuftig måte å få tak i prisene
  23 på uten å samle dem inn på stedet.  Flere har dugnader på gang for å
  24 samle inn prisinformasjon om bensin, men så vidt jeg kan se er det kun
  25 <a href="http://www.dinside.no/php/oko/bensin/vis_prisliste.php">dinside.no</a>
  26 og Bitfactorys App som får regelmessige oppdateringer.  Dinsides
  27 oversikt er tilgjengelig på web for de som vil følge med, mens
  28 bitfactorys informasjon ikke er like enkelt tilgjengelig.<p>
  29
  30 <p>Jeg tok meg derfor litt tid for å revers-utvikle protokollen for
  31 Bitfactorys mobilapp for å gjøre den innsamlede informasjonen mer
  32 tilgjengelig for flere.  Protokollen bruker HTTP og normal
  33 forms-notasjon for POST.  Jeg lot en telefon koble seg til mitt
  34 trådløsnett, og satte opp tcpdump til å samle all trafikken mot
  35 www.bitfactory.no, og deretter tittet på alle HTTP-kallene ved hjelp
  36 av wireshark.  Her er API-kallene jeg har identifisert så langt.</p>
  37
  38 <p><b>stasjonsDatabaseUpdateStamp</b></p>
  39
  40 <p><tt>GET http://www.bitfactory.no/Bensin/ver1.1.stasjonsDatabaseUpdateStamp</tt></p>
  41
  42 <p>Vet ikke helt hva dette API-kallet gjør, men navnet gjør at jeg
  43 tror den rapporterer når listen over stasjoner sist ble endret.
  44 Returverdien er et tall som pr. 2011-12-09 er 1319145491 og
  45 pr. 2012-05-28 er 1336420693.  Mitt gjett er at dette er sekunder
  46 siden 1. januar 1970 ala det en finner på Linux, som kan konverteres
  47 til en leselig dato med <tt>perl -e 'print
  48 scalar(localtime(1319145491)), "\n"'</tt>.  Den første verdien
  49 konverterer da til "Thu Oct 20 23:18:11 2011", mens den andre
  50 konverteres til "Mon May 7 21:58:13 2012".</p>
  51
  52 <p><b>GetXMLDatabase</b></p>
  53
  54 <p><tt>echo password=XYZXYZXYZXYZX | POST http://www.bitfactory.no/Bensin/GetXMLDatabase.php</tt></p>
  55
  56 <p>Henter ned listen med stasjoner på XML-format.  Argumentet er
  57 password som muligens følger med i programpakken og eventuelt
  58 genereres av app-en.  Nedlasting med samme passord flere ganger ser
  59 ikke ut til å fungere.  Innholdet er ca. 1600 stasjoner, men manglet
  60 bensinstasjonen i min hjemkommune Ballangen da jeg sjekket, så den er
  61 ikke komplett.  Formatet på selve listen ser slik ut (klippet):</p>
  62
  63 <p><pre>
  64 &lt;?xml version="1.0" encoding="UTF-8"?&gt;
  65 &lt;STASJONSDATABASE&gt;
  66 &lt;STASJON&gt;
  67 &lt;NAME&gt;&lt;/NAME&gt;
  68 &lt;ADDRESS&gt;&lt;/ADDRESS&gt;
  69 &lt;ID&gt;0&lt;/ID&gt;
  70 &lt;LATITUDE&gt;0.000000&lt;/LATITUDE&gt;
  71 &lt;LONGITUDE&gt;0.000000&lt;/LONGITUDE&gt;
  72 &lt;COMPANY&gt;&lt;/COMPANY&gt;
  73 &lt;/STASJON&gt;
  74 &lt;STASJON&gt;
  75 &lt;NAME&gt;Statoil Best Eidsvoll Verk&lt;/NAME&gt;
  76 &lt;ADDRESS&gt;Gamle Trondheimsvei 339 2074 Eidsvoll Verk&lt;/ADDRESS&gt;
  77 &lt;ID&gt;1&lt;/ID&gt;
  78 &lt;LATITUDE&gt;60.303902&lt;/LATITUDE&gt;
  79 &lt;LONGITUDE&gt;11.168100&lt;/LONGITUDE&gt;
  80 &lt;COMPANY&gt;Best&lt;/COMPANY&gt;
  81 &lt;/STASJON&gt;
  82 [...]
  83 &lt;STASJON&gt;
  84 &lt;NAME&gt;Esso Andenes&lt;/NAME&gt;
  85 &lt;ADDRESS&gt;Falcksgate 9, 8480 Andenes&lt;/ADDRESS&gt;
  86 &lt;ID&gt;1822&lt;/ID&gt;
  87 &lt;LATITUDE&gt;69.320999&lt;/LATITUDE&gt;
  88 &lt;LONGITUDE&gt;16.118700&lt;/LONGITUDE&gt;
  89 &lt;COMPANY&gt;Esso&lt;/COMPANY&gt;
  90 &lt;/STASJON&gt;
  91 &lt;/STASJONSDATABASE&gt;
  92 </pre></p>
  93
  94 <p><b>GetBanStatus</b></p>
  95
  96 <p><tt>echo UDID=Android-123456789012345 | POST http://www.bitfactory.no/Bensin/ver1.1.GetBanStatus.php</tt></p>
  97
  98 <p>Vet heller ikke helt hva dette API-kallet gjør.  Navnet gjør at jeg
  99 tror den rapporterer om telefonen med UDID oppgitt som argument er
 100 bannlyst fra tjenesten.  Bannlysning gjør antagelig at telefonen ikke
 101 kan brukes til å registrere bensinpriser, men det er også mulig det
 102 blokkerer for å se på priser.  Eneste POST-argument er UDID, som ser
 103 ut til å være den unike ID-en til en mobil-enhet.  Returnverdi er 'NO'
 104 for alle UDID-verdier jeg har testet.  Gjetter på at alternativ
 105 returverdi er 'YES', men har ikke sett en slik verdi så langt.</p>
 106
 107 <p><b>PriserVedStasjoner</b></p>
 108
 109 <p><tt>echo 'stasjoner=810,364&day=0' | POST http://www.bitfactory.no/Bensin/ver1.1.PriserVedStasjoner.php</tt></p>
 110
 111 <p>Dette kallet henter ut priser registrert på en eller flere
 112 bensinstasjoner.  Den tar to POST-argumenter, "stasjoner" som er
 113 kommaseparert liste over stasjons-IDer (numeriske), og "day" som bør
 114 settes til "0" for å få ut informasjon om priser.  Usikker på hva
 115 day-tallet betyr, men mistenker det har med hvor langt tilbake i tid
 116 det skal hentes ut informasjon.</p>
 117
 118 <p>Resultatet som kommer tilbake er en kommaseparert liste for hver
 119 enkelt stasjon, med &lt;br&gt; som skillemarkør mellom hver stasjon.
 120 Ikke helt sikker på hva alle feltene er.  Her er mine gjett:</p>
 121
 122 <p><table>
 123 <tr><ht>Felt</ht><ht>Beskrivelse</ht></tr>
 124 <tr><td>1</td><td>Bensinstasjons-ID</td></tr>
 125 <tr><td>2</td><td>Pris for blyfri 95 oktan, flyttall med punktum som desimalskille.</td></tr>
 126 <tr><td>3</td><td>Klokkeslett da prisen ble oppdatert, format HH:MM.  </td></tr>
 127 <tr><td>4</td><td>Telefon-ID på formen Android-123456789012345 eller hex-kodet streng/MD5-sum</td></tr>
 128 <tr><td>5</td><td>tall, uviss betydning.  muligens relatert til day-verdien. <b>Oppdatering 2012-06-02: Denne verdien er antall bekreftelser en gitt pris har fått.</td></tr>
 129 <tr><td>6</td><td>Pris for blyfri 98-oktan?</td></tr>
 130 <tr><td>7</td><td>samme som felt 3</td></tr>
 131 <tr><td>8</td><td>samme som felt 4</td></tr>
 132 <tr><td>9</td><td>samme som felt 5</td></tr>
 133 <tr><td>10</td><td>Pris for disel</td></tr>
 134 <tr><td>11</td><td>Samme som felt 3</td></tr>
 135 <tr><td>12</td><td>Samme som felt 4</td></tr>
 136 <tr><td>13</td><td>Samme som felt 5</td></tr>
 137 </table></p>
 138
 139 <p>En stasjonsoppføring består dermed av av bensinstasjons-ID og
 140 deretter tre blokker for 95-oktan bensin, 98-oktan bensin og
 141 disel.</p>
 142
 143 <p><b>PriserVedStasjon</b></p>
 144
 145 <p><tt>echo 'id=736&day=0' | POST http://www.bitfactory.no/Bensin/ver1.1.PriserVedStasjon.php</tt></p>
 146
 147 <p>Ser ut til å returnere informasjon for en enkelt bensinstasjon.
 148 Formatet er dato på formen "08_12_2011" for 2011-12-08, og noe som ser
 149 ut som samme format som fra PriserVedStasjoner.  For stasjoner der
 150 intet er registrert returnerer den "NO RESULTS".</p>
 151
 152 <p><b>AllePriser</b></p>
 153
 154 <p><tt>echo day=0 | POST http://www.bitfactory.no/Bensin/ver1.1.AllePriser.php</tt></p>
 155
 156 <p>Returnere liste med av alle stasjoner det er registrert oppdaterte
 157 priser på siste 24 timer (eller er det fra ca. midnatt dagen før?).
 158 Returnerer "NO RESULTS" når listen er tom.  Ellers returnerer den en
 159 dato på formen "Thursday_09_12_2011" fulgt av &lt;br&gt; og deretter
 160 en liste med stasjoner på samme format som PriserVedStasjoner.</p>