Can we have the data updated to make more sense


#1

a portion of the data returned from https://api.tfl.gov.uk/Line/jubilee/Arrivals

{
"$type": “Tfl.Api.Presentation.Entities.Prediction, Tfl.Api.Presentation.Entities”,
“id”: “-392134729”,
“operationType”: 1,
“vehicleId”: “331”,
“naptanId”: “940GZZLUBND”,
“stationName”: “Bond Street Underground Station”,
“lineId”: “jubilee”,
“lineName”: “Jubilee”,
“platformName”: “Southbound - Platform 4”,
“direction”: “outbound”,
“bearing”: “”,
“destinationNaptanId”: “940GZZLUNGW”,
“destinationName”: “North Greenwich Underground Station”,
“timestamp”: “2017-08-23T14:49:44Z”,
“timeToStation”: 1604,
“currentLocation”: “Between Kingsbury and Wembley Park”,
“towards”: “North Greenwich”,
“expectedArrival”: “2017-08-23T15:16:28Z”,
“timeToLive”: “2017-08-23T15:16:28Z”,
“modeName”: “tube”,
“timing”: {
"$type": “Tfl.Api.Presentation.Entities.PredictionTiming, Tfl.Api.Presentation.Entities”,
“countdownServerAdjustment”: “00:00:00”,
“source”: “0001-01-01T00:00:00”,
“insert”: “0001-01-01T00:00:00”,
“read”: “2017-08-23T14:49:32.952Z”,
“sent”: “2017-08-23T14:49:44Z”,
“received”: “0001-01-01T00:00:00”
}
}

// What is this?
"$type": “Tfl.Api.Presentation.Entities.Prediction, Tfl.Api.Presentation.Entities”

//Likewise with these 2. What are they and what use?
“id”: "-392134729"
“operationType”: 1

//direction “outbound” means nothing. Jubilee Line runs North/West and South/East. Not outbound. So why not show ‘Northbound’ instead as that is more useful.
“direction”: “outbound”,

//what is the use of this empty field
"bearing": “”,

**edited post as not as angry as was when first posted :slight_smile:


#2

The bearing field is used for the arrival bearing of buses at bus stops, this allows for the direction of the stop in relation to the road to be ascertained. It is likely present for an underground station to ensure consistency data returned for stop points.

I have a feeling the $type field is a .NET thing, and is used for automatic deserialisation of the JSON to an object for the given class. A dll is linked from the API homepage for this.

I do agree with the general sentiment that the semantics of the API’s responses could be better documented, the Swagger documentation is quite sparse as it stands.


#3

id is the unique id of this prediction. (We use id semantically in the same way across the API where it is the unique identifier of a resource).
$type is indeed a .NET thing - it can be ignored if you’re not using .NET.

We do have a lot of work to do on the response documentation in Swagger, agreed. In general we rely on things having sensible names wherever possible, to be self-documenting, but I understand there are times that’s not always good enough.