openf1-js

JavaScript SDK for the OpenF1 API.

npm install openf1-js

Installation

npm install openf1-js

Basic Usage

import { OpenF1 } from "openf1-js";

// Create an API client (default: JSON mode)
const api = new OpenF1();

// Use CSV mode globally
const apiCsv = new OpenF1({ mode: "csv" });
// All endpoint methods support CSV mode, e.g.:
const csvData = await apiCsv.getCarData({ session_key: 1234 }); // returns CSV string

Global Options

The OpenF1 constructor accepts an options object:

Option	Type	Default	Description
baseURL	string	https://api.openf1.org/v1/	Override API base URL
mode	'json' \| 'csv'	'json'	Response format for all endpoints

Endpoint Methods & Parameters

All endpoint methods accept an optional params object, which is passed as query parameters to the API. See the OpenF1 API docs for full parameter details. Here are some examples:

// Car data for a specific driver/session, with a filter
await api.getCarData({ driver_number: 55, session_key: 9159, speed: ">=315" });

// Drivers in a session
await api.getDrivers({ driver_number: 1, session_key: 9158 });

// Intervals with a filter
await api.getIntervals({ session_key: 9165, interval: "<0.005" });

// Location data in a time window
await api.getLocation({
  session_key: 9161,
  driver_number: 81,
  date: ">2023-09-16T13:03:35.200",
  date2: "<2023-09-16T13:03:35.800",
});

// Meetings by year/country
await api.getMeetings({ year: 2023, country_name: "Singapore" });

// Pit stops with duration filter
await api.getPit({ session_key: 9158, pit_duration: "<31" });

// Position for a driver in a meeting
await api.getPosition({
  meeting_key: 1217,
  driver_number: 40,
  position: "<=3",
});

// Race control messages
await api.getRaceControl({
  flag: "BLACK AND WHITE",
  driver_number: 1,
  date: ">=2023-01-01",
  date2: "<2023-09-01",
});

// Sessions by country, name, and year
await api.getSessions({
  country_name: "Belgium",
  session_name: "Sprint",
  year: 2023,
});

// Session results for top 3
await api.getSessionResult({ session_key: 7782, position: "<=3" });

// Starting grid for a session
await api.getStartingGrid({ session_key: 7783, position: "<=3" });

// Stints with tyre age filter
await api.getStints({ session_key: 9165, tyre_age_at_start: ">=3" });

// Team radio for a driver/session
await api.getTeamRadio({ session_key: 9158, driver_number: 11 });

// Weather with filters
await api.getWeather({
  meeting_key: 1208,
  wind_direction: ">=130",
  track_temperature: ">=52",
});

Endpoint Attributes & Parameters

Below are the request parameters (query params) and response attributes for each endpoint, based on the OpenF1 API and SDK types.

Car Data (`getCarData`)

Name	Type	Description
brake	number	0 or 100
date	string	ISO 8601
driver_number	number
drs	number	The Drag Reduction System (DRS) status (see mapping table below).
meeting_key	number	The unique identifier for the meeting. Use `latest` to identify the latest or current meeting.
n_gear	number	0-8. 0 indicates neutral or no gear engaged
rpm	number
session_key	number
speed	number	km/h
throttle	number	%

DRS value	Interpretation
0	DRS off
1	DRS off
2	?
3	?
8	Detected, eligible once in activation zone
9	?
10	DRS on
12	DRS on
14	DRS on

Request params: Any of the above fields can be used as a query param (e.g. driver_number, session_key, speed, etc). Filters like >=, <= are supported for numeric fields.