@misar Well there you go. I’m out of ideas. 
@briantist No problem and my apologies.
I should have been clearer in post #13 yesterday that I have extracted a complete set of bus stops from the API JSONs and appended the two new fields to my existing database. I doubt that the “towards” values change very much but having written the code it is quick and easy to do an update.
1 Like
Hi @misar. Apologies for the delay; I just returned from holiday.
As indicated by the sourceSystemKey, the Towards value comes from the Countdown, so you can query this yourself from the Countdown API.
The Countdown API is documented at:
If you want to get the Towards value for every bus stop on the TfL network, you can make a request to:
https://countdown.api.tfl.gov.uk/interfaces/ura/instant_V1?StopAlso=1&ReturnList=StopCode2,Towards
Note that the response is in JSON Lines format, where every line is a JSON array.
Any array where the zeroth element is 0 is a Stop array. This will indicate the ATCO Code for the stop as well as the Towards value.
For example, the array:
[0,"490013323SB","Elephant & Castle"]
…indicates that the bus stop with ATCO Code 490013323SB (Southwark Station (SB)) has a Towards value of “Elephant & Castle”.
I hope this helps. Please let me know if you have any questions.
1 Like
Hi @LeonByford. Thank you once again. It was much easier than I expected to extract fields from the complete StopPoint download which you originally provided. However, the new URL (with Towards or LineName) is obviously preferable to downloading 37 pages most of which I don’t need!
Back in 2016 when I started with the API I actually found a slightly older (v1.6) copy of the API documentation PDF. The examples enabled me to construct URLs to get real-time arrivals for any stop/route(s) using its NaPTAN and my application has used those ever since. TBH even with your latest URL as an example I cannot work out how I would have derived it by reading the guide. In fact I could not have done so because it begs a question which I asked back in September but was unanswered.
Your latest URL has the root https://countdown.api.tfl.gov.uk/ but all my usage of the API has been with https://api.tfl.gov.uk/. The online API details pages (or the TfL Collection in Postman) have hundreds of URL examples, all without countdown. I tested the latest URL without countdown and it returns a 404 (“NotFound”) error. So - what is Countdown and when does it need to be used?
That question has puzzled me since I received a TfL email back in August with a warning that Countdown was changing. As I had no idea I was using it (this Forum told me I was not), I searched the web for an answer. If one is out there it has so far eluded me.
Thanks for your questions. We have several different systems that do different things. For example, Countdown provides live bus data and Trackernet provides live Tube data. Originally, open data users were required to integrate with each one of these systems individually. However, these systems all function rather differently, making it a bit of a headache for developers.
That’s why in 2016 or so we launched the Unified API. The Unified API effectively “unifies” these different data sources into a single consistent interface. So whether you want bus data, Tube data, or data for any other mode, you can get it in the same format from the Unified API. The data still ultimately originates from Countdown, Trackernet and so on, but you query the Unified API rather than the underlying system.
countdown.api.tfl.gov.ukis the original Countdown APIapi.tfl.gov.ukis the Unified API
When would you use the Unified API and when would you use the Countdown API? Well, the Unified API is a lot simpler and covers all modes of transport, so this is generally what we would recommend using. That said, there are certain use cases where using the Countdown API may be preferable or even necessary. As you noticed, querying data about every single bus stop from the Unified API is somewhat unwieldy (requiring 37 requests), whereas with the Countdown API you can get the data you want with just a single request. In this case, the decision is ultimately yours to make, perhaps based on which would be easier for you. That said, there are certain fields in the Countdown API (e.g. VisitNumber) which are not available from the Unified API. If you need access to this data, then you would need to use the Countdown API.
@LeonByford. Thank you very much for taking the trouble to explain the system. I previously assumed that the Unified API had completely replaced TfL’s legacy APIs (eg Countdown) rather than being just a “high level” interface to them. Your explanation clarifies the position for me but when you have time it raises these two questions:
Is there an accessible listing of additional information which is available only directly from Countdown?
Does the public documentation for the Unified API provide sufficient information to derive Countdown-specific URLs or is that elsewhere?
Sorry to have so many questions!
UPDATE
I just had a closer look at that API documentation PDF (after 7 years) and I think it is the original Countdown documentation. My apologies for the confusion.
You’re welcome. Please do feel free to ask if you have any questions. That’s what we’re here for. 
I’m not aware of something like this. That said, off the top of my head, the main omissions in the Unified API for bus predictions are VisitNumber and TripID. Furthermore, Countdown provides a “cleardown” functionality where a prediction with ExpireTime set to 0 is sent, which indicates that the prediction is no longer valid and should be deleted. This is not available in the Unified API.
In addition to predictions, Countdown provides flexible messages, which are used to indicate bus stop closures or other disruptions / travel information. We import some of these into the Unified API, however there are some that are only available in Countdown (notably, bottom-line messages, i.e. the scrolling text that appears on the bottom line of the dot-matrix display at bus stops).
Omissions aside, differences in the interfaces may make it impractical to use one of the APIs versus the other.
The Unified API and Countdown API are very different, so the documentation is largely separate.
For the Countdown API, the documentation is the PDF I linked to. This PDF is linked to from the “Our open data” page. The PDF does not include the API endpoint, but this can be found on the (confusingly titled) “Our Unified API” page. With this information, it should be possible to derive Countdown-specific URLs.
@LeonByford. I now have a much better understanding of TfL’s data systems but the websites are so confusing I doubt I would ever have got there without your various explanations. Interestingly, I found a note I wrote myself seven years ago lamenting the passing (as I assumed) of the legacy bus API because “it has real pdf documentation which is far superior to the online information for the new API”. With the help of that and your examples I found it trivial today to produce a selection of URLs precisely targeting the Countdown fields to be retrieved. I think I now understand why Countdown is mentioned so often in posts. Somewhere in there might be a moral for TfL. 
1 Like
Yes, the documentation for some of our other APIs is somewhat lacking. It’s something we’re aware of and I know my colleague @SarahLS is trying to address.
Glad to hear you have the Countdown API figured out; if you run into any problems, just let us know. 
1 Like