Main class

class yukinator.yukinator.Yuki(headers: dict = {'User-Agent': 'Yukinator'}, cache_enabled: bool = True, cache_dir: str = '/home/docs/checkouts/readthedocs.org/user_builds/yukinator/checkouts/latest/docs', expires_after: Union[None, int, float, str] = 3600, force_clear: bool = False)

Bases: object

API wrapper for the Ergast F1 API.

The data for every endpoint is provided in the handy data transfer object.

DTOs have methods for converting them into simpler structures.

to_dict(): convert an object to a dictionary

to_flat_dict(): convert object to a flat dictionary

to_tuple(): convert an object to a tuple

to_json(): convert an object to a JSON string

Disabling the caching is strongly not recommended.
Ergast API has a limit of four calls per second and 200 per hour.
Please take care while calling the methods within a loop.

get_circuits(year: Optional[Union[int, str]] = None, race: Optional[Union[int, str]] = None) → list[yukinator.objects.CircuitDTO]

Obtain a list of data transfer objects with information about the circuits.

By default, return every circuit in the F1 history.
If only the year is provided, return a list for that season.
If year and race are provided, return a list for that race and year.
If only the race is provided, raise the WrongQueryParameters error.
If provided parameters are not real (e.g. year from the future),
raise the WrongQueryParameters error.

Parameters

year (int, str, None) – Optional parameter with a year to be queried. Defaults to None.
race (int, str, None) – Optional parameter with a number of a race
None. (to be queried. Defaults to) –

Returns

List of data transfer objects.

Return type

list[CircuitDTO]

Raises

HTTPError – The response’s status code is not less than 400.
WrongQueryParameters – The output for provided query parameters is empty.

get_constructors(year: Optional[Union[int, str]] = None, race: Optional[Union[int, str]] = None) → list[yukinator.objects.ConstructorDTO]

Obtain a list of data transfer objects with information about the constructors.

By default, return every constructor in the F1 history.
If only the year is provided, return a list for that season.
If year and race are provided, return a list for that race and year.
If only the race is provided, raise the WrongQueryParameters error.
If provided parameters are not real (e.g. year from the future),
raise the WrongQueryParameters error.

Parameters

year (int, str, None) – Optional parameter with a year to be queried. Defaults to None.
race (int, str, None) – Optional parameter with a number of a race to be queried. Defaults to None.

Returns

List of data transfer objects.

Return type

list[ConstructorDTO]

Raises

HTTPError – The response’s status code is not less than 400.
WrongQueryParameters – The output for provided query parameters is empty.

get_constructors_standings(year: Union[int, str] = 'current', race: Optional[Union[int, str]] = None, winners: bool = False) → list[yukinator.objects.ConstructorStandingDTO]

Obtain a list of data transfer objects with the constructor standings.

By default, return the standings for a current seasons.
If only year parameter is provided, return the standings at the end of that season.
If year and race are provided, return the standings after that race in that season.
If only the race is provided, return the standings after that race in the current season.
If winners argument is True, list all winners of the constructor championships.
If provided parameters are not real (e.g. year from the future),
raise the WrongQueryParameters error.

Parameters

year (int, str) – Optional parameter with a year to be queried. Defaults to ‘current’.
race (int, str, None) – Optional parameter with a number of a race to be queried. Defaults to ‘last’.
winners (bool) – Optional parameter for listing all winners of championship. Defaults to False.

Returns

List of data transfer objects.

Return type

list[RaceResultDTO]

Raises

HTTPError – The response’s status code is not less than 400.
WrongQueryParameters – The output for provided query parameters is empty.

get_drivers(year: Optional[Union[int, str]] = None, race: Optional[Union[int, str]] = None) → list[yukinator.objects.DriverDTO]

Obtain a list of data transfer objects with information about the drivers.

By default, return every driver in the F1 history.
If only the year is provided, return a list for that season.
If year and race are provided, return a list for that race and year.
If only the race is provided, raise the WrongQueryParameters error.
If provided parameters are not real (e.g. year from the future),
raise the WrongQueryParameters error.

Parameters

year (int, str, None) – Optional parameter with a year to be queried. Defaults to None.
race (int, str, None) – Optional parameter with a number of a race to be queried. Defaults to None.

Returns

List of data transfer objects.

Return type

list[DriverDTO]

Raises

HTTPError – The response’s status code is not less than 400.
WrongQueryParameters – The output for provided query parameters is empty.

get_drivers_standings(year: Union[int, str] = 'current', race: Optional[Union[int, str]] = None, winners: bool = False) → list[yukinator.objects.DriverStandingDTO]

Obtain a list of data transfer objects with the driver standings.

By default, return the standings for a current seasons.
If only year parameter is provided, return the standings at the end of that season.
If year and race are provided, return the standings after that race in that season.
If only the race is provided, return the standings after that race in the current season.
If winners argument is True, list all winners of the driver championships.
If provided parameters are not real (e.g. year from the future),
raise the WrongQueryParameters error.

Parameters

year (int, str) – Optional parameter with a year to be queried. Defaults to ‘current’.
race (int, str, None) – Optional parameter with a number of a race to be queried. Defaults to ‘last’.
winners (bool) – Optional parameter for listing all winners of championship. Defaults to False.

Returns

List of data transfer objects.

Return type

list[RaceResultDTO]

Raises

HTTPError – The response’s status code is not less than 400.
WrongQueryParameters – The output for provided query parameters is empty.

get_finishing_statuses(year: Optional[Union[int, str]] = None, race: Optional[Union[int, str]] = None) → list[yukinator.objects.StatusDTO]

Obtain a list of data transfer objects with finishing statuses.

By default, return all of finishing status codes.
If only the year is provided, return the status codes for that season.
If year and race are provided, return the status codes for that race.
If only the race is provided, raise the WrongQueryParameters error.
If provided parameters are not real (e.g. year from the future),
raise the WrongQueryParameters error.

Parameters

year (int, str, None) – Optional parameter with a year to be queried. Defaults to None.
race (int, str, None) – Optional parameter with a number of a race to be queried. Defaults to None.

Returns

List of data transfer objects.

Return type

list[StatusDTO]

Raises

HTTPError – The response’s status code is not less than 400.
WrongQueryParameters – The output for provided query parameters is empty.

get_lap_times(year: Union[int, str] = 'current', race: Union[int, str] = 'last', lap: Union[int, str] = 1) → list[yukinator.objects.LapDTO]

Obtain a list of data transfer objects with lap times.

Lap time data is available from the 1996 season onwards.

By default, return the pit stops from the last race.
If only the year is provided, return the pit stops from the last race of that season.
If only the year and race are provided, return the pit stops of that race.
If only the race is provided, return the pit stops of that race in the current season.
If only the lap parameters is provided, return that lap from the last race.
If only the race and lap parameters are provided, return that lap from that race
from a current season.
If only the year and lap parameters are provided, return that lap from the last race
from that season.
If provided parameters are not real (e.g. year from the future),
raise the WrongQueryParameters error.

Parameters

year (int, str) – Optional parameter with a year to be queried. Defaults to ‘current’.
race (int, str) – Optional parameter with a number of a race to be queried. Defaults to ‘last’.
lap (int, str) – Optional parameter with a number of a lap to be queried. Defaults to 1.

Returns

List of data transfer objects.

Return type

list[LapDTO]

Raises

HTTPError – The response’s status code is not less than 400.
WrongQueryParameters – The output for provided query parameters is empty.

get_pit_stops(year: Union[int, str] = 'current', race: Union[int, str] = 'last') → list[yukinator.objects.PitStopDTO]

Obtain a list of data transfer objects with information about the pit stops .

Pit stop data is available from the 2012 season onwards.

By default, return the pit stops from the last race.
If only the year is provided, return the pit stops from the last race of that season.
If only the year and race are provided, return the pit stops from that race.
If only the race is provided, return the pit stops from that race in the current season.
If provided parameters are not real (e.g. year from the future),
raise the WrongQueryParameters error.

Parameters

year (int, str) – Optional parameter with a year to be queried. Defaults to ‘current’.
race (int, str) – Optional parameter with a number of a race to be queried. Defaults to ‘last’.

Returns

List of data transfer objects.

Return type

list[PitStopDTO]

Raises

HTTPError – The response’s status code is not less than 400.
WrongQueryParameters – The output for provided query parameters is empty.

get_qualifying_results(year: Union[int, str] = 'current', race: Union[int, str] = 'last') → list[yukinator.objects.QualifyingResultDTO]

Obtain a list of data transfer objects with the qualifying results.

By default, return the results for the last GP.
If only year parameter is provided, return the results for the last GP of that year.
If year and race are provided, return the results for that GP from that season.
If only the race is provided, return the results for that GP from current season.
If provided parameters are not real (e.g. year from the future),
raise the WrongQueryParameters error.

Parameters

year (int, str) – Optional parameter with a year to be queried. Defaults to ‘current’.
race (int, str) – Optional parameter with a number of a race to be queried. Defaults to ‘last’.

Returns

List of data transfer objects.

Return type

list[QualyfingResultDTO]

Raises

HTTPError – The response’s status code is not less than 400.
WrongQueryParameters – The output for provided query parameters is empty.

get_race_results(year: Union[int, str] = 'current', race: Union[int, str] = 'last') → list[yukinator.objects.RaceResultDTO]

Obtain a list of data transfer objects with the race results.

By default, return the results for the last race.
If only year parameter is provided, return the results for the last race of that year.
If year and race are provided, return the results for that race from that season.
If only the race is provided, return the results for that race from current season.
If provided parameters are not real (e.g. year from the future),
raise the WrongQueryParameters error.

Parameters

year (int, str) – Optional parameter with a year to be queried. Defaults to ‘current’.
race (int, str) – Optional parameter with a number of a race to be queried. Defaults to ‘last’.

Returns

List of data transfer objects.

Return type

list[RaceResultDTO]

Raises

HTTPError – The response’s status code is not less than 400.
WrongQueryParameters – The output for provided query parameters is empty.

get_races(year: Union[int, str] = 'current', race: Optional[Union[int, str]] = None) → list[yukinator.objects.RaceDTO]

Obtain a list of data transfer objects with information about the races.

By default, return the races for a current season.
If only the year is provided, return a list for that season.
If year and race are provided, return a list for that race and year.
If only the race is provided, return a race from a current season.
If provided parameters are not real (e.g. year from the future),
raise the WrongQueryParameters error.

Parameters

year (int, str) – Optional parameter with a year to be queried. Defaults to ‘current’
race (int, str, None) – Optional parameter with a number of a race to be queried. Defaults to None.

Returns

List of data transfer objects.

Return type

list[RaceDTO]

Raises

HTTPError – The response’s status code is not less than 400.
WrongQueryParameters – The output for provided query parameters is empty.

get_seasons() → list[yukinator.objects.SeasonDTO]

Obtain a list of data transfer objects with all F1 seasons

Returns: List of data transfer objects.
Return type: list[SeasonDTO]
Raises: HTTPError – The response’s status code is not less than 400.

get_sprint_results(year: Union[int, str] = 'current', race: Optional[Union[int, str]] = None) → list[yukinator.objects.SprintResultDTO]

Obtain a list of data transfer objects with the sprint results.

By default, return the results of sprints in the current season.
If only year parameter is provided, return the results for that year.
If year and race are provided, return the results for that GP from that season.
If only the race is provided, return the results for that GP from current season.
If provided parameters are not real (e.g. year from the future),
raise the WrongQueryParameters error.

Parameters

year (int, str) – Optional parameter with a year to be queried. Defaults to ‘current’.
race (int, str, None) – Optional parameter with a number of a race to be queried. Defaults to None.

Returns

List of data transfer objects.

Return type

list[SprintResultDTO]

Raises

HTTPError – The response’s status code is not less than 400.
WrongQueryParameters – The output for provided query parameters is empty.