Västtrafik handles and coordinate all public transport in west Sweden with the city of Gothenburg as its main transit hub. Västtrafik offers several APIs to search and plan journeys by train, tram, ferries and bus in West Sweden. The API can be found at Västtrafiks development portal (in Swedish), which serves as a focal point for their open API service. The aim of our reviews of open API:s is to shed light on common obstacles and requirements from a user perspective. Note that the portal around the API is in Swedish, but the documentation and the API syntax is in English. The review will try to guide user with no knowledge in Swedish on how to get started.
Travel Planner (called “Reseplaneraren” in Swedish) has several different API stubs that offers search for stations and stops (/ location), arrivals / departures from a station (arrival board & departureBoard), itinerary planning (/ trip), information about all lines within a geographical area (/ livemap), geographic representation of a line (/ geometry), and estimation of when a line will arrive at a specific station (/ journeDetail).
Review sections:
Licensing and impartial use
Support and documentation
Accessibility and API-structure
Dataformat and quality
Reliability
Usability
Total Score
Conclusion
Licensing and impartial use
Licensing rules can be found in the API menu on the portal under the API console section, stating that the “Travel Planner” uses Apache License 2.0. It would have been an advantage if the licensing rules could be accessible directly on the portal’s front page, provided that all APIs use the same licensing rules. There is no simple explanation “in plan English” on the portal of the Apache license permits and not, but you can find one here.
Limitation refer to restriction to access of data for specific user groups. The only limitations of the “Travel planner” is that the user needs access to an email address, and that the portal is only available in Swedish, which is an obstacle for users without knowledge of Swedish.
Support and documentation
Contact information can be found under the menu “Kontakt” on the front page of the portal, which can be accessed without having to create an account. There is nothing stated about support questions, but when we asked a question about authentication for our review, Västtrafik replied within 42 minutes of our request – which must be considered quick, given that the support does not cost anything.
To find the documentation, the user must navigate to “Mina prenumerationer” (my subscribtions) which is not that obvious. The documentation for the API:s are in English and is only available in PDF. The documentation was last updated in 2014 and does not include the authentication procedure for the current version. However, there is an authentication guide in English for the current version at our site.
Read the OAuth 2.0 authentication guide for the Västtrafik API
Accessibility and API-structure
There is no description of what data the API:s provides on the front page. A brief explanation of the content with samples of data, would help curios user to get quick understanding of what is on offer before register. Now the user must navigate to the details in the API section of the portal to look up explanation of data the API provides. In addition, the portal is only available in Swedish, while parts of the documentation are available in English, which could be perceived as an obstacle for some users. To create an account use the menu “Skapa konto”.
Data format and quality
The “Trip Planner” provides both XML and JSON which are suitable formats for the type of hierarchical data provided. The user can specify the format he or she is most comfortable with. The metadata description included for the XML format, links to the previous version of the API. The current schema are available under the documentation (Mina prenumerationer) menu in the portal. The JSON format does not provide a schema for metadata, which complicates validation and management of data on the client side. Most development environments (IDE) provide functionality to automatically generate objects and validation of attributes to today, given that the schemas are publicly available.
We examined the accuracy for part of the data that are the most time-sensitive, departures / arrivals and itinerary planning. Observations we performed during normal traffic conditions where reliable. But when there where disruptions in the transport system, the data for departures / arrivals for buses, trams, ferries, seamed less accurate. We experienced few occasions where some announced departures and arrivals completely disappear, as if the bus or tram had vanished into thin air on the way to the stop.
Reliability
To obtain the response time of the API requests, we automated a series of client calls at different hours of the day, at several occasion to get an idea of the reliability. The two APIs that were included in the test, where the positions of vehicles (livemap) and itinerary planning (trip). The content of these APIs are based on real-time data and the measurement where recorded the 21 of September at 14:35 and 16:32.
At the first occasion (14:35) the response times where short and consistent, with a standard deviation of 76 (livemap) and 156 (trip) milliseconds. On the latter occasion (16:32) the standard deviation of itinerary planning (trip) was much higher, 541 milliseconds. The logging of response time shows that one request took more than nine seconds, and two others took almost three seconds to complete. The tests we performed with test client provides a relatively small load. In reality, the calls from applications and clients are more sporadic and creates a higher load. The conclusion we draw from our automated tests are that the response times can vary depending of the time of day and this can cause implication for programs and applications that are awaiting replay.
Usability
On several occasions the portal cancelled the user session, even if the user was active browsing around. We did not experience this problem when using the APIs. The session period for both the portal and APIs (60 minutes) are one the short side of the spectrum, forcing the user to frequently perform a new authentication or portal login. The API console on the portal can be accessed without the user logging in, but if the user tries to invoke a request the console yield a error message saying “no content” with the error code (-1). Otherwise, except from that the API console worked well and was of assistance to get familiar with the different parameters available for the API.
Total Score
Conclusion
After spending time reviewing the Västtrafiks developer portal, we feel that the API:s are working well technically. The technical maturity of APIs is reflected in the points awarded in the categories of data formats and data quality. For most of the time the API is reliable with relatively short response time, except some deviations we encountered when the transport system suffers from delays. The support function scores high points for being prompt and providing us with a solution to our question.
The API and portal receives a pass with a score over 50 percent, but there are several areas that could be improved. One such area is providing a updated documentation for the current version of the API, which should be available openly on the portal. The portal could benefit from revised menu structure for better navigation. Metadata is another category that relatively easily could be improved by linking to the current version of schema for simplifying data management for developers. In order not to make an already long article longer, you are welcome to contact us if you want to take part of further improvement suggestions that we noted during the review.
Review of Västtrafik API for public transport by Clear Byte is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License.
Icon made by Freepik from www.flaticon.com, licensed by CC 3.0 BY