Trafiklab - ansluta till ett API

Vi ska nu titta på hur man kan kontakta ett API hos Trafiklab. För detta krävs att du registrerat dig som person samt att du skapat ett projekt hos dem. I exemplen kommer vi att använda oss av "SL Platsuppslag", så registrera att ditt projekt använder sig av detta API och hämta ut en API-nyckel. Om du inte har gjort dessa saker, så passa på att göra det nu. Då blir det enklare att följa med i exemplen och du kan testa saker för dig själv.

"SL Platsuppslag"

"SL Platsuppslag" är ett API som kan ge oss information om en plats genom att ange platsens namn (eller delar av platsens namn). Man kan söka efter hållplatser, adresser och platser. Om du går in under dokumentationen för "SL Platsuppslag", så ser du att det finns ett enda API-anrop som vi kan utföra mot detta API. Detta är ett REST-anrop och anropet utformas följdaktligen som en URL.

Anrops-URL

En anrops-URL för detta API ska anges enligt följande mall (för korthetens skulle, utelämnar vi de parametrar som inte är obligatoriska):

api.sl.se/api2/typeahead.<FORMAT>?key=<DIN NYCKEL>&searchstring=<SÖKORD>

Alla bitar som anges i formen "<NÅNTING>" är parametrar som du behöver fylla i med information som gäller för just ditt anrop. Vi går igenom vad dessa ska sättas till:

Parametrar

<FORMAT>: Vilken typ av svars data vill du ha? JSON eller XML.
<DIN NYCKEL>: Här anger du din API-nyckel.
<SÖKORD>: Söksträngen som anger vad du vill söka efter.

Följande går att sätta, men de är inte obligatoriska:

<ENDAST STATIONER>: Vill du enbart söka på stationsnamn. Kan sättas true eller false. Defaultvärdet är false.
<MAX ANTAL SVAR>: Hur många svar vill du maximalt erhålla. 50 är max. Defaultvärdet är 10.

Exempel

En fullständig söknings-URL skulle alltså kunna tänkas se ut så här (förutom att det är fejkad API-nyckel:

https://api.sl.se/api2/typeahead.json?key=BADA551337&searchstring=gata

Prova att klippa ut ovanstående URL, klistra in den i URL-fältet på en webbläsare och ersätt BADA551337 med din API-nyckel. Tryck på enter och du bör få svar ifrån servern. Svaret du erhåller visar alla platser som innehåller strängen "gata". Svårare än så är det inte att kontakta detta API! De flesta REST-API:er har den fördelen att man enkelt kan testa dem direkt i sin webbläsare.

Exempelresultat

Vi modifierade exempelt ovan så att enbart en resultat ska returneras. När vi provkörde fick vi följande resultat (omformaterat för att bli mer läsbart):

{
   "StatusCode":0,
   "Message":null,
   "ExecutionTime":0,
   "ResponseData":[
      {
         "Name":"Gatan (Ekerö)",
         "SiteId":"3254",
         "Type":"Station",
         "X":"17674411",
         "Y":"59357481"
      }
   ]
}

Om du själv vill snygga till JSON-kod så den blir mer lättläst för människor kan du prova den här resursen; JSON Formatter & Validator.

Tolkning av resultat

Vi ska ta och gå igenom svaret och tolka vad vi fått för data.

StatusCode: Svarskoden talar om huruvida API-anropet gick bra eller ej. 0 betyder att allt gick bra.
Message: Meddelandet kan innehålla saker som eventuella felmeddelanden. I vårt fall fick vi bara null, dvs ingenting.
ExecutionTime: Ett rätt meningslös svarsvärde. Vi bryr oss inte i hur lång tid det tog för dem att generera ett svar. Speciellt inte när det i vårt fall var 0.
ResponseData: Här kommer till sist den viktiga biten - själva svarsdatan. Detta är en array som kan innehålla flera objekt. I detta fall hade vi angivit 1 som antal och vi får därför bara ett svarsobjekt.

Tolkning av svarsobjektet

Vi behöver även gå igenom vad svarsobjektet innehåller. Där har vi följande information:

Name: Namnet på den plats API:et fann åt oss.
SiteId: ID för hållplatsområdet där denna plats återfinns.
Type: Vilken typ av plats detta är, en station i vårt fall.
X: X-koordinat till platsen.
Y: Y-koordinat till platsen.

Nästa aktivitet

I nästa aktivitet ska vi ta och skapa en liten applikation som möjliggör att vi kan skriva in sökord, söka och få datan presenterad på ett lite bättre vis.

Trafiklab - enkel SPA