API V4.0

Welcome to the RegattaCentral API!

The RegattaCentral API provides a RESTful interface to data which is available from RegattaCentral, such as upcoming and past regattas, the events, entries and in many cases the results from the regatta. It also provides methods for timing and regatta management systems to exchange data during the operation of a regatta.

This document is intended to detail all of the available data sets and methods of access to the data. It provides JavaScript $ajax examples of the calls. Examples of how other programming languages might be used to create HTTPS requests are also provided here.

All API endpoints require either an API-Key or an OAuth2 token. (See Authentication Information for complete details) If you wish to execute the examples provided within this document, you will first have to obtain a client-id (if you don't already have one) and then use your client-id, client-secret, RegattaCentral username and password to obtain an OAuth2 token. This token will then be utilized as the Authorization string when you execute the examples. Do not Reload/Refresh your page or you will have to obtain a new OAuth2 token.

The data schema is available in 2 ways. You may retrieve the entire schema using the example below, or you may review the schema via the Data Types and Layout page. You can explore the relations between data and/or you can download the entire schema description "rc-api.xsd". Many languages have tools which will create classes from a .xsd file making the exchange of data between systems much easier.

For regatta management and timing systems we also supply a API V4 Cookbook which provides many additional examples and discusses various flows of data before and during a regatta.

Connections to RegattaCentral are required to use TLS 1.1 or higher.

Comments and suggestions are welcome! Please email us at [email protected].

Programming Considerations and Examples

  • Cross-Origin HTTP requests are only allowed if you have defined a "referer" for your client ID. This referer URL must be supplied as the "Origin:" header of all requests made from a web page which is served by your server. You may change the referer by re-entering your information on the Client ID Request form.
  • The examples throughout the documentation show JS/JQuery examples of each call. Click on the tabs below to see an example of a call in each of these languages. Each of these examples show how to request the authorization token. 
$.ajax({
	type: "POST",
	url: 'https://api.regattacentral.com/oauth2/api/token',
    data: 'client_id={client_id}&client_secret={client_secret}&username={username}&password={password}&grant_type=password',
    success: function (data) {
	        // Process & Display Data
	},
    error: function () {
	    alert('Error processing request.');
	}
});

Code: Java

package com.regattacentral.dataexchange.utils;

import java.net.MalformedURLException;

import org.apache.oltu.oauth2.client.response.OAuthAccessTokenResponse;
import org.apache.oltu.oauth2.common.exception.OAuthProblemException;
import org.apache.oltu.oauth2.common.exception.OAuthSystemException;

public class RegattaCentralOAuth {

	public String getToken(String clientId, String clientSecret, String username, String password) throws AuthorizationException {
		try {
			OAuthAccessTokenResponse oAuthResponse = OAuth2Client.requestToken(
					clientId, clientSecret, username, password );
			if (oAuthResponse != null && oAuthResponse.getAccessToken() != null) {
				System.out.println("Token: " + oAuthResponse.getAccessToken());
				System.out.println("Token: " + oAuthResponse.getRefreshToken());
				System.out.println("Token: " + oAuthResponse.getExpiresIn());
				return oAuthResponse.getAccessToken();
			}
		} catch (MalformedURLException e) {
			throw new AuthorizationException("Invalid authorization connection string");
		} catch (OAuthSystemException e) {
			throw new AuthorizationException("Authorization Failed - please try again");
		} catch (OAuthProblemException e) {
			throw new AuthorizationException("Authorization Failed - please try again");
		}
		return "";
	}
}


package com.regattacentral.dataexchange.utils;

import java.net.MalformedURLException;

import org.apache.oltu.oauth2.client.OAuthClient;
import org.apache.oltu.oauth2.client.URLConnectionClient;
import org.apache.oltu.oauth2.client.request.OAuthClientRequest;
import org.apache.oltu.oauth2.client.response.OAuthAccessTokenResponse;
import org.apache.oltu.oauth2.common.exception.OAuthProblemException;
import org.apache.oltu.oauth2.common.exception.OAuthSystemException;
import org.apache.oltu.oauth2.common.message.types.GrantType;

public class OAuth2Client {
	
	public static OAuthAccessTokenResponse requestToken(String clientId, String clientSecret, String username, String password) throws MalformedURLException, OAuthSystemException, OAuthProblemException {
		OAuthClientRequest request = OAuthClientRequest
				.tokenLocation("https://api.regattacentral.com/oauth2/api/token")
				.setGrantType(GrantType.PASSWORD)
				.setClientId(clientId)
				.setClientSecret(clientSecret)
				.setUsername(username)
				.setPassword(password).buildBodyMessage();

		OAuthClient oAuthClient = new OAuthClient(new URLConnectionClient());
		OAuthAccessTokenResponse oauthResponse = oAuthClient.accessToken(request);
		return oauthResponse;
	}

	public static OAuthAccessTokenResponse refreshToken(String oauth2ServerURL, String clientId, String clientSecret, String refreshToken) throws MalformedURLException, OAuthSystemException, OAuthProblemException {
		OAuthClientRequest request = OAuthClientRequest
				.tokenLocation("https://api.regattacentral.com/oauth2/api/token")
				.setGrantType(GrantType.REFRESH_TOKEN)
				.setClientId(clientId)
				.setClientSecret(clientSecret)
				.setRefreshToken(refreshToken).buildBodyMessage();

		OAuthClient oAuthClient = new OAuthClient(new URLConnectionClient());
		OAuthAccessTokenResponse oauthResponse = oAuthClient.accessToken(request);
		return oauthResponse;
	}


}

Code: PHP

function getToken() {
	$postData = array(
    	'client_id' => '{client_id}',
	    'client_secret' => '{client_secret}',
	   	'username' => '{username}',
	   	'password' => '{password}',
		'grant_type' => 'password'
	);
	// Create the context for the request
	$context = stream_context_create(array(
	    'http' => array(
		    'method' => 'POST',
	   		'header' => "Accept: application/json\r\n"."Content-Type: application/x-www-form-urlencoded\r\n",
        	'content' => http_build_query($postData)
	    )
	));
	// Send the request
	$response = file_get_contents('https://api.regattacentral.com/oauth2/api/token', FALSE, $context);

	// Check for errors
	if($response === FALSE){
		die('Error');
	}
	// Decode the response
	$responseData = json_decode($response, TRUE);
	
	// Print the date from the response	
	echo 'Token: '.$responseData['access_token'].'\r\n';
	echo 'Refresh Token: '.$responseData['refresh_token'].'\r\n';
	echo 'Expiration: '.$responseData['expiration'].'\r\n';
}

Code: .Net

Namespace RcDb
        Public Class OAuthToken

        Public expires_in As String = ""
        Public refresh_token As String = ""
        Public access_token As String = ""
        
        Public CreatedTime As DateTime = DateTime.UtcNow
                
        
    End Class
End Namespace

Imports Newtonsoft.Json

Public Class RcTokenMgr

    Private Const ChilkatHTTPKey As String = "{Chilkat key}"
    Private Const RCID As String = "{client-id}"
    Private Const RCSECRET As String = "{client-secret}"
    Private Const RCTOKENURL As String = "https://api.regattacentral.com/oauth2/api/token"

    Public ServerResponse As String = ""

    Private Property _AuthToken As RcDb.OAuthToken

    Private Property _AuthTokenTimeRequested As DateTime = Nothing
    Private Property _AuthTokenTimeExpiry As DateTime = Nothing

    Private _UserId As String = String.Empty
    Public WriteOnly Property UserId() As String
        Set(ByVal value As String)
            _UserId = value
        End Set
    End Property

    Private _UserPw As String = String.Empty
    Public WriteOnly Property UserPw() As String
        Set(ByVal value As String)
            _UserPw = value
        End Set
    End Property

    Private _IsCallSuccessful As Boolean
    ''' 
    ''' True if send or receive was successful, nothing, if no data sent or received.
    ''' 
    ''' 
    Public ReadOnly Property IsCallSuccessful() As Boolean
        Get
            Return _IsCallSuccessful
        End Get
    End Property

    Private _ErrorMessage As String = String.Empty
    ''' 
    ''' Errors, and or exceptions, empty, if none encountered.
    ''' 
    ''' 
    Public ReadOnly Property ErrorMessage() As String
        Get
            Return _ErrorMessage
        End Get
    End Property

    Private Function RCauth() As Boolean

        Me._AuthTokenTimeRequested = DateTime.UtcNow

        'authentication with RC user and pw
        Dim http As New Chilkat.Http()
        Dim retVal As String = String.Empty
        Dim success As Boolean = http.UnlockComponent(ChilkatHTTPKey)
        If (success <> True) Then
            Return False
        End If

        If Me._UserId = String.Empty And Me._UserPw = String.Empty
            Throw New Exception("You must provide valid credentials for the Regatta Central API.")
        End If
        Dim req As New Chilkat.HttpRequest()
        req.AddParam("client_id", RCID)
        req.AddParam("client_secret", RCSECRET)
        req.AddParam("username", _UserId)
        req.AddParam("password", _UserPw)
        req.AddParam("grant_type", "password")
        Dim resp As Chilkat.HttpResponse
        resp = http.PostUrlEncoded(RCTOKENURL, req)
        retVal = resp.BodyStr
        Me.ServerResponse = retVal
        Try
            Me._AuthToken = JsonConvert.DeserializeObject(Of RcDb.OAuthToken)(retVal)
        Catch ex As Exception
            Me._ErrorMessage = String.Format("Unable to parse oauth token.  Check token manager ""ServerResponse"" property to see what the server returned.  Additional exception: {0}", ex.Message)
            Me._IsCallSuccessful = False
            Return False
        End Try

        Me._AuthTokenTimeExpiry = _AuthTokenTimeRequested.AddSeconds(CType(Me._AuthToken.expires_in, Double))
        Me._ErrorMessage = String.Empty
        Me._IsCallSuccessful = True
        Return True

    End Function

    Public Function RefreshRcAuth
        'refresh authentication
        Dim http As New Chilkat.Http()
        Dim retVal As String = String.Empty
        Dim success As Boolean = http.UnlockComponent(ChilkatHTTPKey)
        If (success <> True) Then
            Return False
        End If

        If Me._UserId = String.Empty And Me._UserPw = String.Empty
            Throw New Exception("You must provide valid credentials for the Regatta Central API.")
        End If
        Dim req As New Chilkat.HttpRequest()
        req.AddParam("client_id", RCID)
        req.AddParam("client_secret", RCSECRET)
        req.AddParam("refresh_token", Me._AuthToken.refresh_token)

        Dim resp As Chilkat.HttpResponse
        resp = http.PostUrlEncoded(RCTOKENURL, req)
        retVal = resp.BodyStr

        Me._AuthToken = JsonConvert.DeserializeObject(Of RcDb.OAuthToken)(retVal)
        Me._ErrorMessage = String.Empty
        Me._IsCallSuccessful = True
        Return True
        Try

        Catch ex As Exception
            'MsgBox("Error - unable to connect.", vbOKOnly, "Regatta Central Authentication")
            Me._ErrorMessage = String.Format("Unable to get OAuthToken from Regatta Central.{0}Exception: {1}", Environment.NewLine, ex.Message)
            Me._IsCallSuccessful = False
            Return False
        End Try
    End Function

    Public Function GetValidToken As RcDb.OAuthToken
        If Me._AuthTokenTimeRequested = Nothing
            'Get new token
            If Me.RCauth
                Return Me._AuthToken
            End If
        Else
            'Check to see if token is expired.
            If DateTime.UtcNow > Me._AuthTokenTimeExpiry
                'Auth token is expired. Get new token.
                If Me.RCauth
                    Return Me._AuthToken
                End If
            End If
        End If

        'Auth token is still valid.
        Return Me._AuthToken

    End Function

    Public Sub New(ByVal strUserId As String, ByVal strUserPw As String)
        Me._UserId = strUserId
        Me._UserPw = strUserPw

    End Sub

End Class

Regattas Schema

This service will return the schema of the Regattas structure.

URL: https://api.regattacentral.com/v4.0​/schema

Secure This is a secure API and requires OAuth2 authentication.

Returns

Text
A representation of the Regattas JSON schema.

Code: JavaScript + jQuery

										$.ajax({
    type: "GET",
    url: 'https://api.regattacentral.com/v4.0​/schema',
    headers: {"Authorization": "hex-authorization-code-goes-here",
              "Accept": "application/json"},
    success: function (data) {
        // Process and Display Data
    },
    error: function () {
        alert('Error processing request.');
    }
});

Results: JSON

RegattaCentral © 2024 | Support | Privacy