GuidesAPI ReferenceRegister & Manage Your AppShowcase
Announcements
AnnouncementsAPI StatusSupport
Back to All

Matchup Endpoint

over 9 years ago by World Triathlon

We have added a new Matchup endpoint to the Statistics API. The purpose of this endpoint is to determine the relative performances of a group of athletes, comparing events where they have raced each other. For a simple example, we can see the rivalry of Alistair and Jonathan Brownlee by making the following query:

curl --header "apikey: [[app:key]]" "https://api.triathlon.org/v1/statistics/matchups?athletes=athlete.name,in,Alistair%20Brownlee,Jonathan%20Brownlee"

A curtailed response is shown below (there is much more detail in the actual response). From the response we can quickly see that the pair have raced each other 20 times over the course of the Series with Alistair finishing ahead of Jonathan in those races 14 times.

🚧

Actual Response Contains More Data

The actual response also contains a matchup_results object that describes each of the results in detail that may be used for presentation or in further analysis. Using the matchup_results object it is also trivial to find the first time and last time the matchup occurred.

{
   "code":200,
   "status":"success",
   "data":{
      "total_matchups":20,
      "athletes":[
         {
            "wins":14,
            "losses":6,
            "no_results":0,
            "athlete_title":"Alistair Brownlee",
            "athlete_age":27,
            "athlete_country":"GBR",
            "wts_ranking":5,
            "wts_starts":29,
            "wts_wins":19,
            "wts_podiums":23
         },
         {
            "wins":6,
            "losses":14,
            "no_results":0,
            "athlete_title":"Jonathan Brownlee",
            "athlete_age":25,
            "athlete_country":"GBR",
            "wts_ranking":7,
            "wts_starts":30,
            "wts_wins":10,
            "wts_podiums":22,
         }
      ]
   }
}

Adding Filters

Through the use of filters we can further break down this analysis by applying the relevant filters to match the event criteria we are interested in. Continuing our above example we would like to know the matchup result between the Brownlee brothers over the Sprint distance. The following query yields that result:

curl --header "apikey: [[app:key]]" "https://api.triathlon.org/v1/statistics/matchups?athletes=athlete.name,in,Alistair%20Brownlee,Jonathan%20Brownlee&filters=format,eq,Sprint"

The result, again curtailed for brevity, shows that they have raced each other 6 times over the Sprint distance with the head-to-head matchup standing at 3 wins apiece.

{
   "code":200,
   "status":"success",
   "data":{
      "total_matchups":6,
      "athletes":[
         {
            "wins":3,
            "losses":3,
            "no_results":0,
            "athlete_title":"Alistair Brownlee"
         },
         {
            "wins":3,
            "losses":3,
            "no_results":0,
            "athlete_title":"Jonathan Brownlee",
         }
      ]
   }
}

You may combine multiple filters to further restrict the events used in the analysis. For example the following query builds on the previous example by only including Standard distance races where wetsuits were used.

curl --header "apikey: [[app:key]]" "https://api.triathlon.org/v1/statistics/matchups?athletes=athlete.name,in,Alistair%20Brownlee,Jonathan%20Brownlee&filters=format,eq,Standard|program.wetsuit,eq,true"

🚧

All Properties Available

All properties are available for use in filters as are listed on the Results endpoint property table.

The following example displays the results of the Brownlee matchup for events in London:

curl --header "apikey: [[app:key]]" "https://api.triathlon.org/v1/statistics/matchups?athletes=athlete.name,in,Alistair%20Brownlee,Jonathan%20Brownlee&filters=event.name,contains,London"

Athlete Groupings

You may pass as many athletes as you wish into the Matchups endpoint with a win being determined as finishing ahead of all other athletes in the group. For example, the following example lists the matchup of Jonathan Brownlee, Mario Mola and Richard Murray over the Sprint distance.

curl --header "apikey: [[app:key]]" "https://api.triathlon.org/v1/statistics/matchups?athletes=athlete.name,in,Jonathan%20Brownlee,Mario%20Mola,Richard%20Murray&filters=format,eq,Sprint"

The response (again only partially shown) shows this specific matchup has occurred 7 times in Series history with Jonathan Brownlee leading this group of athletes 4 times, Mario twice and Richard Murray once. 

{
   "code":200,
   "status":"success",
   "data":{
      "total_matchups":7,
      "athletes":[
         {
            "wins":4,
            "losses":3,
            "athlete_title":"Jonathan Brownlee",
         },
         {
            "wins":2,
            "losses":5,
            "athlete_title":"Mario Mola",
         },
         {
            "wins":1,
            "losses":6,
            "athlete_title":"Richard Murray",
         }
      ]
   }
}

Changelog

  • added: Matchup endpoint at /statistics/matchups
  • added: