Request your access token: https://api.racecheck.com/request-access-token/

Read the latest official documentation: https://api.racecheck.com/documentation/

Introduction

The Racecheck API is structured around REST, HTTP, and JSON. All API endpoints are organized around models such as races, reviews, ratings, etc. The HTTP method GET is used to retrieve results. As the Racecheck API is still under active development the API endpoints and request structures are liable to change.

Errors

Sometimes requests to the Racecheck API are not successful, and these failures can occur for a number of reasons. In the event of a failed request, the API will return an HTTP Status Code that can be used to determine the cause of the failure.

Use the table below to help understand what went wrong with your request.

Code	Header	Description
400	Bad Request	The request could not be understood by the server due to incorrect syntax. Do not repeat the request before modifying request parameters/syntax.
403	Forbidden	Request syntax is correct, however the server will not complete the request due to the fact the user is not authorised to access the resource they are requesting.
404	Not Found	The server did not find a current representation for the target resource or is not willing to disclose that one exists.
500	Internal Server Error	The server encountered an unexpected condition that prevented it from fulfilling the request.

Get races - `GET`

This API endpoint is used to retrieve and filter races.

Various query parameters can be used to refine and filter your results. Below is a list of supported parameters along with their rules, conventions and usage descriptions.

The response is in JSON format. The count indicates the number of results and the next and previous keys are used to determine whether there are additional pages that can be requested for the given filters. The results key contains the list of races matching the filtering criteria.

Parameters

Name Description

event_type (optional) Either a single event type or a list of event types can be used to filter what type of events will be retrieved. The event types are: road-running, off-road-running, triathlon, duathlon, cycling, swimming, ocr, aquathlon, swimrun, aquabike, virtual.
The list of event types can also be retrieved from the Get event types API endpoint.

lat (optional) The latitude of the location around which the search will be performed.

lon (optional) The longitude of the location around which the search will be performed.

range (optional) The maximum range (in km) around the location in which the search will be performed. Default 100km, if location is well defined.

country (optional) The country (slug) in which the search will be performed. When applied, lat, lon and range fields are overwritten.
The list of countries can be retrieved from the Get countries API endpoint.

from_date (optional) Starting date in YYYY-MM-DD format. Default date is the current date.

to_date (optional) Ending date in YYYY-MM-DD format. No limit by default.

unit (optional) Can be km for kilometers or mi for miles. Default unit is kilometers.

min_distance (optional) The minimum distance value in the defined unit. Default no minimum distance value.

max_distance (optional) The maximum distance value in the defined unit. Default no maximum distance value.

distance_title (optional)

The title of the distance. Must be a valid distance title for the specified event type from the distance title list. When applied, min_distance and max_distance fields are overwritten.
The list of distance titles per event type can also be retrieved from the Get distance titles API endpoint.

Running distance title	Min distance	Max distance
5km	5.00km	5.00km
10km	10.00km	10.00km
half-marathon	21.00km	21.20km
marathon	42.00km	42.30km
ultra	42.31km	-

Triathlon distance title	Min total distance	Max total distance
super-sprint	0.01km	20.90km
sprint	20.91km	40.00km
standard	40.01km	70.00km
middle	70.01km	150.00km
long	150.01km	230.00km
ultra	230.01km	-

Duathlon distance title	Min total distance	Max total distance
super-sprint	0.01km	22.00km
sprint	22.01km	42.00km
standard	42.01km	70.00km
long	70.01km	-

Cycling distance title	Min distance	Max distance
short	0.01km	50.00km
middle	50.01km	150.00km
long	150.01km	-

Swimming distance title	Min distance	Max distance
up-to-1km	0.01km	1.00km
up-to-3km	1.01km	3.00km
3km+	3.01km	-

OCR distance title	Min distance	Max distance
up-to-5km	0.01km	5.00km
up-to-10km	5.01km	10.00km
10km+	10.01km	-

Aquathlon distance title	Min total distance	Max total distance
short	0.01km	12.00km
middle	12.01km	20.00km
long	20.01km	-

Swimrun distance title	Min total distance	Max total distance
short	0.01km	15.00km
middle	15.01km	40.00km
long	40.01km	-

Aquabike distance title	Min total distance	Max total distance
short	0.01km	31.00km
intermediate	31.01km	52.00km
long	52.01km	103.00km
ultra	103.01km	-

event_features (optional) Either a single event feature or a list of event features can be used to filter what type of events will be retrieved. Default includes all event features. The event features are: suitable-for-beginners, spectator-friendly, babysitting-facilities-available, women-only, free-parking, post-event-food-and-refreshments, free-massage and family-entertainment.
The list of event features can also be retrieved from the Get event features API endpoint.

course_features (optional)

Course features are sport category specific, and therefore you can only specific the course features for a single sport category. Default all course features for all sport categories. Both the course_features_sport and course_features parameters must be defined.
The list of course features can also be retrieved from the Get course feartures API endpoint.

Sport category	Course features
running	mostly-flat, hilly, undulating
swimming	pool, river, lake, sea
cycling	mostly-flat, hilly, undulating

age_range (optional) Can be either adult or junior. Default all age ranges.

min_average_rating (optional) The minimum total average rating of the event. Default no minimum average rating.

min_reviews (optional) The minimum number of reviews an event must have to be returned. Default no minimum number of reviews.

sorting (optional) A single parameter (distance, date, average_rating or reviews) can by specified by which the results will be sorted in ascending (asc) or descending (desc) order. Default sorting is date,asc.

page (optional) The page number to retrieve. Default page value is 1. Returns empty results list if page exceeds the maximum number of pages.

Race search - `GET`

This API endpoint is used to search for Races based on their name and accepts a single parameter, as explained below.

Parameters

Name	Description
q (*required)	A string that is to be used as the query term.

Get event reviews - `GET`

This API endpoint is used to retrieve all reviews that have been left for the event provided in the URL.

Parameters

Name	Description
event_id (*required)	The numeric event ID for which you want to retrieve reviews for. The event_id can be found in a Race Search or Get Races response.

Get event reviews by year - `GET`

This API endpoint is used to retrieve all reviews from the specified year that have been left for the event provided in the URL.

Parameters

Name	Description
event_id (*required)	The numeric event ID for which you want to retrieve reviews for. The event_id can be found in a Race Search or Get Races response.
year (*required)	The year for which you want to retrieve reviews from.

Get event types - `GET`

This API endpoint is used to retrieve all existing event types.

The response is in JSON format. The results key contains the list of supported event types, along with their slugs, that can be used as query parameters in Get races requests.

Get distance titles - `GET`

This API endpoint is used to retrieve distance titles.

Retrieves all existing distance titles per event type. An event type slug can be specified in the URL to filter the results.

The response is in JSON format. The results key contains the list of supported distance titles (per event type), along with their slugs, that can be used as query parameters in Get races requests.

Parameters

Name	Description
event_type (optional)	The slug of the event type for which you want to retrieve the distance titles for. The event_type can be found in a Get event types response.

Get event features - `GET`

This API endpoint is used to retrieve all existing event features.

Get course features - `GET`

This API endpoint is used to retrieve all existing course features.

The response is in JSON format. The results key contains the list of supported course features per activity, that can be used as query parameters in Get races requests.

Get countries - `GET`

This API endpoint is used to retrieve all supported countries.

The response is in JSON format. The results key contains the list of supported countries, along with their slugs, that can be used as query parameters in Get races requests.

Request your access token: https://api.racecheck.com/request-access-token/

Read the latest official documentation: https://api.racecheck.com/documentation/

Introduction

Errors

Get races - GET

Race search - GET

Get event reviews - GET

Get event reviews by year - GET

Get event types - GET

Get distance titles - GET

Get event features - GET

Get course features - GET

Get countries - GET

Get races - `GET`

Race search - `GET`

Get event reviews - `GET`

Get event reviews by year - `GET`

Get event types - `GET`

Get distance titles - `GET`

Get event features - `GET`

Get course features - `GET`

Get countries - `GET`