Skip to content

Uploading Competition results

Starting out

In this section we'll show you how to setup a competition with graded examples. After you've followed the steps on each of the menus you should have a fully runnable script to create a competition.

All example scripts referred to here are available in a GitHub Repo, opentrack-api-examples

First we'll add Competitiors, then we'll have an optional section on Relay Teams and Teams and finally look at events last as this will likely be the most complicated. Keep in mind a competition could be created without any events and competitors too, though this would be barebones. Here we will lay it out in a format easy to understand.

Our Competition data model

Our logical model of a competition consists of a Competition record, with some nested arrays for Competitors and Events.

Competition - descriptive and configuration fields
        Competitor 1 - bib, name, age group, gender etc
            Events entered:
                Event 1    e.g. eventCode=5000, eventId=T22
                Event 2
        Competitor 2
        Event 1
        Event 2
        Event 3 - e.g. Senior Men's 100m
            Unit 1. (e.g. round1 heat 1, or Final)
                Result or Starter 1.  e.g. bib=281, time=10.93
                Result or Starter 2
                Result or Starter 3
            Unit 2

The easiest way to understand this (without authentication) is by browsing to a competition on our main site,, and adding /json/ to the URL. After a few seconds you will download a big JSON URL.

As you browse our site, you can see the JSON for many elements by appending /json/ to the URL.

However, these are 'old API' and the JSON is in camel case. The next topic takes you step by step

A minimal top-level record

Here are the minimum fields needed to create a competition record...

  • full_name = The recognisable name for your competition.
  • slug = unique method for url, lowercase and no spaces allowed.
  • country_id = 3 letter competition country code.
  • date = competition start date with format 'YYYY-MM-DD'
  • finish_date = competition end date with format 'YYYY-MM-DD'
  • contact_details = the email/phone number used to contact the competition organiser
  • organiser_id = The opentrack id of the organisation (can be found by going to the organisation page and taking this id from the url)

This Python script shows how to upload this:

test = {
    "full_name": "api-test open meeting",
    "slug": "api-test-slug",
    "country_id": "GBR",
    "date": "2020-08-10",
    "finish_date": "2020-08-15",
    "contact_details": "",
    "organiser_id": "6b2af700-0481-4f73-b9ae-8221ae619b55"

A more usual example of a competition without the specifics you'd see is something along these lines:

comp = {
  "full_name": "api-test open meeting",
  "short_name": "api-test",
  "slug": "api-test-slug",
  "name_local": "api-test",
  "country_id": "GBR",
  "address": "Kingsmeadow, Jack Goodchild Way, Kingston Road, Kingston upon Thames, UK",
  "date": "2020-08-10",
  "finish_date": "2020-08-15",
  "wa_rankings_category_id": "DF",
  "age_groups": ["ALL"],
  "basic_description": "This is an opentrack api test",
  "contact_details": "",
  "organiser_id": "6b2af700-0481-4f73-b9ae-8221ae619b55",
  "website": "https://example.example",
  "entry_link": "https://example.example/entry",
  "results_link": "https://example.example/results"

in this case we see address, venue_id, latitude, longitude, altitude. If you have an address and coordinates do not fill in venue_id. If a venue with our id is on the system you can use that and leave the others blank. This record will look like so:


A code example can be found at

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.