Kart Laps

A simple API that aims to provide machine-readable access to go kart lap time data from raceways that use Club Speed timing services

Club Speed is a popular timing system used by many arrive-and-drive karting raceways. After registering at your local raceway, your race timing data is stored and published with Club Speed's web application. But this data is only available for human consumption, often displayed on the raceways website inside of iFrame elements.

Using It

It's simple: you GET a particular URL. In response, you'll get back a JSON object containing the information you're requesting; searching for racers, data about individual racers, data about individual heats, the location's leaderboard, etc.

How To Start

Start by figuring out the unique Club Speed location name of the raceway you want to request information about. If your raceway offers a "Lap Times" link on their website, chances are you can find it in the URLs that the raceway website loads when you click on that link. Open up your browser's inspector and filter the loaded page's network activity to show only "clubspeed" requests and look for any request made to an .aspx file. The location name is usually found as a subdomain in that request's URL. You'll find something like "mb2sylmar.clubspeedtiming.com/sp_center/..." where "mb2sylmar" is the location name.

Finding a location name

A location name is required for all requests to the API. But even if you have one, some raceways insist they keep their lap time information entirely private. This seems to be an option in the Club Speed software that each location can control individually. For locations that are set up this way, Kart Laps won't work. If you suspect the location you're working with might be one of those, contact me before you give up, and let me make sure.

Searching a Location for Racers

Once you have your location name, a good place to start is by searching that location for racers. Request a URL like https://kartlaps.info/v2/mb2sylmar/search/smith with "mb2sylmar" replaced with your location name, and "smith" replaced with your search string. Club Speed searches the location's racers by their real first name, last name, racer name, or the email address they used to sign up at the raceway...

Some locations just don't support finding racers by their email address. This seems to be a per-location settting.
Request:
https://kartlaps.info/v2/mb2sylmar/search/smith
Response Example:
{
    "search": {
        "url": "http:\/\/kartlaps.info\/v2\/mb2sylmar\/search\/smith",
        "location": {
            "id": "mb2sylmar"
        },
        "searchString": "smith",
        "results": [
            {
                "url": "http:\/\/kartlaps.info\/v2\/mb2sylmar\/racer\/619",
                "id": 619,
                "racerName": "Chipper",
                "realFirstName": "Chipper",
                "realLastName": "Smith",
                "city": "newhall"
            },
            {
                "url": "http:\/\/kartlaps.info\/v2\/mb2sylmar\/racer\/712",
                "id": 712,
                "racerName": "Jules",
                "realFirstName": "Julie",
                "realLastName": "Smith",
                "city": "Chatsworth"
            },
            ...
Club Speed's search function can return up to 50 results, with no option of pagination.

Location Leaderboard

To check out a location's top 100 points leaders, go to a URL like https://kartlaps.info/v2/mb2sylmar/pointsleaderboard where "mb2sylmar" is replaced with the location name of the location for which you'd like to see the leaderboard...

Request:
https://kartlaps.info/v2/mb2sylmar/pointsleaderboard
Response Example:
{
    "pointsleaderboard": {
        "url": "http:\/\/kartlaps.info\/v2\/mb2sylmar\/pointsleaderboard",
        "location": {
            "id": "mb2sylmar"
        },
        "leaders": {
            "1": {
                "url": "http:\/\/kartlaps.info\/v2\/mb2sylmar\/racer\/9484",
                "id": 9484,
                "racerName": "McShredder Varner",
                "points": 9085,
                "city": "Shredderville"
            },
            "2": {
                "url": "http:\/\/kartlaps.info\/v2\/mb2sylmar\/racer\/48630",
                "id": 48630,
                "racerName": "K. Clouston",
                "points": 7734,
                "city": "hollywood"
            },
            ...
            

Individual Racer's Basic Info and Race History

You can get the basic information and race history of an individual racer at a location by hitting a URL like https://kartlaps.info/v2/mb2sylmar/racer/75116 with "mb2sylmar" replaced with the location name you're querying, and the trailing set of numbers of the url replaced with the ID of the racer you want to know more about...

Request:
https://kartlaps.info/v2/mb2sylmar/racer/75116
Response Example:
{
    "racer": {
        "url": "http:\/\/kartlaps.info\/v2\/mb2sylmar\/racer\/75116",
        "id": 75116,
        "location": {
            "id": "mb2sylmar"
        },
        "racerName": "ANIMAL",
        "points": 5495,
        "heats": [
            {
                "heat": {
                    "url": "http:\/\/kartlaps.info\/v2\/mb2sylmar\/heat\/237669",
                    "id": 237669,
                    "location": {
                        "id": "mb2sylmar"
                    },
                    "name": "~MB2 14 Lap Race",
                    "localDateTime": "1\/5\/2017 6:40 PM"
                },
                "finalPosition": 1,
                "pointsAtStart": 5482,
                "pointsImpact": 13,
                "kartNumber": 10,
                "bestLapTime": 21.632
            },
            {
                "heat": {
                    "url": "http:\/\/kartlaps.info\/v2\/mb2sylmar\/heat\/233248",
                    "id": 233248,
                    "location": {
                        "id": "mb2sylmar"
                    },
                    "name": "~MB2 14 Lap Race",
                    "localDateTime": "10\/31\/2016 8:00 PM"
                },
                "finalPosition": 1,
                "pointsAtStart": 5420,
                "pointsImpact": 62,
                "kartNumber": 5,
                "bestLapTime": 20.984
            },
            ...
            

Get Heat Data

You can get a detailed account of each race at a location that includes the participants, the final positions of the participants, and each of their lap's times by hitting a URL like https://kartlaps.info/v2/mb2sylmar/heat/237669 with "mb2sylmar" replaced with the location name you're querying, and the trailing set of numbers replaced by the heat id you want to know more about...

Request:
https://kartlaps.info/v2/mb2sylmar/heat/237669
Response Example:
{
    "heat": {
        "url": "http:\/\/kartlaps.info\/v2\/mb2sylmar\/heat\/237669",
        "id": "237669",
        "location": {
            "id": "mb2sylmar"
        },
        "name": "~MB2 14 Lap Race",
        "winBy": "Best Lap",
        "localDateTime": "1\/5\/2017 6:40 PM",
        "participants": [
            {
                "url": "http:\/\/kartlaps.info\/v2\/mb2sylmar\/racer\/75116",
                "id": 75116,
                "racerName": "ANIMAL"
            },
            {
                "url": "http:\/\/kartlaps.info\/v2\/mb2sylmar\/racer\/3900",
                "id": 3900,
                "racerName": "Isra"
            },
            ...
        ],
        "podium": [
            {
                "finalPosition": 1,
                "racer": {
                    "url": "http:\/\/kartlaps.info\/v2\/mb2sylmar\/racer\/75116",
                    "id": 75116,
                    "racerName": "ANIMAL"
                }
            },
            {
                "finalPosition": 2,
                "racer": {
                    "url": "http:\/\/kartlaps.info\/v2\/mb2sylmar\/racer\/3900",
                    "id": 3900,
                    "racerName": "Isra"
                }
            },
            {
                "finalPosition": 3,
                "racer": {
                    "url": "http:\/\/kartlaps.info\/v2\/mb2sylmar\/racer\/1279496",
                    "id": 1279496,
                    "racerName": "evilgt500"
                }
            }
        ],
        "laps": [
            {
                "racerId": 75116,
                "racerLaps": [
                    {
                        "lapNumber": 1,
                        "seconds": 30.196,
                        "position": 7
                    },
                    {
                        "lapNumber": 2,
                        "seconds": 23.458,
                        "position": 2
                    },
                    ...
                ]
            },
            {
                "racerId": 3900,
                "racerLaps": [
                    {
                        "lapNumber": 1,
                        "seconds": 22.878,
                        "position": 1
                    },
                    {
                        "lapNumber": 2,
                        "seconds": 23.259,
                        "position": 1
                    },
                    ...
                ]
            },
            {
                "racerId": 1279496,
                "racerLaps": [
                    {
                        "lapNumber": 1,
                        "seconds": 27.753,
                        "position": 2
                    },
                    {
                        "lapNumber": 2,
                        "seconds": 25.418,
                        "position": 5
                    },
                    ...
                ]
            },
            ...
        ]
        ...

Top Times

In addition to a points leaderboard, there is also a laptime leaderboard, that displays best times over the last 1, 7, or 30 day(s). Try a URL like https://kartlaps.info/v2/mb2sylmar/laptimeleaderboard/1 with "mb2sylmar" replace with the location you're querying, and the final number replaced with the amount of days history to show (acceptable values are 1, 7, and 30).

Request:
https://kartlaps.info/v2/mb2sylmar/laptimeleaderboard/1
Response Example:
{
    "laptimeleaderboard": {
        "url": "http:\/\/kartlaps.info\/v2\/mb2sylmar\/laptimeleaderboard\/1",
        "location": {
            "id": "mb2sylmar"
        },
        "days": "1",
        "leaders": {
            "1": {
                "racerName": "Andrew",
                "lapTime": "00:19:065",
                "localDateTime": "8\/26\/2017 2:06 PM"
            },
            "2": {
                "racerName": "YRUSLOW",
                "lapTime": "00:19:468",
                "localDateTime": "8\/26\/2017 11:12 AM"
            },
            "3": {
                "racerName": "Dan Brown",
                "lapTime": "00:19:621",
                "localDateTime": "8\/26\/2017 2:06 PM"
            },
            ...
You may notice this output is a list of racer objects, but that those objects don't contain a racer id. This is because Club Speed's "Top Times" pages strangely don't include the racer's id in this list. Another quirk of their system that I haven't devised a work-around for.

API Keys

There is currently no limit of requests that you can make, and no key required to include in your requests.

But please assume that for each request you make to this API, that there is in-turn a request made to the Club Speed servers for the location. There is some caching done in to improve speeds and to not bombard Club Speed servers by making too many requests of the same unchanged data, but still. Use responsibly please.

"x Doesn't Work!"

Things tends to break sometimes, or not work as expected. Send me a tweet or an e-mail with any questions that come up using this. @varwwwhtml or tom _AT_ itsmetomsmith _DOT_ com.