Skip to content

Competitors

This section will tell you how to * list competitors in your competition * add competitors to your competition. * update a competitor * amend info about their participation in an event (e.g. seed time, checked in, changing events)

Competitors must be identified by a unique string, competitor_id, which is often the bib number on their chest. It must be unique within the competition, but need not be globally. However, if exporting from another system, you may wish to use your internal ID for that athlete.

If you are uploading data on past competitions and just want to get the results in, there is no need to specify "who entered what" in advance; if we see bib 100 in the results, we'll just assume it matches the competitor with competitor_id="100". However, if you wanted to upload entry and start lists pre-competition, you'd want to "drill into" the events_entered property of each competitor, to tell us who is doing which events.

Get your competition ID

As discussed on (the previous page)[/api/competition_setup/], you'll need the id of the competition you want to query, and also meeting director access to that competition.

Iterating over competitors

This endpoint will list competitors in a competition. By default, we return 50 at a time, but you can safely set a higher limit up to 500 to get them in one call. 

/api/competitors?competition=58706d25-1289-4032-9277-020575485c39&limit=500

JSON field Structure

There are MANY fields, explorable through our browseable API. Here are just a few key ones:

  • competitor_id = The bib of the athlete.
  • date_of_birth allows us to calculate age groups. We use World Athletics-style age groups: U14, U16, U18 etc.
  • team_id = OpenTrack short code representing an organisation the athlete represents, a team, club or a country.
  • gender = M/F/X. (The latter meaning "I would rather not specify". 'X' competitors will be fetched into Men's start lists.)
  • first_name, last_name are self-explanatory.
  • first_name_local, last_name_local are the equivalent when using dual scripts, such as Greek or Russian; we will attempt to display the viewer's preferred script from their browser settings.
  • events_entered.event_code = The code used in the events grid to identify the event, e.g. HJ = High Jump, we have rules on choosing these you can find here.
  • events_entered.event_id = Numerical identifier for event in our system, as seen in the events grid. Should not clash with any other event_id. events can just be numbered 1, 2, 3... etc.
  • events_entered.[pb|sb|qp] = Personal Best, Seasons Best, Qualifying Performance. Sometimes you want to set these from outside OpenTrack, having obtained the information elsewhere.
  • events_entered.bib = Used if the athlete is wearing a different bib in this event to all others. For example, an athlete wears one number as a scorer in the match, but another to signify they are a non-scorer in a different event.

Structure of added field:

"competitors": [
    {
        "first_name": "Andrew",
        "last_name": "Robinson", 
        "date_of_birth": "1966-03-21",
        "gender": "M", 
        "team_id": "THH"
        "nationality": "GBR",
        "age_group": "NA", 
        "category": "NA",    # may be 
        "competitor_id": "371", 
        "events_entered": [
            {
                "event_code": "PV", # required
                "event_id": "F2", # required
                "pb": "2.85", # personal best
                "sb": "", # seasons best     
                "qp": "",   # meeting organiser's estimate for seeding
                "time_checked_in": null, # set if using checkins,
                "bib": "987" # if wearing a different bib in this to other events.
            }
        ], 
    },
]

Competitors can be created like this beforehand, before we create events. However it is important to make sure that the event_id and event_code match correctly when you do get down to defining events so it may help to have these written out in advance.

The following example shows the result of uploading the above JSON. The screenshots used in the events also include competitors in them which is why they have all the athlete information filled in.

Method

A code example can be found at https://github.com/openath/opentrack-api-examples/blob/main/results_upload/api_create_competitors.py.

The only change to be made to make this example runnable is to replace the EMAIL and PASSWORD string with your OpenTrack email and password that has authorisation to create competitions.