Statistics¶

Our statistics API is being designed with two main purposes in mind:

Federation customers can build a feature into their own main web sites, showing latest and best performances, or rankings lists
Approved statisticians can pull down individual performances simply, without needing to navigate an entire competition.

At the time of writing this (Dec 2025), Saudi Athletics is the pilot user.

It is only as good as the data; our database does not necessarily know about performances recorded outside OpenTrack. So if a country uses us for all their competitions, and manually submits missing performances, it should serve as a source of data and rankings.

Our example in these docs is The Saudi Arabia Athletics Federation, who are using our system extensively. Examples should work for any other country

Authentication and permission.¶

You need to authenticate as a user, and be added by us to a Group on the server named statisticians_xxx, where xxx is the country code.

API endpoints¶

The base url should be the site for your federation, for example https://saaf.opentrack.run/ or https://norway.opentrack.run. This allows us to determine very easily which country you are requesting data on. )

There is currently only ONE API endpoint present, which is modified by GET paramaters. It's visible in our browseable API under /api/performances/. You can browse by logging into that site, as long as your user's nationality matches the records you wish to fetch.

By default it returns up to 50 records in one query as json, most recent first.

Filtering¶

The API can be filtered through GET parameters as follows:

By default we magically apply?nationality_id=SAU which will show all performances in our database by Saudi Nationals (including overseas, if in Opentrack). This does NOT need to be supplied as a parameter.

If instead?country_id=SAU is supplied, it will show all performances in our database recorded in Saudi Arabia, typically a slightly larger number, as there are many foreign residents and expats living and competing there.

?rankable=[1|0] indicates if the performance is allowed for rankings. For example, a Wind Speed of greater than 2.0 metres per second is not rankable. Similarly, some competitions may not be "rankable" due to lack of officials or an approximately measured course. If you are generating the top rankings for an event and age group, you should always include this.

?has_world_id=1 filters to only those athletes who have an ID in the World Athletics database, which has been added to their OpenTrack record. This ID will let you build a link to their World Athletics full profile.

?gender=[M|F] filters to Male or Female

?event_code=LJ will show all Long Jumps. See our list of event codes

?year=[2025|2026] - the year will filter on dates. The actual filter window is currently from 1st October in the previous year to 30th September in the current year - we regard a December meeting in 2025 to be part of the 2026 season for statistics.

Age Groups¶

Each performance is assigned an age group in this list: ['U12', 'U14', 'U16', 'U18', 'U20', 'U23', 'SEN', 'V35', 'V40', 'V45', 'V50', 'V55', 'V60', 'V65', 'V70', 'V75', 'V80', 'V85', 'V90']

?age_group=SEN is equivalent to not filtering, and includes all junior and veterans age groups. The 100m rankings often includes some U23 and U20 people, and the 5000m rankings will often include people over 35.

?age_group=U20 will be expanded to show lower age groups (U18, U16, U14) and so on

?age_group=V40 will show the bests by anyone 40 and over, thus including V45s

Ordering¶

The default order is by date, most recent first.

?o=perf orders by the numeric performance value (time in seconds or length in metres) - lowest time or greatest distance.

?o=wa orders by the World Athletics points - greatest first. This is great for finding top performances across many events. However, be aware there are NO world athletics points for junior implement weights in throws, or junior hurdle heights, and this field will thus have 0.0

?o=ag orders by the World Masters age grade, a percentage where 100 indicates broadly "world best for this age". This system also has some factors for younger children so can be used to help highlight good junior performances; for example, you might show the best age graded results last weekend to highlight who did "something good" across several competitions, genders or events.

Useful queries¶

This will get the best performances by World Athletics points https://data.opentrack.run/api/performances/?nationality_id=SAU&o=wa

This will get the women's 200m rankings: https://data.opentrack.run/api/performances/?nationality_id=SAU&event_code=200&gender=F&o=perf

Example¶

https://saaf.opentrack.run/api/performances/

By adding the flag (flag name to be decided) will return performances around a certain age group.

Stats JSON Example

  {
    "count": 28,
    "next": null,
    "previous": null,
    "results": [
          {
              "date": "2025-11-07",
              "location": "Al Ahsa National Park - منتزه الأحساء الوطني",
              "country": "http://saaf.opentrack.run/ref/api/countries/SAU/",
              "event_code": "4K",
              "event_text": "R4 4K - Race 1 of 1",
              "person": "http://saaf.opentrack.run/ref/api/people/f128e0e8-9f6d-4fd7-a6a6-faf3d03bd44f/",
              "first_name": "Yasamin",
              "first_name_local": null,
              "last_name": "Al-Jahany",
              "last_name_local": null,
              "gender": "F",
              "nationality_id": "SAU",
              "age_group": "V35",
              "perf_text": "30:24",
              "perf_value": "1824.00",
              "wind": null,
              "record_text": "",
              "note": "",
              "ag": 37.92,
              "wa": 0.0,
              "world_id": null
          }
          ...
    ]
  }

To be completed¶

We are working on ensuring accuracy and correctness. A known bug is that our code is giving World Athletics points to lighter implements; another is that it's not filtering out wind values greater than +2.0. We hope to fix these shortly.