SIRI - Stop monitoring

SM interface provides realtime view into arrivals and departures of single stop. If arriving vehicle is monitored, backend calculates and updates current estimates of vehicle's arrival time.

Estimates are solely based on vehicle's current physical location on route. Because there is possible unexpected external things affecting, the estimates might vary.

There might be traffic jams or sudden obstacles on road.
There might be problems in mobile network connectivity preventing updates of vehicles location.
Traffic lights, possibly delay or rush because of vehicle hitting green or red wave.
Busy hours, amount of passengers gettin in and out

The estimates might gather rapidly large delays if there is for example temporary slow down on road, but return as rapidly back to normal when obstacle is passed. Because these unexpected issues cannot practically be eliminated from estimates, you application should not make promises about time of vehicles' arrivals but instead eagerly signal uncertainity (ie. lose precision) if average difference between estimates shows large deviation.

Stop listing

Base url itself provides list of known stops.

http://data.foli.fi/siri/sm

{
    "4": {
        "stop_name": "Turun linna"
    },
    "578": {
        "stop_name": "Patterinhaka"
    },
    /* ... */
    "5400": {
        "stop_name": "Liedon ja Tarvasjoen raja VT10"
    }
}

Properties of SM reply

Attributes

Message level attributes

sys Stop monitoring-messages are identified by label "SM". (Vehicle-monitoring -messages contain "VM")
status "OK", whether provided data can be considered valid and usable. If there's no connection to SIRI backend or it produces not sensible data, status is "NO_SIRI_DATA".
servertime unix timestamp representing moment when reply is generated. To reduce load on backend, the frontend server cahces replies for 15-30 seconds depending of type of stop.
result arrivals in order of their arrival.

Vehicle attributes

recordedattime unix-timestamp representing last update from vehicle
monitored true, if vehicle produces real time information
latitude, longitude estimated coordinates (if known) of arriving vehicle expressed as WGS-84 coordinates
originaimeddeparturetime planned departure from origin of trip
originaimedarrivaltime planned arrival to terminus
destinationdisplay display text on bus frontplate
aimedarrivaltime planned arrival to this stop
expectedarrivaltime estimated real arrival time to this stop
aimeddeparturetime planned departure from this stop
expecteddeparturetime estimated real departure time from this stop

Extra options to URL

Data-url vithout extra attributes returns compact machine readable JSON reply. You shoud use that.
/pretty -attribute formats reply to visually more human readable. The content is same than without attribute.
/format -attribute translates unix timestamps into human readable times.
/xml -attribute returns original SIRI's XML reply

Example message

http://data.foli.fi/siri/sm/4/pretty

{
    "sys": "SM",
    "status": "OK",
    "servertime": 1432453114,
    "result": [
        {
            "recordedattime": 1432453110,
            "lineref": "15",
            "monitored": true,
            "latitude": 60.454883,
            "longitude": 22.2696,
            "originaimeddeparturetime": 1432451700,
            "destinationaimedarrivaltime": 1432455180,
            "destinationdisplay": "Kakskerta Brinkhallin kautta",
            "aimedarrivaltime": 1432453320,
            "expectedarrivaltime": 1432453229,
            "aimeddeparturetime": 1432453500,
            "expecteddeparturetime": 1432453409,
            "delay": -91
        },
        {
            "recordedattime": 1432453110,
            "lineref": "61",
            "monitored": true,
            "latitude": 60.457017,
            "longitude": 22.268633,
            "originaimeddeparturetime": 1432452000,
            "destinationaimedarrivaltime": 1432454160,
            "destinationdisplay": "Ilpoinen",
            "aimedarrivaltime": 1432453260,
            "expectedarrivaltime": 1432453308,
            "aimeddeparturetime": 1432453500,
            "expecteddeparturetime": 1432453500
        },
        {
            "recordedattime": 1432453110,
            "lineref": "56",
            "monitored": true,
            "latitude": 60.473783,
            "longitude": 22.3123,
            "originaimeddeparturetime": 1432452900,
            "destinationaimedarrivaltime": 1432455180,
            "destinationdisplay": "Haarla",
            "aimedarrivaltime": 1432454040,
            "expectedarrivaltime": 1432454040,
            "aimeddeparturetime": 1432454400,
            "expecteddeparturetime": 1432454400
        },
        {
            "recordedattime": 1432453110,
            "lineref": "55",
            "monitored": false,
            "originaimeddeparturetime": 1432454700,
            "destinationaimedarrivaltime": 1432457220,
            "destinationdisplay": "Haarla",
            "aimedarrivaltime": 1432455840,
            "expectedarrivaltime": 1432455840,
            "aimeddeparturetime": 1432456200,
            "expecteddeparturetime": 1432456200
        },
        /* ...... */
        {
            "recordedattime": 1432453110,
            "lineref": "55",
            "monitored": false,
            "originaimeddeparturetime": 1432461900,
            "destinationaimedarrivaltime": 1432464540,
            "destinationdisplay": "Haarla",
            "aimedarrivaltime": 1432463100,
            "expectedarrivaltime": 1432463100,
            "aimeddeparturetime": 1432463400,
            "expecteddeparturetime": 1432463400
        }
    ]
}