How do I get all the arrivals at a StopPoint regardless of mode?

Unified API
1

I’ve started using the /StopPoint/{id}/Arrivals endpoint, which is very useful - but the docs are unclear which {id} I actually need to use. I’ve experimented a bit and there seems to be different hierarchies for each mode that are inconsistent with one another.

For river buses, I just need to use to the Top-level id for the pier. For example, if I’m looking at https://api.tfl.gov.uk/StopPoint/930GWMR/ I can just add /Arrivals and get the all the arrivals. This will get river buses in both directions in a single call, which I can then subdivide based on the platform field if I wish.

Land buses are bit more complicated, for example adding /Arrivals to https://api.tfl.gov.uk/StopPoint/490G00005736 just returns an empty array. Instead I need to trawl through the children of the StopPoint and then do separate calls for each direction of travel, as they have their own child StopPoints.

Tube stations get even more confusing, as they often have bus stops bundled with them. For example, for https://api.tfl.gov.uk/StopPoint/940GZZLUBMY I can add /Arrivals, which will get me tube trains in both directions. But to get buses I have to look at the children of one of the children of the StopPoint and do separate /Arrivals calls for each direction of travel.

So it seems that to get everything which stops at a StopPoint, I need to recursively go through all the children and then try /Arrivals to see what comes back. The problem with this approach is I end up making a tonne of pointless calls like https://api.tfl.gov.uk/StopPoint/4900STFD3/Arrivals (Which I think is meant to be a list of arrivals to the Northern entrance of Stratford Station - it’s just an empty array)

Another option would be to use the lineGroup array - this seems to only include things I’m interested in (ie not doors and the like). My problem here is I don’t really understand the identifiers returned (naptanIdReference vs stationAtcoCode). I’ve done some experimenting and it seems like the logic is:

  • Land buses: /StopPoint/{naptanIdReference}/Arrivals returns something useful; /StopPoint/{stationAtcoCode}/Arrivals is an empty array.
  • River buses: /StopPoint/{naptanIdReference}/Arrivals is an empty array; /StopPoint/{stationAtcoCode}/Arrivals returns something useful.
  • Tubes: /StopPoint/{stationAtcoCode}/Arrivals returns something useful; naptanIdReference is missing.

This is quite frustrating because I can’t write mode-generic logic for lineGroups. (Also the lineGroups don’t tell you the mode, so I can’t even write mode-specific logic.)

Are there any docs that explain the StopPoint hierarchy in more detail and how that fits in with the Arrivals endpoints? Or even better, is there an endpoint that will show me the Arrivals for all vehicles arriving at a given StopPoint or any of its descendant StopPoints?

Cheers,
Luke

2

Hi @tfluke I feel your frustration, and thank you for writing such a good summary of the problem. By its nature the Naptan hierarchy is complex and inconsistent between modes - some of that is leaking through our abstraction despite our best efforts. The pages on our site use similar (mode-specific) rules to show the right thing - not ideal.

The intention is that Arrivals would always be attached to the stationAtcoCode, and it sounds like buses are the only exception to this? I’ll raise a ticket to get that improved. SVC-4612

In the meantime I’m afraid you’ll have to adopt some mode-specific logic to get arrivals at the correct level in the hierarchy. Alternatively, you can get all Arrivals by mode with /Mode/{mode}/Arrivals, if you wanted to get everything in a few calls and then do your own filtering (rather than recursively querying children).

3

Thanks for that!

Would it also be possible for objects in the lineGroup array to have the mode as an attribute? That’d make mode-specific logic easier to write.

Fetching all the Arrival data across the entire network seems a little overkill. I’m already doing something similar for tube, dlr and river buses, but adding buses and other modes would require a significant amount of loading and filtering. Out of curiosity, is there somewhere I can find the full list of modes? I’ve tried looking at /Mode/, but that just runs 404.

4

Hi @tfluke You can get all the modes from /Line/Meta/Modes [edited typo], although you’ll probably want to filter out the ones that do not have the isScheduledService flag (e.g. walking)

1 Like
5

Cheers @nickp!

(For anyone else looking for this, it’s actually /Line/Meta/Modes with an s)