The Swedish transport administration authority Trafikverket, offering several open data services. One of these is the API for traffic information, which contains data and information for nation-wide train and road traffic. The API began as a information service for train, which was later on expanded to include road data. Our reviews of open APIs are part of an effort to highlight barriers and requirements from a user perspective. We hope that the reviews providing constructive feedback to the data owners, and inspire others by showing examples and solutions. Read more about the background to why we are reviewing open APIs and open data sources.
The traffic information API was available in version 1.1 during the time of the review and contains traffic data for train and road. The API has objects for traffic announcement for train (TrainMessage), available train stations (TrainStation), and timetable for train (TrainAnnouncement). For road there are objects for images depicting varies traffic situations (Icon), road condition (RoadCondition), overview of road condition based on region (RoadConditionOverview), traffic situation and disturbance (Situation), and data from weather stations along national roads (Weather).
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
The license policy is specific to the API and do not follow any international standard. The current license contain few restrictions on how the data can be used. The license state that the user may not violate Trafikverket’s policy and interests, what there are is not clear. The Licensing policy is perceived as vague and could have been clearer on important issues such as, if data can be used for commercial purposes, if its allowed to modify, if the license should be included in redistribution, or if the data can be incorporated into products with more strict licensing rules. To clarify the license it had been better to use an international standardised licenses that contains understandable statements of what is allowed and not. Trafikverket has in a comment informed us that an international standardised license is in progress for the API.
The only restriction about impartial use of the API is that users needs access to an email address. Another impediment is that the portal is only available in Swedish, which is an obstacle for users without knowledge of the language.
Support and documentation
For support questions there is an email address on the portal. There is also a page for frequently asked questions and a forum page where registered users can ask and replay to each other’s questions. When we contacted support via email, it took one and a half day before our question was answered. For the less patient user, the response time maybe a wee bit too long, even if the data service and support function is free of charge.
The documentation for the API is clear and generally easy to follow, but is only available in Swedish. It describes how requests are performed and there are several request templates on how to get user started quickly. There are also examples of request with geographic selection of road-related events within a certain geographical area. The syntax for the API is well described and each of object that the API provides are also documented together with its attributes (road condition, station name, etc.) along with sample data.
Accessibility and API-structure
The portal has its own API console which allows exploration of data without a client software. Generally a web-based console is good tool for users to become familiar with the syntax and data, and should always be available openly. The portal have a console that is open and provides access traffic data, but fails to explained this on the front-page. As stated before the portal is in Swedish, but the syntax for the API is in English.
Overall, the API has a coherent structure and offers good functionality to filter out specific sets of data. This is done by declaring which attributes that should be included or excluded and the API also offers functionality to seek out new or modified data from a given point in time. But the API does not provide functionality to subscribe to data asynchronously (PUSH) – so the user has to decide how often to pull for new data.
Data format and quality
The API has two formats that the user can choose from: JSON and XML, both of which are well suited for the hierarchical data on offer. The syntax of the API do not following any known standard although it resembles SQL, although it uses known conventions for geographical references. Examples of well-known API frameworks are Swagger, JSONAPI and HATEOAS which are based on REST architecture and standard.
The API does not have any XML and JSON schemas for describing objects and data types, which makes handling data on the client-side more cumbersome. The lack of schemas is a pity since most development environments (IDE) today automatically generates objects, attributes and validation if schemas are provided. However, the portal provides definition of object and attributes as documentation.
The API provides basic metadata, such as when a particular data-post was last changed, who is the source of data and what geographical reference system is being used.
The object timetables for trains (TrainAnnoucment) does not provide sufficient detailed data so that the user can deduct or make their own estimation of departure and arrival times. For road there are more detailed data available, for instance there are weather data from sensors along roads which also includes historical observations. Weather data for wind is reported as mean and maximum, instead of individual measurements. If the measurement had been provided, the user could find out the means, standard deviation by using the historical data.
When assessing how timely estimations of arrivals for train in traffic with announced delay, we measured an interval of 2-10 minutes before new data was published. In our opinion this interval is bit to long, especially for travellers waiting for a delayed train, were every minutes counts. We did not however have the opportunity test how exact the estimates were for delayed trains.
We have received a few reports on announced construction and maintenance of roads that was not accurate or had already been resolved when arriving at the location. However, we had not the opportunity to confirm the problem with inaccurate announcements for road maintenance.
Reliability
The response times for querying the API during the test period, was short regardless the time of day. We divided the test in two parts, where we tested the rail and road-related data separately. For trains we logged response times for arrivals / departures from a station and timetable announcement for a train that was delayed.
For road, we made a geographical filtration for a specific area to retrieve traffic incidents, road conditions and weather data. The request that took the longest was recorded for road conditions (RoadCondition), which on some occasions took more than 500 milliseconds to execute. Note that the automated tests we conduct represents a relatively small load. 
Usability
The portal is relatively easy to navigate, but some of the menus tabs could be more obvious. Suggesting that the menu labelled “API” could be named “Dokumentation” (documentation) and the “Frågan” (question) could be named “Anrop” (request). The menu for creating the authentication key to be uses by client programs – should be more visible, today this function can be found under the menu “Min sida” (My Page).
Total Score
Conclusion
After having evaluated and acquainted ourself with the traffic information API for a period, our experience is that both the portal and the API works well for its intended purpose. The total score surpass approved (50%) and with some relatively small improvements could approaching pass with distinction (75%).
An example of simple improvement is to use an international license for the API, which would clarify what is allowed and not compared to the current license. Replies within 24 hours for support questions would also be desirable, and last but not least provide XML and JSON schemas for all published data.
Measurements that are more time consuming, but would make the API more useful to a wider audience, is to provide more detailed data for existing data object. Today, the train part of the API basically provides information about timetables and estimations of arrivals / departures. We are missing data to deduce why trains are delayed, such as traffic congestion, announcement of current maintenance to rail infrastructure, train position, speed and congestions around bottlenecks.
For the road there are more detailed data, such as weather observations, current conditions and maintenance measures such as salting and snow removal. To extend the usefulness of road data, we would like to see access to the actual average speeds on roads surrounding major cities and motorways. We happily share further improvement suggestions and comments we noted during the review period.
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