Vehicle Motion -data is available as JSON formatted from URL :
The URL is to be polled with interval no faster than three seconds. The frontend server caches backend provided data for two seconds, so faster polling interval does not produce more exact data.
VM-data is mainly used for displaying physical location of currently active vehicles. Provided data is not based on sole GPS acquired location but on backend systems educated guess based on vehicles odometer, it's GPS location, time spent after beginning of trip and/or previous stop, etc.
Based on above analysis, backend system positions vehicle into its planned map route. If for some reason (construction zoned, road blockade) vehicle is forced to choose another driving route, backend system does not locate it to its real location but stubbornly tries to keep it on planned route eventually losing the vehicle for rest of it's trip.
Backend system generally compensates reporting delays that occur when transmitting location data over mobile network from vehicle to backend system, but it's common to have about 5 second variation between vehicles advertised and real location. Location reporting is affected by status and availability of mobile network, there is locations where mobile connectivity is not good enough or mobile stations are in state where passing mobile client from station to another does not work correctly.
Also there is occassional breakages in vehicles traffic system equipment causing errors to location data.
In case VM-service is not started at the moment of query, URL returns error :
{"sys":"VM","status":"PENDING","servertime":1433246350,"result":[]}
Service starts producing data in 5-30 seconds.
Response data is practically SIRI-XML -message simplified and reformatted to JSON. Field names matches their SIRI equivalents. Normal response is compressed and unformatted, but for inspection and debugging reasons you can append /pretty suffix to URL to get content in more human readable format.
Example reply :
{
"sys" : "VM",
"status" : "OK",
"servertime" : 1433246786,
"result" : {
"responsetimestamp" : 1433246783,
"producerref" : "jlt",
"responsemessageidentifier" : "western-62",
"status" : true,
"moredata" : false,
"vehicles" : {
"550011" : {
"recordedattime" : 1433246781,
"validuntiltime" : 1433247381,
"linkdistance" : 281,
"percentage" : 41.28,
"lineref" : "14",
"directionref" : "1",
"publishedlinename" : "14",
"operatorref" : "55",
"originref" : "246",
"originname" : "Saram\u00e4ki",
"destinationref" : "395",
"destinationname" : "Erikvalla",
"originaimeddeparturetime" : 1433258100,
"destinationaimedarrivaltime" : 1433261580,
"monitored" : true,
"incongestion" : false,
"inpanic" : false,
"longitude" : 22.240084,
"latitude" : 60.431302,
"delay" : "-PT13539S",
"vehicleref" : "550011",
"previouscalls" : [
{
"stoppointref" : "80",
"visitnumber" : 52,
"stoppointname" : "Korppolaism\u00e4ki",
"aimedarrivaltime" : 1433260320,
"aimeddeparturetime" : 1433260320
}
],
"vehicleatstop" : false,
"next_stoppointref" : "81",
"next_stoppointname" : "Majakkaranta",
"next_destinationdisplay" : "Erikvalla",
"next_aimedarrivaltime" : 1433260320,
"next_expectedarrivaltime" : 1433246507,
"next_aimeddeparturetime" : 1433260380,
"next_expecteddeparturetime" : 1433246567,
"onwardcalls" : [
{
"stoppointref" : "82",
"visitnumber" : 54,
"stoppointname" : "Pihlajaniemi",
"aimedarrivaltime" : 1433260380,
"expectedarrivaltime" : 1433246841,
"aimeddeparturetime" : 1433260440,
"expecteddeparturetime" : 1433246901
}
]
},
"550014" : {
/* ...(snip)... */
Please note that VM-reply is large, so polling VM with handhelds consumes fair amount of bandwidth. Especially in case mobile device has limited data package, long polling of vehicle movements might consume excessive amounts from its monthly data plan.
There is not currently way to poll just some of the vehicles. Because of high volatility of source data and large number of vehicles, this would again be very resources consuming to implement on backend. If picking up selected vehicles is required, you need to implement it on your own dedicated cache server.
If there is problems with backend system, frontend server responds with error :
{"sys":"VM","status":"NO_SIRI_DATA","servertime":1433246350,"result":[]}