Welcome to the Triathlon API
Developer Hub

Whether you are a researcher, media, or a fan, you'll find comprehensive guides and documentation to help you get up and running with the Triathlon API.

Get Started

Live Timing 2017

The 2017 Cape Town ITU Triathlon World Cup held on Feb 11th 2017 marked the first time that the new version of the live timing standard was used. Whilst this results in an improved timing interface on Triathlon.org the major implication of this is that API users can receive real-time timing data directly for use in their own applications.

There are current three ways to receive live timing data:

1 - REST API

Live timing data is available via the Live Timing endpoint by specifying the prog_id of the race that you wish to get timing for i.e. live/timing/{prog_id}. This endpoint will respond with the latest available timing message. Note that the prog_id of the timing may be determined from either receiving a real-time feed (see below) or from the Program Listings endpoint for a given event. Whilst this is an ideal solution for obtaining an initial timing state polling this endpoint is not recommended for real-time applications.

2 - WEBHOOK FEED

The live timing webhook feed is part of the Subscription API where API users may subscribe a URL to receive all timing.store events. Currently to register a subscription, simply go to the API management portal and register a subscription via the form as shown below.

Now when any timing messages are received they are immediately proxied to the URL specified such that subscribers may receive the real-time updates and process and deliver messages according to their application's requirements. Timing data is included in a payload object as shown below and a full timing message is delivered.

{
"subscription": "timing.store",
"payload": {
    "date": "2017-02-11T14:34:28.917Z",
    "start_time": "2017-02-11T15:30:00.000Z",
    "event_id": "109656",
    "event_name": "2017 Cape Town ITU Triathlon World Cup",
    "prog_id": "281501",
    "prog_name": "Elite Men",
    "wetsuit": "true",
    "sandbox": "true",
    "num_athletes": "34",
    "status": "live",
    ...

3 - STREAMING API

A websocket feed is available at wss://socket.api.triathlon.org/timing which sends all timing messages over a websocket channel so front-end applications can be directly updated. Split data is not included in the websocket feed for brevity of the messages and so full timing messages may be obtained from either then webhook feed or from the REST API when a new timing message is received.

Implementation of the Live Timing Feed

For full details of each of the items in the timing messages you should consult the timing standard

Importantly every message contains full timing information such that receiving the latest timing message is all you need.

If you wish to subscribe to future timing feeds then you should take note of how the timing messages are sent:

  • An initial start list message will be published once the start lists have been confirmed. This will detail the start time, the event_id and prog_id as well as containing the data for each athlete on the start list (you may use the athlete_id to get further information for each athlete from the Athletes API).

  • Any changes to the published start times, condition information or any DNS (indicated in the athlete.status field) will be indicated by a new timing message. Any messages sent prior to the start of the race will be indicated by a status of prerace.

  • As soon as the race begins the start_time containing the accurate start time will be published and the status will be updated to live indicating that the race is underway.

  • As soon as the first athlete crosses the first timing point the latest block will be updated to include the details of the segment (i.e. segment_id and segment_name) as well as how many athletes have crossed the timing point (which may be used to create leaderboards). Whilst timing messages are pushed whenever there is new data, on occasions timing messages will be combined into a single message e.g. a bike pack crossing a timing point will not have a message for each athlete. As each timing message always contains full timing information you should simply act on the latest message received.

  • This process continues through each segment of the race with the latest block always indicating the latest timing point. Any athlete that withdraws from the race should have their status updated to DNF.

  • Once the race has finished and the results are confirmed a final message with a status of official will be published.

If you only want to receive the full timing data at the end of the race (i.e. all the lap data) you may simply make a request to the REST API endpoint upon conclusion of the race and the timing message will contain all available data.

This feed is considered a beta release

This feed should currently be considered as a beta release primarily as due to the nature of working with a multitude of different timers it is difficult to guarantee consistency. However you are free to take the feed and we would love your feedback.

All ITU sanctioned events are free to implement the live timing standard and then timing information will be made available via the API. However, at present only World Triathlon Series and certain World Cup events should be expected to provide the live timing data.