The Matchups endpoint allows you to determine the relative head-to-head results for a group of athletes.

The required athletes parameter should contain a filter to determine a list of athletes for analysis. You may use any of the available athlete properties to create your athlete grouping (i.e. athlete.id, athlete.name, athlete.first, athlete.last). So long as the athlete filter resolves to a set of athletes any filter is acceptable.

For example to get a head-to-head matchup of Javier Gomez Noya and Alistair Brownlee we could make the following query:

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

Alternatively using the athlete.id property:

curl --header "apikey: [[app:key]]" "https://api.triathlon.org/v1/statistics/matchups?athletes=athlete.id,in,7788,5695"

The API call will return an object with a total_matchups property which is the number of times that these athletes have raced in the same events matching the chosen criteria (see additional filters section). In addition the resulting athletes array lists all athletes used in the analysis together with the number of wins, losses and no-results for the matching events.

🚧
Wins vs Losses vs No Results
As we are considering matchups a 'win' is finishing ahead of all other athletes in the group (and not necessarily a race win). A no result can only occur when all athletes in the group do not complete, or are disqualified from the event. The Matchup endpoint is specifically for relative performance to a group and if you require absolute analysis types (such as number of race wins) you should use the primary Results endpoint.

The following example only shows a single result in the matchup_results array for brevity. The actual response would contain all 27 results.

{
   "code":200,
   "status":"success",
   "data":{
      "total_matchups":27,
      "athletes":[
         {
            "wins":7,
            "losses":20,
            "no_results":0,
            "athlete_id":5695,
            "athlete_title":"Javier Gomez Noya",
            "athlete_first":"Javier",
            "athlete_last":"Gomez Noya",
            "athlete_gender":"male",
            "athlete_age":32,
            "athlete_country":"ESP",
            "athlete_flag":"https:\/\/f9ca11ef49c28681fc01-0acbf57e00c47a50e70a1acb89e86c89.ssl.cf1.rackcdn.com\/images\/icons\/es.png",
            "athlete_profile_image":"http:\/\/www.triathlon.org\/images\/athlete_thumbs\/Gomez.png",
            "wts_ranking":1,
            "wts_starts":44,
            "wts_wins":11,
            "wts_podiums":32,
            "matchup_results":[
               {
                  "format":"Standard",
                  "finish_time":6738,
                  "program.id":4538,
                  "event.name":"2009 Dextro Energy Triathlon - ITU World Championship Series Madrid",
                  "date":"2009-05-31T14:14:00+0000",
                  "position":3
               },
              //...... other results ......//
            ]
         },
         {
            "wins":20,
            "losses":7,
            "no_results":0,
            "athlete_id":7788,
            "athlete_title":"Alistair Brownlee",
            "athlete_first":"Alistair",
            "athlete_last":"Brownlee",
            "athlete_gender":"male",
            "athlete_age":27,
            "athlete_country":"GBR",
            "athlete_flag":"https:\/\/f9ca11ef49c28681fc01-0acbf57e00c47a50e70a1acb89e86c89.ssl.cf1.rackcdn.com\/images\/icons\/gb.png",
            "athlete_profile_image":"http:\/\/www.triathlon.org\/images\/athlete_thumbs\/Brownlee.png",
            "wts_ranking":5,
            "wts_starts":29,
            "wts_wins":19,
            "wts_podiums":23,
            "matchup_results":[
               {
                  "format":"Standard",
                  "finish_time":6686,
                  "program.id":4538,
                  "event.name":"2009 Dextro Energy Triathlon - ITU World Championship Series Madrid",
                  "date":"2009-05-31T14:14:00+0000",
                  "position":1
               },
              //...... other results ......//
	            ]
         }
      ]
   }
}

You are not limited to analysing two athletes and a group may be conceivably as large as you wish. The following example adds Jonathan Brownlee to the previous query. This will return all results where all three athletes have raced and determine the winner of each event as the first finisher of the three.

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

If you enter a query where no matchups have occurred, such as where a group of athletes have never raced each other, you will be returned a 400 response as per the following example:

{
   "code":400,
   "status":"fail",
   "data":{
      "error":"This matchup has not occurred"
   }
}

Additional Filters

Whilst analyzing all results for an athlete grouping is an excellent starting point, sometimes you may wish to delve deeper into the analysis e.g. what is the matchup over a specific course? How does a matchup vary over format (Sprint vs. Standard)? How does wearing a wetsuit affect the matchup?

For this type of analysis we have the entire filter property at our disposal and we can combine as complex a filter as we wish, for example events in Hamburg that had a wetsuit swim and the air temperature was greater than 20 degrees. This will return a matchup for only these specific conditions for the group of athletes chosen. Filters are constructed as described in the filters section and multiple filters should be combined in a pipe delimited list e.g. for the preceding example:

filters=event.name,contains,Hamburg|program.wetsuit,eq,true|temperature.air,gte,20

Again, you may pass in as many athletes into this analysis as you desire. For example the following query lists the Alistair Brownlee vs Javier Gomez Noya vs Jonathan Brownlee matchup for events that occurred in Hamburg.

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

200200

400400