Gearbox Hub API

v1Stable

Programmatic access to the complete Formula 1 archive. Retrieve historical and current season data, driver and constructor statistics, race results, and more through a clean RESTful interface.

Open Dashboard→

Base URL

https://api.gearboxhub.com/v1

Format

JSON (UTF-8)

Protocol

HTTPS only

Authentication

All API requests require a valid API key passed via the Authorization header using the Bearer scheme. You can generate API keys from your dashboard.

http

GET https://api.gearboxhub.com/v1/seasons HTTP/1.1
Host: api.gearboxhub.com
Authorization: Bearer gxb_sk_live_xxxxxxxxxxxxxxxx
Content-Type: application/json

⚠Keep your API keys secret. Do not expose them in client-side code, public repositories, or browser requests. Use server-side proxies for frontend applications.

Rate Limits

The API enforces rate limits on a per-key basis. Limits are communicated via response headers.

Plan	Requests / min	Burst
Free	60	10
Pro	600	100
Enterprise	Unlimited	Unlimited

http headers

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 54
X-RateLimit-Reset: 1710600000

Seasons

Retrieve Formula 1 season data including championship standings and race calendars.

GET/v1/seasons

Returns a paginated list of all available seasons, sorted by year descending.

Parameter	Type	Required	Description
year	integer	Optional	Filter by specific season year
limit	integer	Optional	Max results per page (default: 50, max: 100)
cursor	string	Optional	Pagination cursor from previous response

json

{
  "data": [
    {
      "season": "2024",
      "raceCount": 24,
      "driverChampion": "Max Verstappen",
      "constructorChampion": "McLaren"
    }
  ],
  "pagination": {
    "hasMore": true,
    "nextCursor": "eyJzIjoiMjAyMyJ9"
  }
}

GET/v1/seasons/{year}

Returns detailed information for a specific season including full standings and race calendar.

Parameter	Type	Required	Description
year	integer	Required	The season year (e.g. 2024)

json

{
  "season": "2024",
  "raceCount": 24,
  "driverChampion": {
    "driver": "Max Verstappen",
    "team": "Red Bull Racing",
    "points": 437,
    "wins": 9,
    "podiums": 14
  },
  "constructorChampion": {
    "team": "McLaren",
    "points": 666,
    "wins": 6,
    "podiums": 18
  },
  "standings": [ ... ],
  "races": [ ... ]
}

Drivers

Access career statistics, season breakdowns, and biographical data for every driver in the archive.

GET/v1/drivers

Returns a list of all drivers with aggregated career statistics.

Parameter	Type	Required	Description
team	string	Optional	Filter by team slug (e.g. "red-bull-racing")
season	integer	Optional	Filter to drivers active in a specific season
sort	string	Optional	Sort field: "points", "wins", "starts" (default: "points")
limit	integer	Optional	Max results per page (default: 50)

json

{
  "data": [
    {
      "driver": "Lewis Hamilton",
      "slug": "lewis-hamilton",
      "teams": ["Mercedes", "McLaren", "Ferrari"],
      "starts": 353,
      "wins": 104,
      "podiums": 201,
      "poles": 104,
      "totalPoints": 4829.5
    }
  ],
  "pagination": { "hasMore": false }
}

GET/v1/drivers/{slug}

Returns full career statistics and season-by-season breakdown for a specific driver.

Parameter	Type	Required	Description
slug	string	Required	URL-safe driver identifier (e.g. "lewis-hamilton")

json

{
  "driver": "Lewis Hamilton",
  "slug": "lewis-hamilton",
  "teams": ["Mercedes", "McLaren", "Ferrari"],
  "starts": 353,
  "wins": 104,
  "podiums": 201,
  "poles": 104,
  "dnfs": 31,
  "bestFinish": 1,
  "averageFinish": 4.2,
  "totalPoints": 4829.5,
  "seasons": [
    {
      "season": "2024",
      "starts": 24,
      "wins": 2,
      "podiums": 3,
      "points": 211
    }
  ]
}

Teams

Constructor data including historical entries, championship results, and driver rosters.

GET/v1/teams

Returns a list of all constructors with aggregated statistics.

Parameter	Type	Required	Description
season	integer	Optional	Filter to teams active in a specific season
sort	string	Optional	Sort field: "points", "wins", "entries" (default: "points")

GET/v1/teams/{slug}

Returns detailed constructor profile with season-by-season breakdown and driver history.

Parameter	Type	Required	Description
slug	string	Required	URL-safe team identifier (e.g. "red-bull-racing")

json

{
  "team": "Red Bull Racing",
  "slug": "red-bull-racing",
  "entries": 418,
  "wins": 120,
  "podiums": 250,
  "poles": 103,
  "points": 7521,
  "seasons": ["2005", "2006", ... , "2024"],
  "drivers": ["Max Verstappen", "Daniel Ricciardo", ...],
  "seasonBreakdown": [
    {
      "season": "2024",
      "entries": 24,
      "wins": 9,
      "podiums": 14,
      "points": 581
    }
  ]
}

Races

Full race results including qualifying, sprint sessions, and practice data when available.

GET/v1/seasons/{year}/races

Returns all races for a given season including results summaries.

Parameter	Type	Required	Description
year	integer	Required	The season year

GET/v1/seasons/{year}/races/{round}

Returns the full result set for a specific race including practice, qualifying, sprint, and race classification.

Parameter	Type	Required	Description
year	integer	Required	The season year
round	integer	Required	Race round number within the season

json

{
  "name": "Bahrain Grand Prix",
  "season": "2024",
  "location": "Sakhir",
  "round": 1,
  "results": [
    {
      "position": "1",
      "driver": "Max Verstappen",
      "team": "Red Bull Racing",
      "time": "1:31:44.742",
      "status": "Finished"
    },
    {
      "position": "2",
      "driver": "Sergio Perez",
      "team": "Red Bull Racing",
      "time": "+22.457",
      "status": "Finished"
    }
  ],
  "qualifying_results": [ ... ],
  "sprint_results": null,
  "practice_results": [ ... ]
}

Errors

The API uses standard HTTP status codes. Errors return a consistent JSON structure.

Code	Status	Description
200	OK	Request succeeded.
400	Bad Request	Invalid query parameter or malformed request.
401	Unauthorized	Missing or invalid API key.
403	Forbidden	API key does not have access to the requested resource.
404	Not Found	The requested resource does not exist.
429	Too Many Requests	Rate limit exceeded. Retry after the time in X-RateLimit-Reset.
500	Internal Server Error	Something went wrong on our end. Please try again later.

json

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Season '2099' does not exist.",
    "status": 404
  }
}

Code Examples

Quick-start snippets in popular languages.

cURL

bash

curl -s \
  -H "Authorization: Bearer gxb_sk_live_xxxxxxxxxxxxxxxx" \
  "https://api.gearboxhub.com/v1/seasons/2024" | jq .

JavaScript / TypeScript

javascript

const API_KEY = process.env.GEARBOX_API_KEY;

const response = await fetch(
  "https://api.gearboxhub.com/v1/drivers/lewis-hamilton",
  {
    headers: {
      Authorization: `Bearer ${API_KEY}`,
      "Content-Type": "application/json",
    },
  }
);

const driver = await response.json();
console.log(driver.data);

Python

python

import requests
import os

API_KEY = os.environ["GEARBOX_API_KEY"]
BASE_URL = "https://api.gearboxhub.com/v1"

response = requests.get(
    f"{BASE_URL}/seasons/2024/races",
    headers={"Authorization": f"Bearer {API_KEY}"},
)
response.raise_for_status()

races = response.json()["data"]
for race in races:
    print(f"Round {race['round']}: {race['name']}")

package main

import (
	"encoding/json"
	"fmt"
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("GET",
		"https://api.gearboxhub.com/v1/teams/red-bull-racing", nil)
	req.Header.Set("Authorization",
		"Bearer "+os.Getenv("GEARBOX_API_KEY"))

	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()

	var team map[string]interface{}
	json.NewDecoder(resp.Body).Decode(&team)
	fmt.Println(team["team"], "-", team["points"], "pts")
}

Loading…

Gearbox Hub API

v1Stable

Programmatic access to the complete Formula 1 archive. Retrieve historical and current season data, driver and constructor statistics, race results, and more through a clean RESTful interface.

Open Dashboard→

Base URL

https://api.gearboxhub.com/v1

Format

JSON (UTF-8)

Protocol

HTTPS only

Authentication

All API requests require a valid API key passed via the Authorization header using the Bearer scheme. You can generate API keys from your dashboard.

http

GET https://api.gearboxhub.com/v1/seasons HTTP/1.1
Host: api.gearboxhub.com
Authorization: Bearer gxb_sk_live_xxxxxxxxxxxxxxxx
Content-Type: application/json

⚠Keep your API keys secret. Do not expose them in client-side code, public repositories, or browser requests. Use server-side proxies for frontend applications.

Rate Limits

The API enforces rate limits on a per-key basis. Limits are communicated via response headers.

Plan	Requests / min	Burst
Free	60	10
Pro	600	100
Enterprise	Unlimited	Unlimited

http headers

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 54
X-RateLimit-Reset: 1710600000

Seasons

Retrieve Formula 1 season data including championship standings and race calendars.

GET/v1/seasons

Returns a paginated list of all available seasons, sorted by year descending.

Parameter	Type	Required	Description
year	integer	Optional	Filter by specific season year
limit	integer	Optional	Max results per page (default: 50, max: 100)
cursor	string	Optional	Pagination cursor from previous response

json

{
  "data": [
    {
      "season": "2024",
      "raceCount": 24,
      "driverChampion": "Max Verstappen",
      "constructorChampion": "McLaren"
    }
  ],
  "pagination": {
    "hasMore": true,
    "nextCursor": "eyJzIjoiMjAyMyJ9"
  }
}

GET/v1/seasons/{year}

Returns detailed information for a specific season including full standings and race calendar.

Parameter	Type	Required	Description
year	integer	Required	The season year (e.g. 2024)

json

{
  "season": "2024",
  "raceCount": 24,
  "driverChampion": {
    "driver": "Max Verstappen",
    "team": "Red Bull Racing",
    "points": 437,
    "wins": 9,
    "podiums": 14
  },
  "constructorChampion": {
    "team": "McLaren",
    "points": 666,
    "wins": 6,
    "podiums": 18
  },
  "standings": [ ... ],
  "races": [ ... ]
}

Drivers

Access career statistics, season breakdowns, and biographical data for every driver in the archive.

GET/v1/drivers

Returns a list of all drivers with aggregated career statistics.

Parameter	Type	Required	Description
team	string	Optional	Filter by team slug (e.g. "red-bull-racing")
season	integer	Optional	Filter to drivers active in a specific season
sort	string	Optional	Sort field: "points", "wins", "starts" (default: "points")
limit	integer	Optional	Max results per page (default: 50)

json

{
  "data": [
    {
      "driver": "Lewis Hamilton",
      "slug": "lewis-hamilton",
      "teams": ["Mercedes", "McLaren", "Ferrari"],
      "starts": 353,
      "wins": 104,
      "podiums": 201,
      "poles": 104,
      "totalPoints": 4829.5
    }
  ],
  "pagination": { "hasMore": false }
}

GET/v1/drivers/{slug}

Returns full career statistics and season-by-season breakdown for a specific driver.

Parameter	Type	Required	Description
slug	string	Required	URL-safe driver identifier (e.g. "lewis-hamilton")

json

{
  "driver": "Lewis Hamilton",
  "slug": "lewis-hamilton",
  "teams": ["Mercedes", "McLaren", "Ferrari"],
  "starts": 353,
  "wins": 104,
  "podiums": 201,
  "poles": 104,
  "dnfs": 31,
  "bestFinish": 1,
  "averageFinish": 4.2,
  "totalPoints": 4829.5,
  "seasons": [
    {
      "season": "2024",
      "starts": 24,
      "wins": 2,
      "podiums": 3,
      "points": 211
    }
  ]
}

Teams

Constructor data including historical entries, championship results, and driver rosters.

GET/v1/teams

Returns a list of all constructors with aggregated statistics.

Parameter	Type	Required	Description
season	integer	Optional	Filter to teams active in a specific season
sort	string	Optional	Sort field: "points", "wins", "entries" (default: "points")

GET/v1/teams/{slug}

Returns detailed constructor profile with season-by-season breakdown and driver history.

Parameter	Type	Required	Description
slug	string	Required	URL-safe team identifier (e.g. "red-bull-racing")

json

{
  "team": "Red Bull Racing",
  "slug": "red-bull-racing",
  "entries": 418,
  "wins": 120,
  "podiums": 250,
  "poles": 103,
  "points": 7521,
  "seasons": ["2005", "2006", ... , "2024"],
  "drivers": ["Max Verstappen", "Daniel Ricciardo", ...],
  "seasonBreakdown": [
    {
      "season": "2024",
      "entries": 24,
      "wins": 9,
      "podiums": 14,
      "points": 581
    }
  ]
}

Races

Full race results including qualifying, sprint sessions, and practice data when available.

GET/v1/seasons/{year}/races

Returns all races for a given season including results summaries.

Parameter	Type	Required	Description
year	integer	Required	The season year

GET/v1/seasons/{year}/races/{round}

Returns the full result set for a specific race including practice, qualifying, sprint, and race classification.

Parameter	Type	Required	Description
year	integer	Required	The season year
round	integer	Required	Race round number within the season

json

{
  "name": "Bahrain Grand Prix",
  "season": "2024",
  "location": "Sakhir",
  "round": 1,
  "results": [
    {
      "position": "1",
      "driver": "Max Verstappen",
      "team": "Red Bull Racing",
      "time": "1:31:44.742",
      "status": "Finished"
    },
    {
      "position": "2",
      "driver": "Sergio Perez",
      "team": "Red Bull Racing",
      "time": "+22.457",
      "status": "Finished"
    }
  ],
  "qualifying_results": [ ... ],
  "sprint_results": null,
  "practice_results": [ ... ]
}

Errors

The API uses standard HTTP status codes. Errors return a consistent JSON structure.

Code	Status	Description
200	OK	Request succeeded.
400	Bad Request	Invalid query parameter or malformed request.
401	Unauthorized	Missing or invalid API key.
403	Forbidden	API key does not have access to the requested resource.
404	Not Found	The requested resource does not exist.
429	Too Many Requests	Rate limit exceeded. Retry after the time in X-RateLimit-Reset.
500	Internal Server Error	Something went wrong on our end. Please try again later.

json

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Season '2099' does not exist.",
    "status": 404
  }
}

Code Examples

Quick-start snippets in popular languages.

cURL

bash

curl -s \
  -H "Authorization: Bearer gxb_sk_live_xxxxxxxxxxxxxxxx" \
  "https://api.gearboxhub.com/v1/seasons/2024" | jq .

JavaScript / TypeScript

javascript

const API_KEY = process.env.GEARBOX_API_KEY;

const response = await fetch(
  "https://api.gearboxhub.com/v1/drivers/lewis-hamilton",
  {
    headers: {
      Authorization: `Bearer ${API_KEY}`,
      "Content-Type": "application/json",
    },
  }
);

const driver = await response.json();
console.log(driver.data);

Python

python

import requests
import os

API_KEY = os.environ["GEARBOX_API_KEY"]
BASE_URL = "https://api.gearboxhub.com/v1"

response = requests.get(
    f"{BASE_URL}/seasons/2024/races",
    headers={"Authorization": f"Bearer {API_KEY}"},
)
response.raise_for_status()

races = response.json()["data"]
for race in races:
    print(f"Round {race['round']}: {race['name']}")

package main

import (
	"encoding/json"
	"fmt"
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("GET",
		"https://api.gearboxhub.com/v1/teams/red-bull-racing", nil)
	req.Header.Set("Authorization",
		"Bearer "+os.Getenv("GEARBOX_API_KEY"))

	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()

	var team map[string]interface{}
	json.NewDecoder(resp.Body).Decode(&team)
	fmt.Println(team["team"], "-", team["points"], "pts")
}