API

danger

As HH Timing V2 is still being heavily developed the API contracts may change between releases and require updates in clients.

The HH Timing V2 desktop application hosts an API that can be accessed locally via http://localhost:5000 (when the software is running). Currently the API is readonly.

The Swagger docs can be accessed by navigating to http://localhost:5000/swagger. The current endpoints allow for the following items to be accessed:

• getting session data
• getting all cars in a session
• getting a single car in a session
• getting all stints for a car
• getting all laps for a car

tip

Use active as the sessionId in requests to access the currently active session.

Do not hesitate to send us a request if you would like access any other data via the API.

There is no authentication required for the API at the moment as it is only running locally.

The concept of the API is similar to the HH Data Management API, so it will provide continuity for those used to working with HH Data Management.

Selecting parameters returned in queries

When making a GET request to an endpoint you can pass a URL parameter called parametersToInclude that lets you specify which parameters will be included in the response. This can be useful to access related data (e.g. get the stint for a lap or the sectors) and also to limit the amount of data returned in a response to make the API calls faster. The parametersToInclude should be a comma separated list. The * symbol is used to represent all parameters. When building a response the API has the following logic:

• if you do not provide a value for parametersToInclude or if you pass in * the API will return:

  • all parameters of the current entity
  • the following parts of the response will be present but empty
    • children (e.g. the Laps requests will return an empty OnTrackSectors object)
    • parents (e.g. the Laps requests will return an empty Stint object)

  Here is a sample from the RunSheet endpoint:

{
    "$type": "Lap",
    "Id": "30b88ef1-6283-4dd0-a33d-157f1a0ba439",
    "Parameters": {
        "LapNumber": 1,
        "StintLapNumber": 1,
        "Time": 78.50200000762939,
        "EndTime": {
            "SessionTime": 94.535,
            "TimeOfDay": 1790897494.535,
            "ComputerTime": "12.18:59:15.1314050"
        },
        "TrackStatus": null,
        "BestType": 0,
        "InLapTime": null,
        "IsInLap": false,
        "OutLapTime": 78.50200000762939,
        "IsOutLap": true,
        "EnabledForCalculations": false,
        "IsTrackLimits": false,
        "IsDeleted": false,
        "PowerMode": 0,
        "IsJokerLap": false,
        "Position": 13,
        "PositionInClass": 2,
        "NumberOfCarsPassed": 0,
        "NumberOfCarsPassedBy": 0,
        "LineCrossingOrder": 3,
        "EnergyConsumed": null,
        "EnergyRemaining": 97.74649999141693,
        "AirTemperatureC": 25.799999237060547,
        "TrackTemperatureC": 36.29999923706055,
        "AirPressureKpa": 98.57999877929687,
        "Humidity": 72.0,
        "WindSpeedKmh": 0.0,
        "WindDirectionDeg": 360.0,
        "LapNumberDecimalSectorNumber": 1,
        "IsStrikeThrough": false,
        "IsProjected": false
    },
    "OnTrackSectors": [],
    "SpeedTraps": [],
    "Stint": {}
}

The empty and minimal objects are returned to provide insight to users to see what each entity has access to.

• if parameters are specified then only these parameters are provided. For example, if the parametersToInclude was set to Time,IsTrackLimits then the response would look like this:

{
    "$type": "Lap",
    "Id": "30b88ef1-6283-4dd0-a33d-157f1a0ba439",
    "Parameters": {
        "Time": 78.50200000762939,
        "IsTrackLimits": false
    }
}

• Referenced items can be specified using the dot notation. For example, if the parametersToInclude was set to Time,Stint.BestLap then the response would look like this:

{
    "$type": "Lap",
    "Id": "cff3cd01-9f9a-4511-9c89-d0ca58e03069",
    "Parameters": {
        "Time": 78.50200000762939
    },
    "Stint": {
        "$type": "Stint",
        "Id": "30b38819-f08b-4932-b7c4-f9f72d42c934",
        "Parameters": {
            "BestXAverage": 72.6288
        }
    }
}

the dot notation also supports the wildcard character, so sending Stint.* when reading laps would return all parameters from the stint that the lap belongs to.

Custom lap properties

Laps have a Custom object, next to Parameters, with the session's custom lap properties (for example the values written by the Telemetry Import). Every lap lists every custom property of the session; the value is null when the lap has no value for it.

{
    "$type": "Lap",
    "Id": "30b88ef1-6283-4dd0-a33d-157f1a0ba439",
    "Parameters": {
        "Time": 78.50200000762939
    },
    "Custom": {
        "FuelLevel": 41.5,
        "TyrePressFL": null
    }
}

Custom is returned with *, and Custom on its own returns all custom properties. Single properties are selected with the dot notation, e.g. Time,Custom.FuelLevel.