Simple API

The Simple API serves to make data from your event file accessible through a static link without logging in to your customer account, this may be to publish results on another website. 

Settings can be accessed through Main Window->Access Rights/Simple API. Simply select what type of data you would like to make accessible and then select the listname or enter the setting name.

You can choose from different API types:

The icon in the column Link then leads to the static link.

When calling APIs you should consider that they will be cached for between 10-30 seconds, therefore calling them more often may not result in data updating correctly.

The Simple API applies rate limiting of 1 call per second per each unique API URL from each unique address. If your client script is calling an API more than once per second then it will receive a 406 error code. If you require more frequent calls please contact support. 

Custom APIs

Custom APIs allow for further refinement of API outputs and also provide some additional functionality when working with RACE RESULT 12.

This guide will document some of the functionality that can be achieved with custom APIs, but should you have any further specific requirements then please contact support with your requirements. 

Custom Counts

As well as the default counts by contest you can apply any filter to an API to return specific count, similar to a DCount.

To count data use a Custom API with: 

Data/count?filter=

You can then apply a regular filter expression such as [Contest]=1AND[Firstname]="Max" however this must be URL encoded. 

The example above would become: %5BContest%5D%3D1AND%5BFirstname%5D%3D%22Max%22

List Data

List Data

Sometimes you want the ability to apply additional filters to output lists or easily adapt what is shown without building more Output Lists. 

To LIST data use a Custom API with:

data/list?

There are some additional paramters which can be appended here, parameters can either be used in the API details in RACE RESULT 12 if they should apply to all API calls, or can be appended to the end of the API url in the API call, when appending to the API url then append "?" first before the parameters.

&fields=
Choose which fields should be listed, multiple fields should be joined with "%2C", this is the URL encoded format of "&"

&sort=
How the data should be sorted

&filterbib=
Quickly filter the list by bib number

&filter=
Allows any standard filter to be applied to the list, remember to use percent encoding for any special characters in the string, multiple filters can be joined using AND

&listformat=
Define the format of the returned values. (e.g. Simple, CSV, XML, JSON)

&separator=
Define the text separator when using TEXT or CSV format

 

Example:

API Details: data/list?fields=RiderID%2CFirstName%2CLastName%2CMaleFemale%2CDateOfBirth%2CATF12%2CATF13
URL: https://api.raceresult.com/111952/6XENXE0KZY1NBFJDB57UQWS14R0L6R2H

Returns a list of all riders with the RiderID (ATF), FirstName, LastName, MaleFemale, DateOfBirth, ATF12 and ATF13, in the default TEXT format.

Appending some additional parameters will filter this by bib and change the format to XML

https://api.raceresult.com/111952/6XENXE0KZY1NBFJDB57UQWS14R0L6R2H?&filterbib=11&listformat=XML

Update Fields

It is possible to update values in RACE RESULT 12 using custom API calls, this could be used for any field including participant details, ATF / AYN fields, Status and Comment fields and more. This method will update a single field.

To SAVE field data use a Custom API with:

part/savevalue?

There are some additional paramters which can be appended here, parameters can either be used in the API details in RACE RESULT 12 if they should apply to all API calls, or can be appended to the end of the API url in the API call, when appending to the API url then append "?" before the first parameter.

&bib=
The bib number which should be updated, updates can only be applied to a single bib at a time in this way. 

&fieldname=
The name of the field which should be updated

&value=
The new value for the field

&nohistory=
If participant history record should be updated set this to 0, if not then set to 1

 

Example:

API Details: part/savevalue
URL: https://api.raceresult.com/111952/FCMAAKQOYEI6YHU7JBAM6YLK8J5485TG?&bib=11&fieldname=Status&value=4&nohistory=0

Sets the value of the Status field to 4 (DNS) for bib number 11, this change is saved in the participant history

Insert / Update Participants

Participants can be inserted to RACE RESULT 12 using a POST request to the API including the participant data in the Body, this will also update any participant data for participants already entered in to the software, matching on bib number. Note that when updating participants this will not update any Age Groups, you will need to trigger this separately if the data has changed. 

To insert / update participants use a Custom API with:

part/savefields?

 

Body

Participant data should be parsed in JSON format, you can send any number of data fields and only those which are sent will be updated, note that bib must be sent always. The format should look as follows:

{"Bib":"123","CreatedBy":"Username","Lastname":"Doe","Firstname":"John","DateOfBirth":"1993-01-01","Sex":"m","Contest":"1","ATF1":"Red"}

To send multiple participant records in one then the format is extended as such:

[{ Participant Data 1.....},{ Participant Data 2.....},{ Participant Data 3.....}]

The whole body is wrapped in square brackets with commas between each record. 

Custom API Field Exceptions

APIs can be used to update and call any data fields which can normally be imported, derived / calculated fields cannot be inserted or updated via APIs.

Since APIs interact directly with the database there are certain fields which need to be called differently when used to call fields in a list, used as part of a filter or when updating fields.

Gender - Internally stored as Sex

State - For English state names / abbreviations this is internally stored as State2. 

RaceMap Access

To link the participants data of a RACE RESULT 12 file to a Racemap, you need to use the simple API feature under Main Window > Access rights / Simple API

In the Type setting, select "Racemap Access".


 

An integration is automatically created, with the default settings above. These should be fine for most events, but you can edit them where needed.

Here is more information about each field, and what you should put in them:

  • Id: should contain a numerical value that is unique through the event file and does not change.
  • RaceNr: that field will be displayed on each participant's flag in the timing visualisation. It is typically the bib number, but can be anything you like (it can even include text and emojis) and does not need to be unique.
  • Transponder1 and Transponder2: chip codes assigned to a participant via the corresponding data fields. If you are using a chip file instead of these two fields to assign chips, replace Transponder1 with TransponderInChipFile in the Transponder1 field.
  • Contest: typically, the contests as set up in RACE RESULT 12. However, you can use this field to group participants into any categories relevant to Racemap, for example if participants from a given contest do not all perform the same course.
  • Visibility: leave as "public" so participants show up in the Racemap
  • Start and Finish: needs to contain the start and finish time of day (in UTC time) of the participants, or be left blank. When filled, Racemap uses these fields to ignore trackpings before / after a participant is on course, so it is critical that they are properly set up, or blank.
  • Custom: use this field to add any extra information. You will need to liaise with Racemap to make sure they can actually make any use of what you put there.