DOCSEARCHbyAlgolia
Submit Docs

OpenF1 API

repository·main·Indexed 23 days ago

https://github.com/br-g/openf1

An open-source API providing real-time and historical Formula 1 data, including lap timings, car telemetry, and driver information. Version 1.9.14 includes tools for data ingestion via MongoDB and MQTT, a REST API for querying car data and session results, and modules for scraping F1 schedules and starting grids.

Tokens
16.1K
Snippets
55
Records
94
Agent score
81%

What's inside openf1

  1. Overview of OpenF1 API data and access

    main

    OpenF1 is an open-source API that provides Formula 1 telemetry, timing, and session data in JSON and CSV formats.

    Data Access Tiers

    • Historical Data (2023 onwards): Free and accessible without authentication.
    • Real-time Data: Requires a paid subscription.

    You can interact with the API directly using a web browser or any standard HTTP client.

  2. Understand the live timing ingestion model

    main

    The live timing ingestion module processes F1 data through three primary abstractions:

    1. Topics and Messages: Data is streamed from Formula 1 via topics. Each topic acts as a specific channel for a particular data type (e.g., driver lists, tyre information). These channels deliver individual messages.
    2. t0 (reference time): In historical sessions, timestamps are often provided as relative offsets. t0 is the session's reference time point used to convert these relative offsets into absolute timestamps.
    3. Documents and Collections: Once messages are processed, they are stored as documents. A collection is a grouping of documents that share the same type. Definitions for these structures are located in core/processing/collections/.

  3. Ingest F1 schedule meetings and sessions

    main

    Use the openf1.services.f1_scraping.schedule module to ingest F1 schedule data. You can ingest either meetings or sessions for a specific year. If the --year parameter is omitted, the service defaults to the latest available season (either the season currently in progress or the upcoming season).

    To ingest meetings:

    python -m openf1.services.f1_scraping.schedule ingest-meetings --year 2025

    To ingest sessions:

    python -m openf1.services.f1_scraping.schedule ingest-sessions --year 2025
    python -m openf1.services.f1_scraping.schedule ingest-meetings --year 2025
python -m openf1.services.f1_scraping.schedule ingest-sessions --year 2025

  4. Create an interactive strategy dashboard with Python

    main

    You can follow this external tutorial to build an interactive strategy dashboard using Python and OpenF1 data. The tutorial is hosted on GitHub and demonstrates how to leverage the API for data visualization and strategy analysis.

    https://github.com/bordanattila/OpenF1_tutorial

  5. Ingest starting grid data

    main

    Use the openf1.services.f1_scraping.starting_grid module to ingest starting grid information. This command requires a --meeting-key and a --session-key. If omitted, it defaults to the latest session (last completed or in progress).

    Note: This function only works with qualifying sessions.

    python -m openf1.services.f1_scraping.starting_grid --meeting-key 1264 --session-key 9951

  6. Request query results in CSV format

    main

    By default, the OpenF1 API returns results in JSON format. To receive query results in CSV format—which is useful for importing data into spreadsheet software like Microsoft Excel—append the query parameter csv=true to your request URL.

    https://api.openf1.org/v1/sessions?year=2023&csv=true

  7. Convert OpenF1 API responses to DataFrames

    main

    When consuming OpenF1 data in Python or R, you can easily convert the JSON responses into DataFrames for analysis.

    Python (using pandas):

    import pandas as pd
# Assuming 'data' is the JSON list from the API response
df = pd.DataFrame(data)

    R (using httr and jsonlite):

    # Required libraries: httr, jsonlite
# Assuming 'parsed_data' is the result of fromJSON()
df <- do.call(rbind, lapply(parsed_data, data.frame, stringsAsFactors = FALSE))
df <- as.data.frame(t(as.matrix(df)))

  8. Install and run OpenF1 locally

    main

    To run the OpenF1 project locally for data ingestion and API querying, follow these steps:

    1. Prerequisites:

    2. Installation: Clone the repository and install the openf1 package in editable mode:

      git clone git@github.com:br-g/openf1.git
pip install -e openf1

    3. Configuration: Set the MONGO_CONNECTION_STRING environment variable to point to your MongoDB instance:

      export MONGO_CONNECTION_STRING="mongodb://localhost:27017"

    4. Execution: The project is divided into services for different tasks:

      • Scraped Data Ingestion: See services/f1_scraping/.
      • Live Timing Ingestion: See services/ingestor_livetiming/.
      • API Querying: See services/query_api/.
    git clone git@github.com:br-g/openf1.git
pip install -e openf1

export MONGO_CONNECTION_STRING="mongodb://localhost:27017"

  12. Perform time-based filtering with date ranges

    main

    To narrow down results using time ranges, use date_start and date_end parameters combined with comparison operators like >= (greater than or equal to) and <= (less than or equal to).

    Supported date formats are those compatible with Python's dateutil.parser.parse method. Examples of valid formats include:

    • ISO 8601: "2021-09-10T14:30:20" or "2021-09-10T14:30:20+00:00"
    • Simple dates: "2021-09-10", "09/10/2021", or "10 September 2021"
    • Human-readable: "Sep 10, 2021" or "Fri Sep 10 14:30:20 2021"
    • With Timezones: "2021-09-10 14:30:20 UTC" or "2021-09-10 14:30:20 EST"
    https://api.openf1.org/v1/sessions?date_start>=2023-09-01&date_end<=2023-09-30