HomeUser ManualThe data interface

The data interface

This feature is part of the SmartRace Champions Club. This is a big package with cool extensions, which you can conveniently add in the form of a monthly or annual subscription in the app and of course cancel at any time. Learn more.

What is the data interface?

The data interface offers you the possibility to connect external services or scripts to SmartRace. For this purpose, SmartRace sends certain data to a configurable endpoint on request and you can process this data as you wish. The data is sent as a POST request in JSON format.

Activation and configuration

The data interface is not activated by default. To activate it, go to Settings in the main menu of SmartRace and open the Data Interface tab. Use the button at the top to enable the interface, but you must also enable the events that you want the data interface to consider. Which data are contained in the individual events, you will learn below.

Configuration of the data interface

The different events

You can select on which events the data interface should send data. Each event type triggers different actions in SmartRace. Which actions these are, you can see in the following:

  • Lap: A car finishes a lap. The first crossing of start/finish does not trigger this event.
  • Event: A new event (qualifying/race) is started or finished or the event status changes (e.g. suspended, jump start, etc.).
  • Weather: Weather changes and change announcements (“it will rain soon”, etc.)
  • VSC: Activating and deactivating the virtual safety car.
  • Penalty: Getting and serving penalties
  • Damage: Suffer and repair damage

Sent data

The structure of the sent data is identical for each event and is built like this:

  "time": 1684769957969, // Time of the event as Unix timestamp
  "event_type": "ui.lap_update", // Event name
  "event_data": {
      // The data of the event, see below


    "controller_id": "1",
    "lap": 1,
    "laptime": "0:13.861",
    "laptime_raw": 13861,
    "sector_1": "0:06.305",
    "sector_1_pb": true,
    "sector_2": "0:03.224",
    "sector_2_pb": true,
    "sector_3": "0:04.332",
    "sector_3_pb": true,
    "lap_pb": true,
    "driver_data": {
        "id": 2,
        "name": "Marc",
        "name_tts": "",
        "active": "yes",
        "start_no_text_style": "normal",
        "team": "-",
        "name_short": null,
        "image": "",
        "start_no": "",
        "start_no_color_border": "rgb(68, 68, 68)",
        "start_no_color_background": "rgb(68, 68, 68)",
        "start_no_color_text": "rgb(68, 68, 68)"
    "car_data": {
        "color": "rgb(176, 243, 0)",
        "brakes": null,
        "active": "yes",
        "tags": "[]",
        "decoder_type": "Carrera (default)",
        "image": "cdvfile:\/\/localhost\/persistent\/1684000048302.jpg",
        "laps": 5,
        "fuel": null,
        "speed": null,
        "tyres": "Ortmann",
        "digital_analog": "digital",
        "name": "Porsche 911 RSR Grello (911)",
        "manufacturer": "Carrera",
        "id": 40,
        "interval_counter": 0,
        "scale": "1:24",
        "magnets": "yes",
        "logo": "porsche.png",
        "changed_on": null,
        "interval": 0,
        "sound": "-",
        "comment": ""
    "controller_data": {
        "color_bg": "rgb(176, 243, 0)",
        "color_text": "#000"


When starting a lap race over 50 laps:

    "type": "race",
    "laps": "50"

When starting a time race over 10 minutes (600 seconds):

    "type": "race",
    "duration": "600"


The data contains all participants, here exemplarily with three participants:

    "type": "race",
    "result": {
        "1": {
            "driver_id": 2,
            "car_id": 39,
            "controller_id": 1,
            "laps": 33,
            "best_laptime": 4915,
            "pitstops": 0,
            "gap": "",
            "disqualified": false,
            "retired": false
        "2": {
            "driver_id": 2,
            "car_id": 3,
            "controller_id": 3,
            "laps": 29,
            "best_laptime": 4914,
            "pitstops": 1,
            "gap": "+4 Lap(s)",
            "disqualified": false,
            "retired": false
        "3": {
            "driver_id": 14,
            "car_id": 33,
            "controller_id": 4,
            "laps": 27,
            "best_laptime": 4925,
            "pitstops": 0,
            "gap": "+6 Lap(s)",
            "disqualified": false,
            "retired": false


    "old": "running",
    "new": "ended"

Valid status names: prepare_for_start, starting, jumpstart, running, suspended, restarting, ended.


Contains either dry or wet.


Contains either about_to_rain or about_to_dry_up.


No further data.


No further data.


This event contains the controller_id and the penalty received in seconds. If the time is 0, the penalty has been served.

    "controller_id": "2",
    "penalty": 10
    // Will be enriched with driver_data, car_data and controller_data, see ui.lap_update


This event contains the controller_id and the type of damage. The type is one of the following: engine, battery, suspension or gearbox.

If the damage attribute has the value none, the damage has been repaired.

    "controller_id": "2",
    "damage": "engine"
    // Will be enriched with driver_data, car_data and controller_data, see ui.lap_update

Processing the data

The receiving script can be of any type. Here as an example a PHP script:


header("Access-Control-Allow-Origin: *");
header("Access-Control-Allow-Headers: *");


    $json_data = json_decode(file_get_contents('php://input'));



Download now and experience real racing.

© 2022 SmartRace – a Trademarc - Web, Apps, Print & Mehr project

All videos, images and graphics used are the property of SmartRace unless otherwise stated. Further use for private or commercial purposes is not permitted without permission. Pictures of the ADAC TotalEnergies 24h Nürburgring courtesy of ADAC Nordrhein e.V.

SmartRace is a software for Mac, tablets and smartphones and is used for timing Carrera Digital tracks in 1:32 and 1:24 scale and via the Analogue mode also for analogue tracks (e.g. Carrera Evolution, Carrera Exclusiv, Carrera Go!!!, Ninco, Scalextric or others). SmartRace either connects to the Carrera AppConnect adapter via Bluetooth or takes the measurement in analogue mode via the camera of a smartphone connected via SmartRace Connect

Carrera®, Carrera Digital® and Carrera AppConnect® are registered trademarks of Carrera Toys GmbH. SmartRace is not an official Carrera product and is in no way associated with or dependent on Carrera Toys GmbH.