ITSFactory siriaccess developerguide

ITS Factory supports following SIRI modules:

• Vehicle Monitoring, VM (Currently available)
• General Messages, GM (Currently available)

SIRI Vehicle Monitoring

SIRI vehicle monitoring, or VM, offers real-time location related information on monitored vehicles (buses). A client can request information on all active vehicles or limit its request to certain bus line or vehicle. The data contains the current state of vehicle transit, history data is not currently available.

URLs:

• http://data.itsfactory.fi/siriaccess/vm/json (SIRI JSON documents over HTTP GET)

Requests

To communicate with Vehicle Monitoring URL, the client must send XML formatted SIRI requests via HTTP POST. The server will response with proper SIRI XML response. SIRI Subscriptions are not supported by this URL. A minimalist request to access all vehicle monitoring data is as follows:

<?xml version="1.0" encoding="UTF-8"?>
<Siri xmlns="http://www.siri.org.uk/siri" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" version="1.3" 
  xsi:schemaLocation="http://www.kizoom.com/standards/siri/schema/1.3/siri.xsd">
	<ServiceRequest>
			<VehicleMonitoringRequest version="1.3">
				<VehicleMonitoringRef>VEHICLES_ALL</VehicleMonitoringRef>
			</VehicleMonitoringRequest>
	</ServiceRequest>
</Siri>

To access vehicle monitoring data for certain line, a minimalist request would be:

<?xml version="1.0" encoding="UTF-8"?>
<Siri xmlns="http://www.siri.org.uk/siri" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" version="1.3" 
	xsi:schemaLocation="http://www.kizoom.com/standards/siri/schema/1.3/siri.xsd">
	<ServiceRequest>
			<VehicleMonitoringRequest version="1.3">
				<LineRef>23</LineRef>
			</VehicleMonitoringRequest>
	</ServiceRequest>
</Siri>

To access vehicle monitoring data for certain vehicle, a minimalist request would be:

<?xml version="1.0" encoding="UTF-8"?>
<Siri xmlns="http://www.siri.org.uk/siri" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" version="1.3" 
	xsi:schemaLocation="http://www.kizoom.com/standards/siri/schema/1.3/siri.xsd">
	<ServiceRequest>
			<VehicleMonitoringRequest version="1.3">
				<VehicleRef>TKL_123</VehicleRef>
			</VehicleMonitoringRequest>
	</ServiceRequest>
</Siri>

Responses

Following response is an example of vehicle monitoring data collected from vehicle (bus) TKL_248 operating on line 30.

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<Siri xmlns="http://www.siri.org.uk/siri" xmlns:ns2="http://www.ifopt.org.uk/acsb" xmlns:ns3="http://www.ifopt.org.uk/ifopt" 
	xmlns:ns4="http://datex2.eu/schema/1_0/1_0" version="1.3">
	<ServiceDelivery>
		<ResponseTimestamp>2013-04-24T09:41:42.486+03:00</ResponseTimestamp>
		<ProducerRef>IJ2010</ProducerRef>
		<Status>true</Status>
		<MoreData>false</MoreData>
		<VehicleMonitoringDelivery version="1.3">
			<ResponseTimestamp>2013-04-24T09:41:42.486+03:00</ResponseTimestamp>
			<Status>true</Status>
			<VehicleActivity>
				<RecordedAtTime>2013-04-24T09:41:42.173+03:00</RecordedAtTime>
				<ValidUntilTime>2013-04-24T09:42:12.173+03:00</ValidUntilTime>
				<MonitoredVehicleJourney>
					<LineRef>30</LineRef>
					<DirectionRef>2</DirectionRef>
					<FramedVehicleJourneyRef>
						<DataFrameRef>2013-04-24</DataFrameRef>
						<DatedVehicleJourneyRef>0935</DatedVehicleJourneyRef>
					</FramedVehicleJourneyRef>
					<OperatorRef/>
					<OriginName xml:lang="fi">Keskustori M</OriginName>
					<DestinationName xml:lang="fi">Etelä-Hervanta</DestinationName>
					<Monitored>true</Monitored>
					<VehicleLocation>
						<Longitude>23.77120000000000032969182939268648624420166015625</Longitude>
						<Latitude>61.4919000000000011141310096718370914459228515625</Latitude>
					</VehicleLocation>
					<Bearing>148.0</Bearing>
					<Delay>P0Y0M0DT0H2M58.000S</Delay>
					<VehicleRef>TKL_248</VehicleRef>
				</MonitoredVehicleJourney>
			</VehicleActivity>
		</VehicleMonitoringDelivery>
	</ServiceDelivery>
</Siri>

The response follows SIRI standards, so you can get the whole picture from there, however here we explain few key fields:

• LineRef specifies the line where the bus is currently operating.
• DirectionRef sepecifies the direction the bus is travelling on the line. 1 = from origin stop to destination stop, 2= from destination stop back to origin stop.
• DataFrameRef specifies the date when the vehicle started from the origin or destination stop (depending on the DirectionRef)
• DatedVehicleJorneyRef specifies the time when the vehicle started from the origin or destination stop (depending on the DirectionRef)
• OriginName specifies the name of the stop where the vehicle started
• DestinationName specifies the name of the stop where the bus is heading to
• Latitude and Longitude specifies the map position of the vehicle at the time of the response
• Bearing specifies the direction the vehicle is travelling
• Delay specifies the relative time the vehicle is behind or ahead of its planned schedule
• VehicleRef uniquely identifies the monitored vehicle

SIRI JSON documents over HTTP GET

NEW!

• Please note! This SIRI VM JSON interface is superceeded by http://wiki.itsfactory.fi/index.php/Journeys_API#Vehicle_Activity . This interface will remain in use until it is eventually removed in the future. SIRI GM interface continues its operation.

JSON access responds to HTTP GET requests and returns JSON formatted textual data. The data itself is structured and named like standard SIRI XML responses (it is just converted from SIRI XML to JSON notation). This allows the client avoid XML request parsing which is typically cumbersome for example to JavaScript clients.

Requests

To access the SIRI vehicle monitoring client must send HTTP GET requests to http://data.itsfactory.fi/siriaccess/vm/json

The URL supports following parameters

• lineRef=<string>
• vehicleRef=<string>
• indent=<yes|no>

Url examples

• http://data.itsfactory.fi/siriaccess/vm/json returns data for all vehicles
• http://data.itsfactory.fi/siriaccess/vm/json?lineRef=22 returns data for all vehicles currently operating on specified line
• http://data.itsfactory.fi/siriaccess/vm/json?vehicleRef=paunu_155 returns data for specified vehicle
• http://data.itsfactory.fi/siriaccess/vm/json?indent=yes returns data in human readable format, indent parameter works also in conjunction with lineRef and vehicleRef parameters, for example http://data.itsfactory.fi/siriaccess/vm/json?indent=yes&lineRef=22

Responses

Following response is an example of data collected from vehicle (bus) TKL_94 operating on line 2.

{
  "Siri" : {
    "ServiceDelivery" : {
      "ResponseTimestamp" : 1379169513744,
      "ProducerRef" : {
        "value" : "IJ2010"
      },
      "Status" : true,
      "MoreData" : false,
      "VehicleMonitoringDelivery" : [ {
        "VehicleActivity" : [ {
          "ValidUntilTime" : 1379169543010,
          "MonitoredVehicleJourney" : {
            "LineRef" : {
              "value" : "5"
            },
            "DirectionRef" : {
              "value" : "2"
            },
            "FramedVehicleJourneyRef" : {
              "DataFrameRef" : {
                "value" : "2013-09-14"
              },
              "DatedVehicleJourneyRef" : "1705"
            },
            "OperatorRef" : {
              "value" : "TKL"
            },
            "OriginName" : {
              "value" : "Keskustori I",
              "lang" : "fi"
            },
            "DestinationName" : {
              "value" : "Hervantakeskus",
              "lang" : "fi"
            },
            "Monitored" : true,
            "VehicleLocation" : {
              "Longitude" : 23.8516535,
              "Latitude" : 61.4486107
            },
            "Bearing" : 0.0,
            "Delay" : "P0Y0M0DT0H3M28.000S",
            "VehicleRef" : {
              "value" : "TKL_94"
            }
          },
          "RecordedAtTime" : 1379169513010
        } ],
        "version" : "1.3",
        "ResponseTimestamp" : 1379169513744,
        "Status" : true
      } ]
    },
    "version" : "1.3"
  }
}

The fields and the response structure is similar than the earlier presented XML response. Please check the XML response for few field descriptions.

SIRI General Messages

SIRI general messages, or GM, offers periodic message-style updates on events occurring in the public transport network, such as information about service disruptions or route changes.

URLs:

• http://data.itsfactory.fi/siriaccess/gm/json (SIRI JSON documents over HTTP GET)

SIRI XML documents over HTTP POST

Requests

<?xml version="1.0" encoding="UTF-8"?>
<Siri xmlns="http://www.siri.org.uk/siri" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" version="1.3" xsi:schemaLocation="http://www.kizoom.com/standards/siri/schema/1.3/siri.xsd">
            <ServiceRequest>
                        <RequestTimestamp>2012-06-11T09:30:50-03:00</RequestTimestamp>
                        <GeneralMessageRequest version="1.3">
                                    <RequestTimestamp>2012-06-11T09:30:50-03:00</RequestTimestamp>
                        </GeneralMessageRequest>           
            </ServiceRequest>
</Siri>

Responses

Following is a response for general message request:

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<Siri version="1.3" xmlns="http://www.siri.org.uk/siri" xmlns:ns2="http://www.ifopt.org.uk/acsb" xmlns:ns3="http://www.ifopt.org.uk/ifopt" xmlns:ns4="http://datex2.eu/schema/1_0/1_0">
   <ServiceDelivery>
      <ResponseTimestamp>2013-04-24T10:20:19.195+03:00</ResponseTimestamp>
      <ProducerRef>IJ2010</ProducerRef>
      <Status>true</Status>
      <MoreData>false</MoreData>
      <GeneralMessageDelivery version="1.3">
         <ResponseTimestamp>2013-04-24T10:20:19.195+03:00</ResponseTimestamp>
         <Status>true</Status>
         <GeneralMessage formatRef="string">
            <RecordedAtTime>2011-09-20T00:00:00+03:00</RecordedAtTime>
            <InfoMessageIdentifier>307</InfoMessageIdentifier>
            <InfoMessageVersion>1</InfoMessageVersion>
            <InfoChannelRef>errors</InfoChannelRef>
            <ValidUntilTime>2011-09-20T23:59:00+03:00</ValidUntilTime>
            <Content xsi:type="xs:string" xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">Hämeensilta poikki</Content>
         </GeneralMessage>
         <GeneralMessage formatRef="string">
            <RecordedAtTime>2011-09-20T00:00:00+03:00</RecordedAtTime>
            <InfoMessageIdentifier>308</InfoMessageIdentifier>
            <InfoMessageVersion>3</InfoMessageVersion>
            <InfoChannelRef>warnings</InfoChannelRef>
            <ValidUntilTime>2011-09-20T23:59:00+03:00</ValidUntilTime>
            <Content xsi:type="xs:string" xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">Vappukulkue hidastaa linjojen 13 23 etenemistä</Content>
         </GeneralMessage>
      </GeneralMessageDelivery>
   </ServiceDelivery>
</Siri>

The response is quite straightforward:

• InfoChannelRef tells if this message is either error, warning or message
• Content contains the actual message data

SIRI JSON documents over HTTP GET

Requests

To access the SIRI general messages client would send following request to http://data.itsfactory.fi/siriaccess/gm/json The URL supports following parameters

• indent=<yes|no>

Responses

The fields and the response structure is similar than the earlier presented XML response. Please check the XML response for few field descriptions.