Introduction

Welcome to the Sim Racing Limited Venue Management System (VMS) API! You can use the API to access data for use in your internal business systems or for creating customer-facing applications, and to add data to your VMS database from your own systems.

Please ensure that you use proper parsing libraries to handle the API responses, as additional fields may be added to endpoint output in the future. We aim never to remove fields from the output in a specific API version.

If you experience any issues, or feel that improvements could be made in either the API or the documentation, please don't hesitate to contact us.

Authentication

# With shell, you can just pass the correct header with each request
curl "https://api.simracing.co.uk/v0.1/api_endpoint_here" \
  -H "Authorization: SRL <your-API-key>"

Sim Racing Limited uses API keys to grant access to the API. API keys may be generated via the API section of the Account Management pages.

We strongly encourage that each application you write that requires API access has a separate API key. This means that should an API key need to be revoked, only a single application will be affected. For the same reason, we also encourage that you reference the API key in a single location in your application.

API keys may be generated via the Account Management site. Please contact us if you require additional keys.

API keys may be revoked/regenerated at your request, or may be revoked if we detect that the key has been compromised. Wherever possible we will attempt to contact you before revoking a key.

The VMS API requires the API key to be included in all API requests to the server in a header that looks like the following:

Authorization: SRL <your-API-key>

You must replace <your-API-key> with your personal API key.

Permissions

New API keys initially only have read access to the VMS database, so cannot alter any data, and also do not have access to your customers' personally identifiable information, such as their e-mail addresses and phone numbers.

If you attempt to access an API endpoint which the key does not have permission to access, you will receive a 403 Forbidden error, and a response body stating that 'API key permissions do not permit access to this resource'.

API key permissions must be configured to allow write access and/or access to customer PII, as well as to choose the specific endpoints that can be accessed. Not all licence levels allow all API key permissions to be altered. Available API key permissions can be configured via the API section of the Account Management pages.

Protocol Security

All requests made to the VMS API must be made via TLS (SSL) to the default HTTPS port, 443. This ensures the security and integrity of communications between Sim Racing Limited systems and your application.

Please ensure that the client or language you use to interact with the VMS API supports TLS 1.0 or higher. TLS 1.2 is recommended, as TLS 1.0 and 1.1 support may be deprecated in future API releases.

Compression

Gzip compression of returned data is optionally available for all endpoints. Gzip compression is recommended for applications that frequently transfer a lot of data (for example, a custom SWP replacement that may have to display several hundred laps at a time), or for applications that transfer data over unreliable network links such as a cellular network.

Gzip compression may be enabled by setting the following header in the request:

Accept-Encoding: gzip

If this header is set, your application will need to decompress the data before parsing it. Many libraries include inbuilt support for gzip decompression.

Rate Limiting

To prevent excessive load on the servers, and to provide good performance for all licensees, all API keys have associated rate limits for requests. Rate limits are reset at the start of every hour.

The rate limit for your API key(s) may be viewed in the API section of the Account Management site. Our default rate limit for API keys is 2,000 requests/hour. Your current and historic usage may also be viewed by clicking on the graph icon next to the relevant API key in the Account Management site.

A secondary rate limit also applies for exports of lap telemetry data, with a default limit of 180 exports/hour. This limit does not affect any other API endpoints.

Please contact us if you find your rate limits to be restrictive to your routine usage patterns.

Timezones

# With shell, you can just pass the correct headers with each request
curl "https://api.simracing.co.uk/v0.1/api_endpoint_here" \
  -H "Authorization: SRL <your-API-key>" \
  -H "timezone-offset: <your-offset>" \

API queries which check whether something is in the past or the future require knowledge of the timezone of your request in order to accurately determine this information. Currently this includes listing hotlapping events, and listing bookings. If you wish to use the 'past' and 'future' query parameters with these endpoints, we highly recommend providing your timezone, otherwise the current UTC time will be used to determine whether something is in the past or the future.

Your timezone should be provided in a header named timezone-offset, which takes a positive or negative value specifiying the offset from UTC to use. For example, if you are on the west coast of the US, and daylight savings time is not active, you should include a header that looks like the following:

timezone-offset: -8

You may include the timezone offset header in all API requests, to ensure that it is used when appropriate.

The timezone offset header does not alter the date or time fields of returned results. All date and time fields are considered to be in the local venue time, so are not translated.

If you do not wish to provide your timezone offset, it is highly recommended that you do not rely on 'past' or 'future' query parameters, and instead retrieve all data from a specific endpoint, and locally process the data to determine whether something is in the past or future.

Return and Error Codes

The VMS API uses the following return codes:

Return Code	Meaning
200	OK -- Your request was successful.

The VMS API uses the following error codes:

Error Code	Meaning
400	Bad Request -- Your request had invalid, missing or conflicting data. Usually, an error message will also be returned with more information.
401	Unauthorized -- Your API key is incorrect or invalid.
403	Forbidden -- Either the API key permissions are set to disallow your request, or the account licence does not permit access to the specified API endpoint. Contact Sim Racing Limited for upgrade options.
404	Not Found -- The API endpoint was incorrect.
405	Method Not Allowed -- Your request was not valid for the specified API endpoint.
429	Too Many Requests -- You have exceeded the API rate limit for your API key. If exporting telemetry data, a secondary rate limit also applies.
500	Internal Server Error -- We had a problem fulfilling the request. Try again later or contact support.
503	Service Unavailable -- We're temporarially offline for maintanance. Please try again later.

Retrieving Data

An HTTP GET request should be made to the appropriate endpoint, documented below, to retrieve information from the API. Ensure that you include your API key in all requests, as documented in the authentication instructions.

Bookings

Access to the booking endpoints requires the bookings feature to be enabled for your VMS account. If this feature is not enabled, you will receive a 403 error when attempting to access these endpoints.

List Bookings

curl "https://api.simracing.co.uk/v0.1/bookings" \
  -H "Authorization: SRL <your-API-key>"

<?xml version="1.0" encoding="utf-8"?>
<bookings>
  <booking>
    <id>1</id>
    <event_name>Christmas Eve Party!</event_name>
    <start_date>2018-12-24 18:00:00</start_date>
    <end_date>2018-12-24 22:00:00</end_date>
    <status>Booked</status>
    <venue_id>1</venue_id>
    <venue_name>Venue One</venue_name>
    <event_activity>Hotlapping</event_activity>
    <group_size>60</group_size>
    <number_of_pods>10</number_of_pods>
    <requested_vehicles>
      <vehicle>
        <vehicle_id>1</vehicle_id>
        <vehicle_name>1991 McLaren MP4/6</vehicle_name>
        <vehicle_uri>https://api.simracing.co.uk/v0.1/vehicles/1</vehicle_uri>
      </vehicle>
      ...
    </requested_vehicles>
    <requested_circuits>
      <circuit>
        <circuit_id>1</circuit_id>
        <circuit_name>A1 Ring - GP</circuit_name>
        <circuit_uri>https://api.simracing.co.uk/v0.1/circuits/1</circuit_uri>
      </circuit>
      ...
    </requested_circuits>
    <participants>
      <customer>
        <customer_id>1</customer_id>
        <customer_name>Jim Clark</customer_name>
        <customer_uri>https://api.simracing.co.uk/v0.1/customers/1</customer_uri>
      </customer>
      ...
    </participants>
    <staffing_notes>Peter unavailable to assist due to vacation.</staffing_notes>
    <notes>Whole venue booking for Christmas party.</notes>
    <payment_notes>20% deposit paid in advance, remainder to be paid on day.</payment_notes>
    <venue_uri>https://api.simracing.co.uk/v0.1/venues/1</venue_uri>
  </booking>
  ...
</bookings>

This endpoint lists all available bookings.

HTTP Request

GET https://api.simracing.co.uk/v0.1/bookings

Query Parameters

Parameter	Default	Description
past	`1`	Include historic bookings.
future	`1`	Include bookings in the future.

Notes

When using the 'past' and 'future' query parameters to filter results, it is highly recommended that you also supply your timezone, to ensure accurate results.
Depending on the booking, either a number_of_pods field, containing a single number, or a specific_pods field, containing a list of comma-separated pod numbers, may be present.

Get a Specific Booking

curl "https://api.simracing.co.uk/v0.1/bookings/1" \
  -H "Authorization: SRL <your-API-key>"

<?xml version="1.0" encoding="utf-8"?>
<booking>
  <id>1</id>
  <event_name>Christmas Eve Party!</event_name>
  <start_date>2018-12-24 18:00:00</start_date>
  <end_date>2018-12-24 22:00:00</end_date>
  <status>Booked</status>
  <venue_id>1</venue_id>
  <venue_name>Venue One</venue_name>
  <event_activity>Hotlapping</event_activity>
  <group_size>60</group_size>
  <number_of_pods>10</number_of_pods>
  <requested_vehicles>
    <vehicle>
      <vehicle_id>1</vehicle_id>
      <vehicle_name>1991 McLaren MP4/6</vehicle_name>
      <vehicle_uri>https://api.simracing.co.uk/v0.1/vehicles/1</vehicle_uri>
    </vehicle>
    ...
  </requested_vehicles>
  <requested_circuits>
    <circuit>
      <circuit_id>1</circuit_id>
      <circuit_name>A1 Ring - GP</circuit_name>
      <circuit_uri>https://api.simracing.co.uk/v0.1/circuits/1</circuit_uri>
    </circuit>
    ...
  </requested_circuits>
  <participants>
    <customer>
      <customer_id>1</customer_id>
      <customer_name>Jim Clark</customer_name>
      <customer_uri>https://api.simracing.co.uk/v0.1/customers/1</customer_uri>
    </customer>
    ...
  </participants>
  <staffing_notes>Peter unavailable to assist due to vacation.</staffing_notes>
  <notes>Whole venue booking for Christmas party.</notes>
  <payment_notes>20% deposit paid in advance, remainder to be paid on day.</payment_notes>
  <venue_uri>https://api.simracing.co.uk/v0.1/venues/1</venue_uri>
</booking>

This endpoint retrieves the details of the specified booking.

URL Parameters

Parameter	Description
ID	The ID of the booking to retrieve

HTTP Request

GET https://api.simracing.co.uk/v0.1/booking/<ID>

Notes

Depending on the booking, either a number_of_pods field, containing a single number, or a specific_pods field, containing a list of comma-separated pod numbers, may be present.

Championships

Access to the championship endpoints requires the championships feature to be enabled for your VMS account. If this feature is not enabled, you will receive a 403 error when attempting to access these endpoints.

List Championships

curl "https://api.simracing.co.uk/v0.1/championships" \
  -H "Authorization: SRL <your-API-key>"

<?xml version="1.0" encoding="utf-8"?>
<championships>
  <championship>
    <id>1</id>
    <name>1966 World Championship</name>
    <venues>
      <venue>
        <id>2</id>
        <venue_uri>https://api.simracing.co.uk/v0.1/venues/2</venue_uri>
      </venue>
    </venues>
    <most_recent_event>2018-03-05 22:03:50</most_recent_event>
    <championship_uri>https://api.simracing.co.uk/v0.1/championships/1</championship_uri>
  </championship>
  ...
</championships>

This endpoint lists all available championships.

HTTP Request

GET https://api.simracing.co.uk/v0.1/championships

Get a Specific Championship

curl "https://api.simracing.co.uk/v0.1/championships/1" \
  -H "Authorization: SRL <your-API-key>"

<?xml version="1.0" encoding="utf-8"?>
<championships>
  <championship>
    <id>1</id>
    <name>1966 World Championship</name>
    <venues>
      <venue>
        <id>2</id>
        <venue_uri>https://api.simracing.co.uk/v0.1/venues/2</venue_uri>
      </venue>
    </venues>
    <max_events_counted>5</max_events_counted>
    <summary>
      <result>
        <position>1</position>
        <customer_id>4</customer_id>
        <customer_name>Jack Brabham</customer_name>
        <class_id>1</class_id>
        <class_name>World Champions</class_name>
        <score>45</score>
        <max_counted_score>42</max_counted_score>
        <events>
          <event>
            <number>1</number>
            <id>844</id>
            <type>group_event</type>
            <position>20</position>
            <score>0</score>
            <group_event_uri>https://api.simracing.co.uk/v0.1/group_events/844</group_event_uri>
          </event>
          ...
        </events>
      </result>
      ...
    </summary>
    <events>
      <event>
        <id>844</id>
        <name>Monaco Grand Prix</name>
        <start_date>2017-01-09 18:02:13</start_date>
        <end_date>2017-01-09 21:58:45</end_date>
        <venues>
          <venue>
            <id>2</id>
            <venue_uri>https://api.simracing.co.uk/v0.1/venues/2</venue_uri>
          </venue>
        </venues>
        <type>group_event</type>
        <summary>
          <result>
            <position>1</position>
            <customer_id>4</customer_id>
            <customer_name>Jack Brabham</customer_name>
            <qualification_points>9</qualification_points>
            <race_points>70</race_points>
            <fastest_practice_lap_id>1693339</fastest_practice_lap_id>
            <fastest_practice_lap_time_ms>124533</fastest_practice_lap_time_ms>
            <fastest_practice_lap_time_str>2:04.533</fastest_practice_lap_time_str>
            <fastest_practice_lap_transmission>Manual</fastest_practice_lap_transmission>
            <fastest_qualification_lap_id>1693406</fastest_qualification_lap_id>
            <fastest_qualification_lap_time_ms>125928</fastest_qualification_lap_time_ms>
            <fastest_qualification_lap_time_str>2:05.928</fastest_qualification_lap_time_str>
            <fastest_qualification_lap_transmission>Manual</fastest_qualification_lap_transmission>
            <fastest_race_lap_id>1693763</fastest_race_lap_id>
            <fastest_race_lap_time_ms>123949</fastest_race_lap_time_ms>
            <fastest_race_lap_time_str>2:03.949</fastest_race_lap_time_str>
            <fastest_race_lap_transmission>Manual</fastest_race_lap_transmission>
            <class_id>1</class_id>
            <class_name>World Champion</class_name>
            <race_wins>7</race_wins>
            <total_points>79</total_points>
            <practice_telemetry_uri>https://telemetry.racecentres.com/v0.7/getdata.php?did=1&amp;lid=1693339&amp;hash=abc</practice_telemetry_uri>
            <qualification_telemetry_uri>https://telemetry.racecentres.com/v0.7/getdata.php?did=1&amp;lid=1693406&amp;hash=abc</qualification_telemetry_uri>
            <race_telemetry_uri>https://telemetry.racecentres.com/v0.7/getdata.php?did=1&amp;lid=1693763&amp;hash=abc</race_telemetry_uri>
            <customer_uri>https://api.simracing.co.uk/v0.1/customers/4</customer_uri>
            <practice_lap_uri>https://api.simracing.co.uk/v0.1/laps/1693339</practice_lap_uri>
            <qualification_lap_uri>https://api.simracing.co.uk/v0.1/laps/1693406</qualification_lap_uri>
            <race_lap_uri>https://api.simracing.co.uk/v0.1/laps/1693763</race_lap_uri>
            <class_uri>https://api.simracing.co.uk/v0.1/classes/1</class_uri>
          </result>
          ...
        </summary>
        <group_event_uri>https://api.simracing.co.uk/v0.1/group_events/844</group_event_uri>
      </event>
      ...
    </events>
    <championship_uri>https://api.simracing.co.uk/v0.1/championships/1</championship_uri>
  </championship>
</championships>

This endpoint retrieves the details of the specified championship, including the overall championship summary and a summary of each event in the championship.

URL Parameters

Parameter	Description
ID	The ID of the championship to retrieve

HTTP Request

GET https://api.simracing.co.uk/v0.1/championship/<ID>

Notes

The telemetry URI endpoint produces a Javascript graph output of the currently selected lap compared to the fastest lap in this circuit, vehicle and transmission combination (if available). It is recommended to display this URI in an iframe. Not all laps will have telemetry available, the <telemetry_uri> entry will only be present in the output if telemetry is available. Telemetry URIs will not be provided if your licence key does not include telemetry support.
Telemetry URIs contain XML-encoded characters which will need to be decoded before the URI is valid, specifically replacing & with &. Many XML parsing libraries have options to allow this decoding to occur automatically.
The XML returned for a championship can be very big -- it is recommended to use gzip compression to reduce data transit times.

Circuits

Get a List of Circuits

curl "https://api.simracing.co.uk/v0.1/circuits" \
  -H "Authorization: SRL <your-API-key>"

<?xml version="1.0" encoding="utf-8"?>
<circuits>
  <circuit>
    <id>1</id>
    <name>A1 Ring - GP</name>
    <length>4.326</length>
    <circuit_uri>https://api.simracing.co.uk/v0.1/circuits/1</circuit_uri>
    <vehicle_records_uri>https://api.simracing.co.uk/v0.1/circuits/1/vehicle_records</vehicle_records_uri>
    <customer_records_uri>https://api.simracing.co.uk/v0.1/circuits/1/customer_records</customer_records_uri>
  </circuit>
  <circuit>
    <id>2</id>
    <name>Adelaide - GP 1994</name>
    <length>3.78</length>
    <circuit_uri>https://api.simracing.co.uk/v0.1/circuits/2</circuit_uri>
    <vehicle_records_uri>https://api.simracing.co.uk/v0.1/circuits/2/vehicle_records</vehicle_records_uri>
    <customer_records_uri>https://api.simracing.co.uk/v0.1/circuits/2/customer_records</customer_records_uri>
  </circuit>
  ...
</circuits>

This endpoint lists all available circuits, in alphabetical order.

HTTP Request

GET https://api.simracing.co.uk/v0.1/circuits

Get a Specific Circuit

curl "https://api.simracing.co.uk/v0.1/circuits/1" \
  -H "Authorization: SRL <your-API-key>"

<?xml version="1.0" encoding="utf-8"?>
<circuit>
  <id>1</id>
  <name>A1 Ring - GP</name>
  <length>4.326</length>
  <circuit_uri>https://api.simracing.co.uk/v0.1/circuits/1</circuit_uri>
  <vehicle_records_uri>https://api.simracing.co.uk/v0.1/circuits/1/vehicle_records</vehicle_records_uri>
  <customer_records_uri>https://api.simracing.co.uk/v0.1/circuits/1/customer_records</customer_records_uri>
</circuit>

This endpoint retrieves a specific circuit.

HTTP Request

GET https://api.simracing.co.uk/v0.1/circuit/<ID>

URL Parameters

Parameter	Description
ID	The ID of the circuit to retrieve

Get Vehicle Lap Records for a Circuit

curl "https://api.simracing.co.uk/v0.1/circuits/1/vehicle_records" \
  -H "Authorization: SRL <your-API-key>"

<?xml version="1.0" encoding="utf-8"?>
<circuit>
  <id>1</id>
  <name>A1 Ring - GP</name>
  <length>4.326</length>
  <vehicle_results>72</vehicle_results>
  <results>
    <result>
      <date>2015-05-17 16:27:50</date>
      <customer_id>2</customer_id>
      <customer_name>Graham Hill</customer_name>
      <lap_id>1229486</lap_id>
      <lap_time_ms>69763</lap_time_ms>
      <lap_time_str>1:09.763</lap_time_str>
      <transmission>Manual</transmission>
      <vehicle_id>1</vehicle_id>
      <vehicle_name>1991 McLaren MP4/6</vehicle_name>
      <vehicle_engine>3493cc</vehicle_engine>
      <class_id>1</class_id>
      <class_name>World Champion</class_name>
      <class_icon>A</class_icon>
      <venue_id>1</venue_id>
      <venue_name>Venue One</venue_name>
      <invalid>0</invalid>
      <verified>0</verified>
      <telemetry_uri>http://telemetry.racecentres.com/v0.4/getdata.php?did=1&amp;lid=1229486&amp;hash=abc</telemetry_uri>
      <customer_uri>https://api.simracing.co.uk/v0.1/customers/2</customer_uri>
      <lap_uri>https://api.simracing.co.uk/v0.1/laps/1229486</lap_uri>
      <vehicle_uri>https://api.simracing.co.uk/v0.1/vehicles/1</vehicle_uri>
      <class_uri>https://api.simracing.co.uk/v0.1/classes/1</class_uri>
      <venue_uri>https://api.simracing.co.uk/v0.1/venues/1</venue_uri>
    </result>
    ...
  </results>
</circuit>

This endpoint retrieves the fastest lap recorded by each vehicle for the specified circuit.

URL Parameters

Parameter	Description
ID	The ID of the circuit to retrieve

HTTP Request

GET https://api.simracing.co.uk/v0.1/circuits/<ID>/vehicle_records

Query Parameters

Parameter	Default	Description
index	`0`	The starting index for the list of results.
count	`1000`	The number of results returned.
invalid	`0`	Whether to include invalidated laps.

Notes

The telemetry URI endpoint produces a Javascript graph output of the currently selected lap compared to the fastest lap in this circuit, vehicle and transmission combination (if available). It is recommended to display this URI in an iframe. Not all laps will have telemetry available, the <telemetry_uri> entry will only be present in the output if telemetry is available. Telemetry URIs will not be provided if your licence key does not include telemetry support.
Telemetry URIs contain XML-encoded characters which will need to be decoded before the URI is valid, specifically replacing & with &. Many XML parsing libraries have options to allow this decoding to occur automatically.

Get Customer Lap Records for a Circuit

curl "https://api.simracing.co.uk/v0.1/circuits/1/customer_records" \
  -H "Authorization: SRL <your-API-key>"

<?xml version="1.0" encoding="utf-8"?>
<circuit>
  <id>1</id>
  <name>A1 Ring - GP</name>
  <length>4.326</length>
  <customer_results>11447</customer_results>
  <results>
    <result>
      <date>2015-05-17 16:27:50</date>
      <customer_id>2</customer_id>
      <customer_name>Graham Hill</customer_name>
      <lap_id>1229486</lap_id>
      <lap_time_ms>69763</lap_time_ms>
      <lap_time_str>1:09.763</lap_time_str>
      <transmission>Manual</transmission>
      <vehicle_id>1</vehicle_id>
      <vehicle_name>1991 McLaren MP4/6</vehicle_name>
      <vehicle_engine>3493cc</vehicle_engine>
      <class_id>1</class_id>
      <class_name>World Champion</class_name>
      <class_icon>A</class_icon>
      <venue_id>1</venue_id>
      <venue_name>Venue One</venue_name>
      <invalid>0</invalid>
      <verified>0</verified>
      <telemetry_uri>http://telemetry.racecentres.com/v0.4/getdata.php?did=1&amp;lid=1229486&amp;hash=abc</telemetry_uri>
      <customer_uri>https://api.simracing.co.uk/v0.1/customers/2</customer_uri>
      <lap_uri>https://api.simracing.co.uk/v0.1/laps/1229486</lap_uri>
      <vehicle_uri>https://api.simracing.co.uk/v0.1/vehicles/1</vehicle_uri>
      <class_uri>https://api.simracing.co.uk/v0.1/classes/1</class_uri>
      <venue_uri>https://api.simracing.co.uk/v0.1/venues/1</venue_uri>
    </result>
    ...
  </results>
</circuit>

This endpoint retrieves the fastest lap recorded by each customer for the specified circuit.

URL Parameters

Parameter	Description
ID	The ID of the circuit to retrieve

HTTP Request

GET