openf1-js

v0.1.3

Published

8 months ago

OpenF1 API (https://openf1.org) JavaScript SDK

0High
0Medium
0Low

ianleckey

f1 openf1 sdk api formula1

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.

Drivers (`getDrivers`)

| Name | Type | Description | | -------------- | ------ | ----------- | | broadcast_name | string | | | country_code | string | | | driver_number | number | | | first_name | string | | | full_name | string | | | headshot_url | string | | | last_name | string | | | meeting_key | number | | | name_acronym | string | | | session_key | number | | | team_colour | string | | | team_name | string | |