blog/draft/2011-12-bensinpris.txt

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