SL Reseplanerare 3

Beskrivning

Med detta API kan du få reseförslag från A till B inom Stockholms län med SLs trafik. I SLs reseplanerare finns även Waxholmsbolagets trafik. APIet kan användas för att beräkna reseförslag mellan valfri kombination av position och/eller stoppställe. APIet returnerar reseförslag från ”bästa matchning” av det som läggs in.

Reseplaneraren anropas med en GET-request per tjänst med UTF-8 url-kodade GET-parametrar.


I reseplaneraren finns det fyra olika funktioner som kan anropas:

  • Trip:
    Räknar ut en resa från en startpunkt till en destination. Dessa kan vara stations-id eller koordinater baserade på adresser eller ”intressepunkter.

     

  • JourneyDetail:
    Returnerar detaljerad information om en del av en resa med ett fordon.
    Den returnerar en lista på alla stop/stationer inklusive alla ankomst- och avgångstider med realtidsdata(om det finns tillgängligt).

     

  • Reconstruction:
    Används för att återskapa en kopia av en Trip med hjälp av ett rekonstruktionskontext. Resultatet kommer att vara en fullständig kopia givet att underliggande data inte har ändrats.

  • XSD:
    Returnerar en xsd för ovanstående service-svar.

URL

  • Trip:
    api.sl.se/api2/TravelplannerV3/trip.<FORMAT>?key=<DIN API NYCKEL>&parametrar

     

  • Journey detail:
    api.sl.se/api2/TravelplannerV3/journeydetail.<FORMAT>?key=<DIN API NYCKEL>&<referensparameter>

     

  • Recontruction:
    api.sl.se/api2/TravelplannerV3/Reconstruction.<FORMAT>?key=<DIN API NYCKEL>&<referensparameter>

     

  • XSD:
    api.sl.se/api2/TravelplannerV3/xsd.xml?key=<DIN API NYCKEL>

Format

Json eller Xml enligt ändelse till serviceanropet.

Trip

Parametrar

Namn

Beskrivning

Kommentar

lang

Språk (en/sv/de)                                           

Språk i svar, default de.

originId

 Internt id för startpunkt,

 

originExtId

Startpunkt, id

Kan antingen vara siteid eller ett alias, site eller akronym.
Exempel: 300109001, 9001, TCE

 

En startpunkt måste anges med ett av originId, originExtId eller orgiginCoordLat/originCoordLong

originCoordLat

 Latitud för startpunkt

Måste anges tillsammans med originCoordLong.

originCoordLong

Longitud för startpunkt

Måste anges tillsammans med originCoordLat.

destId

Intent id för destination.

 

destExtId

Destination, id.

Kan antingen vara siteid eller ett alias, site eller akronym.
Exempel: 300109001, 9001, TCE.

 

En destination måste anges med ett av originId, originExtId eller orgiginCoordLat/originCoordLong

destCoordLat

Latitud för destination

Måste anges tillsammans med destinationCoordLong.

destCoordLong

Longitud för destination

Måste anges tillsammans med destinationCoordLat

via

Lista av specification av stationer att passera.

Valfritt

Separeras av ; i följande format:

viaId|vänttid|status|produkter

 

-viaId, internt eller extert id på hållplats/station att passera

-vänttid, minuter att stanna på passerad hållplats/station (valfritt)

-status, ett av EXR (av- och påstigning krävs), NER (påstigning krävs ej), NXR (avstigning krävs ej), NEXR (av och påstigning krävs ej). Valfritt, EXT är default.

- produkter, trafikslag för via, se Produkt.

 

Ex1. via två hållplatser, 9001;9117

Ex2, via två hållpatser med 15 respektive 10 minuters väntetid, 9001|15;9117|10                                   

viaId

Id för station att passera

Valfritt

Enskilt id för en hållplats/station att resa via, ex 9001.

viaWaitTime

Vänttid för passerad station

Valfritt

Antal minuter som ska spenderas på via-station angiven med viaId.

avoid

Lista av stationer att undvika att resa via.

Valfritt

Separeras av ; i följande format:

avoidId|avoidStatus

 

-avoidId, internt eller externt id för hållplats/ station att undvika,

- avoidStatus, ett av NPAVO (passera ej), NCAVO (byt ej vid). Valfritt.

 

avoidID

Id för station att undvika

Valfritt

Internt eller externt id för hållplats/station att undvika för byten

changeTimePercent

Utökad bytestid, procentuell

(100-500)

Valfritt

Procentuell utökning av ursprungligt beräknad tid för att hantera ett byte. Ex, 200 dubblar tiden som systemet kommer använda för att resenären ska hinna med ett byte. Default 100.

minChangeTime

Minsta bytestid (min)

Valfritt

Minsta antal minuter som ska användas vid byten.

maxChangeTime

Högsta bytestid

Valfritt

Flest antal minuter som ska användas vid byten.

addChangeTime

Utökad bytestid

Valfritt

Antal minuter som läggs till beräknad bytestid.

maxChange

Max antal byten (0-11)

Högst antal byten på föreslagna resor.

date

Datum

ÅÅÅÅ-MM-DD

Valfritt.

Datum för resa. Default är dagens datum (servertid)

time

Klockslag

TT:MM

Valfritt

Klockslag för resa. Default är aktuellt klockslag (servertid)

searchForArrival

0 eller 1

Valfritt.

Om 1 används angivna date och time för ankomsttid istället för avgångstid.

numF

0-6

Valfritt

Min antal resor efter angiven starttid, default 4.

 

numF och numB tillsammans kan ej överstiga 6.

numB

0-6

Valfritt.

Min antal resor före angiven starttid, default 1.

 

numF och numB tillsammans kan ej överstiga 6.

products

Trafikslag, heltal

Valfritt

Kombinationsvärde av önskade trafikslag om inte alla ska användas vid utsökning av resor.

Bitmask enligt följande:

Pendeltåg (1)

Tunnelbana (2)

Lokalbana/spårvagn (4)

Buss (8)

Ej i bruk (16)

Ej i bruk (32)

Båt typ (64)

Närtrafik (128)

 

Värdes anges som heltalsvärdet av den kombinerade bitmasken, ex Buss och båt, 8+64 = 72

lines

Inkluderade filtrering av linjer.

Linje eller linjer, separerade med kommatecken som ska användas för att filtrera resultat, utropstecken används för exkludering av linjer.

 

Ex:
lines=55,122 (endast linje 55 och 122)
lines=!19 (Ej linje 19)

context

Tidigare eller senare resor

Valfritt.

Parameter som anger startpunkt för att söka senare eller tidigare resor. Värdet fås av resultatvärdet scrF eller scrB i ett anrop till trip-tjänsten. Se 2.4.2

poly

0 eller 1

Valfritt.

Anger om detaljerade färdvägar ska beräknas för resultaten. För beskrivning av polyline se 2.4.5. Default 0.

passlist

0 eller 1

Valfritt

Anger om hållplatser/stationer som passeras på resan ska hämtas. Default 0.

originWalk

0 eller 1 + detaljering

Valfritt

Anger om en resa ska kunna inledas med en gångsträcka. För delajering av avstånd kan min och max antal metrar och anges som 1,[minavstånd],[maxavstånd]

Default 1

 

Ex. 1,0,1000 Tillåt gång men maximalt 1000 meter.

destWalk

0 eller 1 + detaljering

Valfritt.

Som originWalk fast för destination.

 

 

 

Sökning efter tidigare eller senare resor

I resultat från trip kommer två utdataparametrar, scrB och scrF, som kan användas för att söka tidigare (scrB) eller senare (scrF) avgångar. Detta görs genom att skicka in samma sökning till trip med parametern context satt till värdet av den av de två som vill användas.

Anmärkningar

I sökresultaten finns olika typer av anmärkningar.

Fasta anmärkningar är inlagda som ”notes”. Fasta anmärkningar är anmärkningar kopplade till avgången i tidtabellen, som tex förhandsbokning på telefon.

Störningsmeddelanden ligger inlagda som ”Messages”.

Priser

Priser för en resa kommer i ”TariffResult”, priserna är angivna som heltal i ören. Exempelvis:

<TariffResult>

<fareSetItem desc="Standard Fare">

<fareItem name="Reskassa" price="3000" cur="SEK"/>

<fareItem name="Övriga försäljningsställen" price="4300" cur="SEK"/>

<fareItem name="Konduktör på Djurgårds- och Roslagsbanan" price="6000" cur="SEK"/>

<fareItem name="Reskassa" price="2000" cur="SEK"/>

<fareItem name="Övriga försäljningsställen" price="2900" cur="SEK"/>

<fareItem name="Konduktör på Djurgårds- och Roslagsbanan" price="4000" cur="SEK"/>

</fareSetItem>

</TariffResult>

Detaljerade färdvägar

Trip och journeyDetail kan leverera en detaljerad färdväg för resultatet i ”Polyline”, exempelvis:

<Polyline type="WGS84" delta="true" dim="2">

<crd>18061711</crd>

<crd>59331331</crd>

<crd>-90</crd>

<crd>-54</crd>

<crd>-1249</crd>

<crd>-979</crd>

</Polyline>

 

Koordinatlistan består av en startlongitud och latitud, och följande differenser från föregående punkt. Dvs i exemplet ovan en linje bestående av punkterna (longitud, latitud):
(18.061711,59.331331),(18.061621, 59.331227),(18.060462, 59.330248)

Realtid

Realtidsprognoser finns för närvarande för bussar, pendeltåg, Tvärbanan, Saltsjöbanan, Spårvagn 7, Roslagsbanan samt tunnelbanans blå och gröna linjer. Nockebybanan, tunnelbanans röda linje, båttrafik och Närtrafiken saknar i dagsläget realtidsprognoser.

Realtiden är en prognos, dvs, den är ungefärlig.

Om det finns realtid så anges detta i separata fält. För realtidstider i reseförslaget så läggs ”rtTime” och ”rtDate” till i svaret. De gamla fälten ”time” och ”date” är kvar så att man vet vad det ändrats från/till.

I denna version av api:et är realtid inte parameterstyrt utan levereras alltid om data finns tillgängligt.

Svarsformat

API:et kan returnera både xml och json.
Json-innehållet är automatiskt konverterat från xml enligt följande regler:

  • Elementnamn blir objektegenskaper
  • Text (PCDATA) blir en objektegenskap med namnet "$"
    <a>foo</a> blir { "a": { "$" : "foo" } }
  • Nestlade element blir nestlade egenskaper:
    <a><b>foo</b><c>foo</c></a>
    blir
    { "a": { "b" : { "$": "foo" }, "c": { "$": "foo"} } }
  • Om det finns multipla element med samma namn så översätts det till en json array ex:
    <a><b>foo1</b><b>foo2</b></a>
    blir
    { "a": { "b" : [{"$": foo1" }, {"$": "foo2" }] } }
  • Attributnamn blir objektegenskaper
    <a atb="foo1">foo2</a>
    blir
    { "a": { "atb" : "foo1", "$" : "foo2" } }

 

Följande exempel visar ett svar på anrop till trip i xml och dess motsvarighet i json:

XML:

Triplist XML

 

JSON:

 

Triplist JSON 

Svarsstruktur


 

I nedan tabell beskrivs den xml struktur som finns. Vissa uppenbara attribut är inte med då det blir väldigt mycket annars, som t.ex. Lat och Lon för att ge en lättare överblick av det som är mindre självklart.
För mer information om olika attribut och element så finns också xsd’n hafasRestTrip.xsd.

Exempel förklaring av nedan struktur i tabellen:
element1/element2 => element2 är ett underelement till element1.
element1.attribut1 => attribut1 är ett attribut till element1.

Element

Notes

Element Error

Element som innehåller felbeskrivning

Complex type Polyline

Detaljerad färdväg, om poly=1 angivits.

Element Product

Complex type ProductType

Produktkontext, möjliggör åtkomst till intern data.

Ex.

<Product name=" " admin="100017" operatorCode="SL" operator="Storstockholms Lokaltrafik" num="11297" line="17" catOutS="MET" catOutL="TUNNELBANA " catOut="METRO " catIn="MET" catCode="1"/>

Element JourneyDetailRef

Referens till journey detail för ett detta leg-elementet.

Simple type PrognosisType

Innehåller typ av prognos. Om den rapporterades in av extern part, räknades ut, eller rättades av systemet.

Element Stops

En lista av journey stops/stations, om passlist=1 angivits.

Complex type StopType

 

Elementet stop innehåller namnet, route index, latitude, longitude, departure time/date, arrival time/date, track, realtidsdata för ankomst och avgång sampt track.

Element Messages

Innehåller en lista av meddelanden för denna trip.

Element Names

Lists av journey names

Element JourneyStatus

Innehåller status för Journey.

Element TripList

 

Rotelement, innehåller en lista på alla Trips vid anrop till trip. Om ett större fel har inträffat under anrop så innehåller attributen errorCode och errortext felbeskrivning.

Element Trip

Trip-objektet innehåller en lista med Leg-objekt med den uträknade resan.

Element LegList

Innehåller alla Leg-element för en Trip.

Element Leg

 

Leg-objektet är en del av en resa. Det kan vara antingen en gångväg, cykel eller bilväg eller oftast en resa med bus, tåg, eller annat typ av transportmedel.

Element Origin

Innehåller namn, typ, rout index, realtidsdata för startpunkten för denna resa.

Element Destination

Innehåller namn, typ, rout index, realtidsdata för destinationen för denna resa.

Element GisRef

Referens till en specifik route i ett Leg-element.

Genererad exempeldata

Exempeldata

JourneyDetail

Journeydetail används för att få detaljerad information kring en resa/delresa (Leg)

Detta bygger på att man först anropat trip.

I svaret från trip får man en referens, t.ex.

<JourneyDetailRef ref="1|3598|0|74|13062017"/>

Denna referens använder man när man ska anropa Journeydetail för den specifika resan. Hela linjesträckningen för angiven resa returneras, önskar man bara information om hållplatser i den del av resa som en sökning med trip ger rekomenderas att sätta passlist=1 i trip. Detta är en utökning från api-version 2.

Parametrar

Namn

Beskrivning

Kommentar

id

Referensen från Trip, se ovan

It may be necessary to escape the | character by its URL encoding %7C.

date

ÅÅÅÅ-MM-DD

Valfritt

Ger motsvarande resa annan dag, om möjligt

poly

0 eller 1

Valfritt.

Anger om detaljerade färdvägar ska beräknas för resultaten. Se beskrivning av polyline. Default 0.

 

Exempel:
api.sl.se/api2/TravelplannerV3/journeydetail.<FORMAT>?key=<DIN API NYCKEL>&id=1|3598|0|74|13062017

Realtid

Om det finns realtid så anges detta i separata extra fält. För realtidstider i journeyDetail så läggs ”rtArrTime”, ”rtArrDate”, ”rtDepTime” och ”rtDepDate” till i svaret. De gamla fälten ”arrTime”, ”arrDate”, ”depTime” och ”depDate” är kvar så att man vet vad det ändrats från/till.

1Svarsstruktur

I nedan tabell beskrivs den xml struktur som finns. Vissa uppenbara attribut är inte med då det blir väldigt mycket annars, som t.ex. Lat och Lon för att ge en lättare överblick av det som är mindre självklart.
 

Exempel förklaring av nedan struktur i tabellen:
element1/element2 => element2 är ett underelement till element1.
element1.attribut1 => attribut1 är ett attribut till element1.

Namn

Datatyp

Beskrivning

JourneyDetail

Element

Rootelement.

JourneyDetail/Notes

Element

Innehåller noteringar att visas för resan.

JourneyDetail/Stops

Lista av element

Lista på hållplatser för den här resan.

Stops/Stop

Element

Stop innehåller namn på hållplats, route index, latitud, longitud, avgångens datum och tid, ankomstens datum och tid.

Stop.id

Attribute

Id för angiven plats i hållplatslistan. Kan användas för vidare resa från den punkten.

Stop.routeIdx

Attribute

Denna används i samband med routeIdx som finns i Trip svaret i en sökning, för att veta vilken del av listan som är aktuell för resan.

JourneyDetail/Directions

Lista av element

Lista på riktingar

Directions/Direction

Element

Riktningsinformation.

JourneyDetail/Types

Lista av element

Lista av restyper.

JourneyDetail/Names

Lista av element

 

 

Names/Name

Element

Innehåller resans namn.

JourneyDetail/Messages

Lista av element

Innehåller en lista med realtidsmeddelanden att visa.

Polyline

Element

Detaljerad färdväg, om poly=1 angivits.

 

 

 

 

 

 

Reconstruction

För att återskapa en resa framsökt via tjäsnten trip kan tjänsten reconstruction användas (exempelvis för delningsfunktion eller liknande)

I svaret från trip fås:
<Trip idx="0" ctxRecon="T$A=1@O=T-Centralen@L=400101052@a=128@$A=1@O=Slussen@L=400101012@a=128@$201706140859$201706140902$ $" checksum="774B67E9_4" tripId="C-0" duration="PT3M">

Värdet i ctxRecon är det som används som input till reconstruction

Parametrar

Namn

Beskrivning

Description

ctx

 

Värdet i ctxRecon som fås i svaret från trip.

poly

0 eller 1

Valfritt.

Anger om detaljerade färdvägar ska beräknas för resultaten. Default 0.

date

Datum

ÅÅÅÅ-MM-DD

Valfritt

  1. rekonstruera en resa på specificerat datum, om möjligt.

 

Exempel:

api.sl.se/api2/TravelplannerV3/reconstruction.<FORMAT>?key=<DIN API NYCKEL>& ctx=T%24A%3D1%40O%3DT-Centralen%40L%3D400101052%40a%3D128%40%24A%3D1%40O%3DSlussen%40L%3D400101012%40a%3D128%40%24201706140859%24201706140902%24%20%24

Svarsstruktur

Svaret från reconstruction är detsamma som för resultatet från trip, med skillnad att det bara är en resa med i resultatet.

XSD

Returnerar en xsd innehållandes definioner för alla de ingående delarna av svarsstrukturerna för tjänsterna i SL Reseplanerare 3.

Parametrar

Inga specifika parametrar används för denna tjänst

 

Exempel:

api.sl.se/api2/TravelplannerV3/xsd.xml?key=<DIN API NYCKEL>.xsd

Felmeddelanden

Statuskod

Meddelande

1001

problem with request: Key is undefined

Nyckel har ej skickats med.

1002

problem with request: Key is invalid

Nyckel är ogiltig

1003

Invalid api

Ogiltigt api

1004

 

problem with request: This api is currently not available for keys with priority above 2

1005

Nyckel finns, men ej för detta api

problem with request: Invalid api for key

1006

To many requests per minute

För många anrop per minut, för den profil som används

1007

To many requests per month

För många anrop per månad, för den profil som används