Benutzerdefinierte APIs ermöglichen Ihnen eine weitere Verfeinerung von API Ausgaben sowie weitere, fortgeschrittene Funktionen.

Die nachfolgende Dokumentation stellt einige der Funktionen von benutzerdefinierten APIs vor. Haben Sie besondere Anforderungen, wenden Sie sich mit diesen an den race|result Support.

Eigene Counter

So wie die voreingestellten Counter die Teilnehmer des ausgewählten Wettbewerbs zählen, so können Sie einen beliebigen Filter anwenden, um eine Anzahl Teilnehmer über die API zu übermitteln.

Hierfür schreiben Sie eine benutzerdefinierte API mit:

Data/count?filter=

Nun können Sie einen gewöhnlichen Ausdruck als Filter verwenden (Vorsicht: Ausdruck muss auf Englisch sein), z.B. [Contest]=1 AND [Firstname]="Max". Der Ausdruck allerdings muss URL encoded sein.

Im Beispiel wird daraus: %5BContest%5D%3D1AND%5BFirstname%5D%3D%22Max%22

Der gesamte Filter lautet also:
Data/count?filter=%5BContest%5D%3D1AND%5BFirstname%5D%3D%22Max%22

Daten aus Listen

In manchen Fällen möchten Sie lediglich weitere Filter auf Ausgabelisten legen oder anpassen, ohne jeweils weitere Ausgabelisten anzulegen. Um per Simple API auf Daten aus Listen zuzugreifen, erstellen Sie eine benutzerdefinierte API mit:

data/list?

An diesen Ausdruck können Sie weitere Parameter anhängen. Parameter können entweder im API Ausdruck in RACE RESULT 14 angehängt werden, wenn sie sich auf alle API Aufrufe beziehen sollen, oder an die URL angehängt werden, wenn der Parameter nur für diesen Aufruf gelten soll. Wenn Sie den Ausdruck an die URL anhängen, setzen Sie ein "?" vor den ersten Parameter. Beachten Sie, dass die Standard-Feldnamen im String Englisch sein müssen.

&fields=
Bestimmt, welche Felder aufgelistet werden. Mehrere Felder müssen mit "%2C", dem URL codierten Format von ",", verbunden werden.

&sort=
Bestimmt, wie die Daten sortiert werden.

&filterbib=
Filtert die Liste nach der Startnr.

&filter=
Ermöglicht das Filtern. Mehrere Filter können über AND verbunden werden, Sonderzeichen im String müssen mit dem entsprechend URL codierten Äquivalent geschrieben.

&listformat=
Bestimmt das Format der Liste (z.B. Simple, CSV, XML, JSON)

&separator=
Bestimmt das Trennzeichen im TEXT- oder CSV-Format

Beispiel:

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

Liefert eine Liste aller Fahrer mit der RiderID (ZTF), Vorname, Nachname, MännerFrauen (benutzerdef. Feld), Geburtstag, ZTF12 und ZTF13 in einem Standard TEXT Format.

Durch Anhängen weiterer Parameter kann die Liste beim Aufruf nach der Startnummer gefiltert und das Format zu XML angepasst werden.

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

Felder aktualisieren

Sie können Werte in RACE RESULT 14 durch benutzerdefinierte API Aufrufe ändern. Änderungen können in sämtlichen Feldern vorgenommen werden, inkl. Teilnehmerdaten, Zusatzfeldern, Status, Kommentar u.v.m.

Um Änderungen durchzuführen, nutzen Sie eine benutzerdefinierte API mit:

part/savevalue?

&bib=
Die Startnummer, für die Werte aktualisiert werden sollen. Änderungen können auf diese Weise immer nur für eine Startnummer vorgenommen werden.

&fieldname=
Das Feld, dessen Inhalt geändert werden soll.

&value=
Der neue Wert für das Feld.

&nohistory=
Wenn die Änderung in der Teilnehmerhistorie gespeichert werden soll, setzen Sie den Wert auf 0, ansonsten auf 1.

Beispiel:

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

Setzt den Status-Wert von Startnummer 11 auf 4 (DNS). Die Änderung wird in der Teilnehmerhistorie gespeichert.

Teilnehmer einfügen / aktualisieren

Teilnehmer können über eine POST-Anfrage, die die Teilnehmerdaten im Body enthält, in RACE RESULT 14 geschrieben werden. Die Anfrage führt auch Änderungen an bereits bestehenden Teilnehmerdaten basierend auf der Startnummer als eindeutiges Kriterium durch. Wenn Sie Teilnehmer updaten, werden Altersklassen nicht automatisch angepasst. Diese müssen manuell aktualisiert werden.

Um Teilnehmer zu schreiben / aktualisieren, verwenden Sie eine benutzerdefinierte API mit:

part/savefields?&lang=en

Body

Teilnehmerdaten sollten im JSON Format geparsed werden. Sie können eine beliebige Anzahl Felder senden. Nur die aufgeführten Felder werden beschrieben / aktualisiert. Beachten Sie, dass die Startnummer als eindeutige ID immer gesendet werden muss. Das Format sieht wie folgt aus:

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

Um mehrere Teilnehmer auf einmal zu senden, wird das Format wie folgt erweitert:

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

Der gesamte Body ist in eckige Klammern gehüllt, mit Kommata zwischen den einzelnen Teilnehmern.

Ausnahmen bei Feldern in benutzerdefinierten APIs

APIs können verwendet werden, um jedes beliebige Eingabe-Datenfeld abzurufen und zu ändern. Abgeleitete/Berechnete Felder können nicht über APIs beschrieben oder upgedated werden.

Da APIs direkt mit der Datenbank verbunden sind, gibt es einige Felder, die intern einen anderen Namen haben, als bspw. beim Abrufen in Ausgabelisten.

Gender - Intern als Sex angelegt

State - Lediglich für Amerikanische Bundesstaaten ist die Abkürzung intern als State2 angelegt.

Eventdaten

Sie können auf bestimmte Listen oder Eventeinstellungen über API-Links zugreifen. Dies kann nützlich sein, wenn Sie diese in externe Anmeldeplattformen o.ä. einbinden möchten.

Unterstützte Listen:

Rawdata/get
Contests/get
Timingpoints/get
Ranks/get
Results/get

Versand von Email-Vorlage

Über die Simple API kann der Versand von vordefinierten Email-Vorlagen getriggert werden. Dies ist vor allem nützlich für semi-permanente Veranstaltungen, bei denen Teilnehmer automatisch eine Finisher-Email erhalten sollen, da der Browser nicht dauerhaft geöffnet bleiben muss. Für übliche Veranstaltungen ist InstantPush hierfür die bessere Option, da dies aber dauerhaft geöffnet bleiben muss, ist es für länger währende Veranstaltungen nur bedingt zu empfehlen.
Der Versand von SMS ist aufgrund von weiteren Sicherheitseinstellungen über die Simple API nicht möglich.

Um EMail-Vorlagen über die Simple API zu verschicken, erstellen Sie eine benutzerdefinierte API mit folgenden Parametern:

emailtemplates/send?

Hieran müssen Sie weitere Parameter anfügen. Entweder direkt in den API-Einstellungen in RACE RESULT 14, wenn diese Parameter für alle API-Calls gültig sind, oder fügen Sie die Parameter an das Ende der API-URL, wenn sie nur für diesen einen Call gelten sollen. Wenn Sie Parameter an die URL anhängen, setzen Sie ein "?" vor den ersten Parameter.

&name=

Bestimmt den Namen der EMail-Vorlage, die verwendet werden soll.

&filter=

Bestimmt, an welche Teilnehmer die Vorlage versendet werden soll. Fügen Sie Standard-Filter hinzu, und denken Sie an die korrekte URL-Enkodierung. Mehrere Filter können per AND kombiniert werden.