Welcome to yukinator’s documentation!

Yukinator is an unnofficial API wrapper for Ergast API.

Package is created mainly for learning purposes. There are already at least two other wrappers worth checking: fastF1 - a swiss army knife for F1-related analyses, pyErgast - a neat pandas wrapper.

The name of the wrapper is Yukinator, in honor of the Japanese Formula 1 driver - Yuki Tsunoda.

Features

  • Extensive: covers all Ergast API endpoints

  • Responsible: minimize the load on the API server

    • implemented caching

  • Simple: easy to use and customize:

    • object-oriented design

    • use of data transfer objects

    • converts adequate fields from strings to the more suitable types

  • Lightweight: minimal usage of the third-party packages

Installation

pip install yukinator

Getting started

Obtaining data for an Ergast API endpoint is very simple. For example, you can get a list of race objects from the 2020 season like this:

import yukinator

y = yukinator.Yuki()
races_2020 = y.get_races(year=2020)

The wrapper is initiated with the caching enabled by default. You can manually set the caching-related attributes like a directory for cache file, time after cached items expire, or clear the whole cache before the first request as follows:

y = yukinator.Yuki(cache_dir='f1project/races', expires_after=9000, force_clear=True)

The caching can be also disabled (strongly not recommended):

y = yukinator.Yuki(cache_enabled=False)

Chosen fields of the object can be accessed easily:

race_1 = races_2020[0]

# print name of the race
print(race_1.raceName)

# print name from every nested Circuit object
for race in races_2020:
    print(race.Circuit.circuitName)

Every object from the obtained list can be converted to the simpler structures:

# convert object to the dictionary
race_1_dict = race_1.to_dict()

# convert object to the tuple
race_1_tuple = race_1.to_tuple()

# convert object to the flat dict - useful for creating pandas dataframes
race_1_flat_dict = race_1.to_flat_dict()

# convert object to a json string
race_1_json = race_1.to_json()

WARNING

The Ergast API has a limit of four calls per second and 200 per hour. Please take care while calling the methods within a loop.

Help, questions, and contributing

All contributors are very welcome. If you have any questions or a bug to report feel free to open an issue.

External packages

Yukinator depends on these third-party packages:

Main class and submodules

From here you can refer to the main class - Yuki and submodules documentation.

Index