Ergast-Py

A comprehensive Python wrapper for the Ergast API. Built for easy use and functionality, Ergast-py aims to bring the Ergast API into the Python network as seemlessly as possible.

NOTE: Ergast-py will continue development using a new publicly available API. Jolpica provides a drop-in replacement API for the Ergast API, and therefore development will continue with this new API in mind.

What is Ergast?

Ergast is a free, experimental API for accessing motor-racing data, dating back to the beginning of World Championships in 1950. The website provides plenty of detail into how effective the API can be, and the many options that are available for data gathering using it.

Why should I use Ergast-Py?

Ergast-Py provides a clean, Python orientated wrapper for this API. It has been designed to remove the heavy lifting of handling the API formatting behind the scenes, allowing developers to easily access the data that is relevant to them. All the data is conformed into clean class code, allowing for users to keep a Python-centric mindset whilst developing.

How to install

Ergast-py is a pip package, so can be installed with the pip command:

pip install ergast-py

Usage

Once ergast-py is installed on your system you can then begin using the library in querying the ergast API. To begin, initialise an instance of the Ergast() class.

Note: Whilst the package is called ergast-py, you need to import ergast_py

import ergast_py

e = ergast_py.Ergast()

Queries can then be built up with function calls in a sequential manner. Once you've built up a query, finally define what data you wish to get using a get_xyz() function.

# http://ergast.com/api/f1/2008/5/results
race_results = e.season(2008).round(5).get_results()

# http://ergast.com/api/f1/drivers/massa
felipe_massa = e.driver("massa").get_driver()

# http://ergast.com/api/f1/current/constructorStandings/3
constructor_standings = e.season().standing(3).get_constructor_standings()

Structure and Types

Ergast-py has many models which allow the user to more effectively use and manipulate the data available to them through Ergast. All models of data are available through .models.xyz.

Query building

There are 3 types of query available in the Ergast() class. FILTER functions build up the query, by filtering down the data that you will receive. PAGING functions control the flow of data if there is excessive amounts, limiting it to not overflow the API. RETURN functions detail what type of data you're expecting back from the query.

The order of the builder functions is inconsequential, however the final function called should be a return function.

Ergast().{paging/filter}.{return}

More detail on the available functions within the Ergast() class is available below.

Credits

This library would not be possible without the freely available Ergast API. For full information about the API and it's responsible use, please refer to their website. Poetry was used for package building and releasing.