Skip to content
OResults Docs

Public API

OResults has a public API for uploading competition data and exchanging punches. It is the same interface our own integrations use. If you are connecting event management software, build against it.

If your software is MeOS, QuickEvent, OE12 or SI-Droid Event, it already speaks to OResults. You do not need this page. If it saves IOF XML files to a folder, OResults Connector uploads them.

Authentication

Section titled “Authentication”

The upload endpoints, the MeOS Online Protocol and Send punches authenticate with your event’s API key: no account, no token exchange. Copy it as described in Connect your software with the API key on the Upload start lists and results page. Reading punches back over the ROC protocol takes no key at all.

Send it one of three ways, depending on the endpoint:

  • the apiKey text field of a multipart/form-data upload
  • the api_key field of the JSON body, for Send punches
  • the pwd header, for the MeOS Online Protocol

Uploads

Section titled “Uploads”

Start lists, results and courses are uploaded as multipart/form-data with two fields: apiKey (text) and file (binary). Files may be plain or compressed with gzip, deflate, zlib or zip.

Send punches

Section titled “Send punches”

Send punches from your own online controls or timing system as JSON, and OResults adds them to the event’s live punches.

Request: POST https://api.oresults.eu/punches/external, with Content-Type: application/json

Field Type Value
api_key string the event’s API key, or the device token of a device linked to the event
records array the punches, each an object with the fields below
code integer the station code
card integer the SI card number
time string RFC 3339 with an offset (2026-01-20T14:30:00+01:00, 2026-01-20T14:30:00Z), or a local time with optional fractions of a second (2026-01-20T14:30:00.123), read in the event’s Timezone
punch_type integer, optional 0 control, 1 start, 2 clear, 3 check, 9 finish

A device token sends the punches to the event its device is linked to when they arrive. It is shown in the device’s Pair Bluebox Mobile dialog, as Pair the app on the Use a phone as an online control page describes.

Without punch_type, or with 0, OResults keeps code and reads it by the station-code convention: 29 start, 30 check, below 29 finish, 31 or above an online control. See Station codes on the Set up online controls page. With 1 or 9, OResults stores a start or a finish punch whatever code says. It skips records with 2 or 3.

{
  "api_key": "your-event-api-key",
  "records": [
    { "code": 31, "card": 8636192, "time": "2026-01-20T14:30:00+01:00" },
    { "punch_type": 9, "code": 1, "card": 8636192, "time": "2026-01-20T14:52:17.400" }
  ]
}

Responses:

  • 201, empty: every record is stored.
  • 400 Invalid API token: api_key matches no event and no device.
  • 400 Device not assigned to an event: the device token belongs to a device linked to no event.
  • 400, empty: a time in neither format. OResults stops at that record, and the records before it are already stored.

OResults stores a punch with the same code, card and time only once, so resending a whole batch after an error is safe.

MeOS Online Protocol

Section titled “MeOS Online Protocol”

The MeOS Online Protocol (MOP) publishes results, split times and start lists from MeOS to an online service, in our case OResults. It is MeOS’s protocol, not ours, and MeOS source on GitHub defines the format itself.

Request: POST https://api.oresults.eu/meos

  • Authentication: your event’s API key, in the pwd header
  • Accepted format: MeOS Online Protocol XML 2.0
  • Compression: optional; OResults accepts gzip, deflate, zlib, or a zip archive and reads its first file

OResults reads each start time (st) as a local time of day on the event’s Start date, in the event’s Timezone, and counts online-control times from it. A runner without a start time starts at the event’s Start date and Start time. Set Start date, Start time and Timezone to those of the competition, or times will not line up.

Setting MeOS itself up is on the MeOS page.

ROC protocol

Section titled “ROC protocol”

The ROC protocol is a plain-text list of punch records that orienteering software polls to receive live punches. MeOS reads it with its Remote Input service, OE12 with Online monitor - Client Web.

Request: GET https://api.oresults.eu/roc

Parameters:

  • unitId: OResults event ID (in the URL of your event)
  • lastId: last punch ID (usually filled in automatically by your orienteering software)
  • date: optional, YYYY-MM-DD; with time, OResults returns only punches after this moment (default 1970-01-01)
  • time: optional, HH:MM:SS (default 00:00:00)

OResults reads date and time in the event’s timezone, and writes each punch timestamp in the event’s timezone with no offset.

Response example:

1;1;2067971;2022-05-21 08:45:19
2;1;2144039;2022-05-21 09:53:40
3;1;8636192;2022-05-21 09:53:47
4;1;2144039;2022-05-21 09:59:17

Each row is one punch record. The semicolon-separated values are the punch record ID, control code, SI card and punch timestamp.

Setting it up in your own software is on the MeOS and OE12 pages.

Reference and support

Section titled “Reference and support”

The full endpoint reference, with schemas and examples, is the OResults API specification.

Email tech@oresults.eu or join our Discord.