Getting Started with the Events API

Many resources are contained within events including results, program data, event images and start lists. As a result the Events API contains a large number of methods to explore.

Run in Postman

Event Methods

Event Listings returns a filterable list of event objects. This method is useful for displaying event listings or all events that meet a criteria e.g. WTS events in 2016. This method will allow determining of the unique event_id parameter that is required in all subsequent request types. Below we explore each of the available methods and provide a sample query for each.

curl --header "apikey: [[app:key]]" "https://api.triathlon.org/v1/events?category_id=351&start_date=2016-01-01&end_date=2017-01-01"

Retrieve Event Information returns a full event listing suitable for outputting an event detail page. This method also includes summary information for associated news, videos and images such that these results may be previewed without resorting to multiple API calls.

curl --header "apikey: [[app:key]]" "https://api.triathlon.org/v1/events/97636"

Event Web Images returns a list of gallery objects for the event web galleries (all subject to usage restrictions) that you will find on Triathlon.org.

curl --header "apikey: [[app:key]]" "https://api.triathlon.org/v1/events/97636/images"

Event High Resolution Images returns a list of gallery objects for High Resolution Images that were taken at the event (again all subject to usage restrictions).

curl --header "apikey: [[app:key]]" "https://api.triathlon.org/v1/events/97636/hr_images"

Event News returns an array of news objects for all articles that have been associated with the event.

curl --header "apikey: [[app:key]]" "https://api.triathlon.org/v1/events/97636/news"

Event Videos returns an array of video objects for all videos that have been associated with the event.

curl --header "apikey: [[app:key]]" "https://api.triathlon.org/v1/events/97636/videos"

Event Twitter acts as a proxy for the Twitter API allowing users to query the Twitter account of the event simply by knowing the event_id.

curl --header "apikey: [[app:key]]" "https://api.triathlon.org/v1/events/97636/twitter"

Event Related Events returns an array of event objects for other events happening at the same venue.

curl --header "apikey: [[app:key]]" "https://api.triathlon.org/v1/events/97636/related"

Event Medal Tally returns an Olympic-style medal tally for a given event_id

curl --header "apikey: [[app:key]]" "https://api.triathlon.org/v1/events/97636/medal_tally"

Event Medal Country Breakdown returns the athletes corresponding to a country_id that secured medals in a given event_id.

curl --header "apikey: [[app:key]]" "https://api.triathlon.org/v1/events/97636/medal_tally/2356"

Event Specifications returns a list of all available event specifications that may be used to filter event searches.

curl --header "apikey: [[app:key]]" "https://api.triathlon.org/v1/events/specifications"

Event Categories returns a list of all available event categories that may be used to filter event searches.

curl --header "apikey: [[app:key]]" "https://api.triathlon.org/v1/events/categories"

Program Methods

Races at an event are referred to as programs. So one event contains many programs such as Elite Men, Elite Women, U23 Men etc... A large amount of data is also held at the program level such as atmospheric conditions, entries and results.

  • Program Listings returns a filterable array of program objects for a given event_id.
  • Retrieve Program Information returns a full program listing for a given prog_id (and associated event_id). This method would return, if available, course distances, weather data and any associated notes.
  • Program Entries returns an array of athlete objects for a given prog_id (and associated event_id) representing the start list of a program. It is also possible to view the waitlist of an event in the future provided that the 30-day window before the event has been met.
  • Program Results returns an array of result objects for a given prog_id (and associated event_id).

Sample Usage

Using the World Triathlon Series website as an example to generate the following pages:

  • 2016 Calendar Listing - Use the Event Listings method specifying parameters of category_id=351, start_date=2016-01-01 and end_date=2016-01-01
  • Start List Page use the program entries method to generate a list of athletes. For the expanded athlete profile information simply use the associated athlete_id of each entry to make a request to the Retrieve Athlete Information method of the Athletes API.