Which function for X data?¶
Background
Every page on the iRacing Membersite receives its data, to be nicely displayed, from various URL endpoints in the form of /GetSomeData that is usually in JSON format.
The functions below interact with 1 endpoint each and use the provided arguments as the parameters in the URL query string that we've found it accepts. It is then mapped into a class object for ease of use. (More details here)
While some of these endpoints reveal data that can't be found anywhere else, others will return such little information that you might wonder why they exist at all. Our primary goal is to provide accessibility to the data, not make sense of it..
Warning
We do not currently offer error handling in the event of an invalid input. Data returned from iRacing is mapped into objects based on the specific dictionary key values that they give us. When a reponse is an empty dictionary (due to an invalid input to iRacing) you will recieve an error. We plan to modify this to return a None object with a warning instead so that the program won't crash.
Driver Data¶
Data returned from these methods require a driver (cust_id) to be included in the query parameters. A good example is event_results(); It can return all kinds of different race results, but only ones related to a specific cust_id. For all results of a series, go to series_race_results()
career_stats()¶
Returns a list of CareerStats objects as seen on iRacing's Career Profile.
| Args/Kwargs | Description |
|---|---|
| cust_id | Which driver’s Career Stats to return. |
driver_stats()¶
Returns a list of DriverStats objects that match the given parameters. This is the backend source for iRacing's Driver Stats Page.
This method provides functionality that the iRacing page does not. It search drivers by name. It is arguably the easiest method to obtain driver information.
| Args/Kwargs | Description |
|---|---|
search='null' |
Useful for looking up a specific driver. (e.g. 'John Smitherson5') Also accepts partial names to return all matching drivers. |
country='null' |
Return only drivers from a given country. Accepted values can be found in the CountryCode enum from the constants module for convienence. |
| category=Category.road.value | Selects the race discipline. (The Category enum is from the constants module) |
| class_low=None class_high=None |
Filters results by the driver's License Class. |
| irating_low=None irating_high=None |
Filters results by the driver's iRating. |
| ttrating_low=None ttrating_high=None |
Filters results by the driver's ttRating. |
| starts_avg_low=None starts_avg_high=None |
Filters results by the driver's average starting position. |
| finish_avg_low=None finish_avg_high=None |
Filters results by the driver's average finish position. |
| points_avg_low=None points_avg_high=None |
Filters results by the driver's average champ points awarded. |
| inc_avg_low=None inc_avg_high=None |
Filters results by the driver's average incidents per race. |
| num_results_low=1 num_results_high=25 |
The first result of the query to return and the last result of the query to return. |
| sort=Sort.irating.value order=Sort.descending.value |
How to sort and order the data. The default is to sort the data with the most recent race as the first result. The Sort enum is from the constants module. |
| active=1 | Should let you see non-active drivers with 0, but appears that iRacing does not allow it. |
| friend=None watched=None recent=None |
Accepts a cust_id to filter results to friend, watched, or recent.!Note: Only works for the currently logged in members cust_id. |
| cust_id=None | Does not affect returned data |
driver_status()¶
Returns friends list for the person logged in. (gold star for least useful)
| Args/Kwargs | Description |
|---|---|
| cust_id=None | Returns the status info of the provided cust_id. If logged in while also providing your custid, it will also return the status info of your friends and studied/blacklisted drivers. |
| friends=1 | Toggles display of friends in results. |
| studied=1 | Toggles display of studied drivers in results. |
| blacklisted=1 | Toggles display of blacklisted drivers in results. |
event_results()¶
Returns a list of EventResults objects that the driver has participated in. This is the backend data for iRacing's My Series Results. Contains the summary information about the results of the event. For detailed information about a specific session, see: subsession_data().
| Args/Kwargs | Description |
|---|---|
| cust_id | Which driver's events to return. |
| quarter | Which quarter/season of the year to return data from. |
| show_races=1 show_quals=None show_tts=None show_ops=None |
A value of 1 includes the session type in the return. A value of None excludes the session type from the results. |
| show_official=1 show_unofficial=None |
Toggles official/non-official sessions with values of 1 or None. |
| show_rookie=1 show_class_d=1 show_class_c=1 show_class_b=1 show_class_a=1 show_pro=1 show_prowc=1 |
Filters results by the license class that a series requires. Setting only show_class_a to 1 for the road category will only display results from the iGPS series, as that is the only series with an A class requirement. |
| result_num_low=1 result_num_high=25 |
First result of the data to return. Last result of the data to return. |
| sort=Sort.start_time.value order=Sort.descending.value |
How to sort and order the data. The default is to sort the data with the most recent race as the first result. The Sort enum is from the constants module. |
| data_format='json' | Other values are currently unknown. |
| category=Category.road.value | Which category of race discipline to return. The Category enum is from the constants module. |
| year=datetime.today().year | Which year to query. The default sets to the current years data. |
| race_week=None | Which raceweek of the quarter/season to query. |
| track_id=None car_class=None car_id=None |
Allows to filter results to a specific track, car class, car, or a combination of all three. |
| start_low=None start_high=None |
Filters results by the driver's starting position. |
| finish_low=None finish_high=None |
Filters results by the driver's finish position. |
| incidents_low=None incidents_high=None |
Filters results by the driver's number of incidents. |
| points_champ_low=None points_champ_high=None |
Filters results by driver's champ points awarded. |
irating()¶
Utilizes the stats_chart() method to return a list of iRating values. Used in the membersite's Career Profile charts.
Accessing irating.current() will give the most recent irating of a user.
| Args/Kwargs | Description |
|---|---|
| cust_id | Which driver’s irating to return. |
| category | Selects the race discipline. The Category enum from constants module can be used here. |
last_races_stats()¶
Returns a list of LastRacesStats objects each representing a race for the driver's last 10 races; used in the membersite's Career Profile "Last 10 Races" table.
| Args/Kwargs | Description |
|---|---|
| cust_id | Which driver’s races to return. |
last_series()¶
Returns a list of LastSeries objects each representing 1 of the driver's last 3 series; Used in the membersite's Career Profile "Last 3 Series" table.
| Args/Kwargs | Description |
|---|---|
| cust_id | Which driver’s series to return. |
license_class()¶
Utilizes the stats_chart() method to return a list of license values; Used in the membersite's Career Profile charts.
See the LicenseClass class for how to further use this data. (Link to page coming soon...)
| Args/Kwargs | Description |
|---|---|
| cust_id | Which driver’s stats to return. |
| category | Selects the race discipline. The Category enum from constants module can be used here. |
member_cars_driven()¶
Returns a list of car_ids that the member has driven.
| Args/Kwargs | Description |
|---|---|
| cust_id | Which member to search for their car's driven. |
member_division()¶
Returns which division the driver was in for the specified season_id. ("was" because a season_id can be a season that has concluded)
| Args/Kwargs | Description |
|---|---|
| cust_id | Which member's division to return. |
| season_id | Which season to check for the driver's division. |
member_subsession_id_from_session()¶
Returns which subsession_id that a member was in from a given session_id. This might be useful when you you know the session_id before the race session were split into subsessions, but otherwise subsession is usually included for the driver in other queries.
| Args/Kwargs | Description |
|---|---|
| cust_id | Which member's subsession_id to return. |
| session_id | Which session to look in for the driver's subsession. |
personal_bests()¶
Returns a list of PersonalBests objects each representing a best laptime for every car/track/event_type combo, as seen on the /CareerStats page.
| Args/Kwargs | Description |
|---|---|
| cust_id | Which driver’s laptimes to return. |
| car_id | Which car's laptimes to return for the driver. |
race_laps_driver()¶
Returns a single RaceLapsDriver object containing nested Driver data for all laps completed of a single driver. sim_sess_id specifies the laps from practice, qual, or race.
| Args/Kwargs | Description |
|---|---|
| cust_id | Which driver’s lap data to return. |
| subsession_id | Which subsession's data to return. |
| sim_session_type= SimSessionType.race.value |
Which segment of a race session to return results for. (Practice, Qualify, Race) The SimSessionType enum is from the constants module. |
stats_chart()¶
Returns a list in the form of time:value for the race category specified.
| Args/Kwargs | Description |
|---|---|
| cust_id | Which driver’s chart to return. |
| category | Which race category to return. The Category enum from the constants module provides available values. |
| chart_type | Type of chart to return. (iRating, ttRating, and License Class) The ChartType enum from the constants module provides easy access. |
ttrating()¶
Utilizes the stats_chart class to return a list of ttrating values that are used in the /CareerStats charts.
| Args/Kwargs | Description |
|---|---|
| cust_id | Which driver’s ttrating to return. |
| category | Selects the race discipline. The Category enum from constants module can be used here. |
yearly_stats()¶
Returns a list of YearlyStats objects breakdown of career stats by year, as seen on the driver profile page.
| Args/Kwargs | Description |
|---|---|
| cust_id | Which driver’s Yearly Stats to return. |
Series Data¶
Data returned from these methods return information about a series.
Note
On the topic of series_id and season_id:
series_id refers to the specific configuration for a series that does not change. e.g. The "Advanced Mazda MX-5 Cup Series" has a series id of 231. It refers to the car, license, caution types, incident limits, and grid size.
season_id refers to time period that a series will be active with a given track configuration. It is used to hold all the stats and races for a specific series during a season. The series referenced above had a season id of 2846 for the year 2020 quarter 3.
active_op_counts()¶
Returns a list of OpenPractice objects sessions that are currently active. By default only sessions with registered drivers are included. Use include_empty flag to see all sessions.
| Args/Kwargs | Description |
|---|---|
| count_max=250 | Sets the max number of results to return. |
| include_empty='n' | Set to 'y' if empty results should be included. |
| cust_id=None | Unknown purpose. |
next_event()¶
Returns a NextEvent object for a series.
| Args/Kwargs | Description |
|---|---|
| series_id | Which series to return the next event for. |
| event_type=EventType.race.value | Which event_type (Race, Practice) to return results for. The EventType enum is from the constants module. |
| date=now_five_min_floor() | Default is to use the same time format that iRacing's Race Guide uses, which is the current time rounded down the previous 5 minute mark. |
next_session_times()¶
Returns a list of 5 NextSessionTimes objects each with summary information about the upcoming sessions for a season_id.
| Args/Kwargs | Description |
|---|---|
| season_id | Which season to return the sessions for. |
season_standings()¶
Returns a list of SeasonStandings objects each representing a driver in the championship point standings of a series. This is the same data found in /statsseries.jsp.
| Args/Kwargs | Description |
|---|---|
| season_id | Which season's champ points to return. |
| race_week=None | Which race_week of the season to return. |
| car_class_id=None | Filters point standings to a specific car class. |
| club_id=None | Filters point standings to a specific club. |
| division=None | Filters point standings to a specific division. |
| result_num_low=1 result_num_high=25 |
The first result of the query to return and the last result of the query to return. |
| sort=Sort.champ_points.value order=Sort.descending.value |
How to sort and order the data. The default is to sort the data with the most recent race as the first result. The Sort enum is from the constants module. |
series_race_results()¶
Returns a list of SeriesRaceResults objects each representing a session that contained at least 1 registered driver for the requested race_week info for the specified season_id and race_week.
Results are restricted to a single week per query.
| Args/Kwargs | Description |
|---|---|
| season_id | Which season's results to return. |
| race_week=1 | Which week of the season to return. iRacing restricts this endpoint to querying a single week at a time. |
team_standings()¶
(Not finished) Returns championship point standings of Teams.
| Args/Kwargs | Description |
|---|---|
| season_id | Which season's standings to return. |
| car_class_id | Which car class to return data for. (Required to select 1 class) |
| car_id=None | Filters results to a specific car. |
| race_week=None | Filters results to a specific race week. |
Session Data¶
all_subsessions()¶
Returns subsession IDs for any additional race splits to the one provided.
| Args/Kwargs | Description |
|---|---|
| subsession_id | Which subsession to return the related subsession_id(s) for. |
private_results()¶
Returns a list of PrivateResults objects each representing a hosted session result.
| Args/Kwargs | Description |
|---|---|
| cust_id | Which driver’s hosted sessions to return. |
| time_start_lower time_start_upper |
Filters results to between these times. Note: Both fields are required for this endpoint to return data. |
| lower_bound=1 upper_bound=25 |
The first result of the query to return and the last result of the query to return. |
| sort=Sort.session_name.value order=Sort.ascending.value |
How to sort and order the data. The default is to sort the data alphabetically by session_name.The Sort enum is from the constants module. |
race_guide()¶
Returns a RaceGuide object containing all data used by the race guide page for the active seasons. Filters are identical to those found when visiting the race guide with a browser.
| Args/Kwargs | Description |
|---|---|
| rookie=None class_d=None class_c=None class_b=None class_a=None class_pro=None class_prowc=None |
Filters for license classes. Setting to 0 will filter results to exclude series requiring that license.Any combination is allowed. |
| oval=None road=None dirt_oval=None dirt_road=None |
Filters for race categories. Setting to 0 will filter results to exclude the category from being returned.Any combination is allowed. |
| fixed_setup=None | Set to 1 to display only fixed setup sessions. (None displays both. There is not an option to display only open setups) |
| multiclass=None | Set to 1 to display only multiclass sessions |
| meets_mpr=None | Set to 1 to display races that meet your MPR. (Restricted to loggedin member) |
| populated=None | Set to 1 to display only populated sessions. |
| eligible=None | Set to 1 to dispaly only the series you are eligible for. (Restricted to logged in member) |
| official=None | Set to 1 to return only official race sessions. |
| time=now_five_min_floor() | The Race Guide uses the current time (in unix milliseconds) rounded down the previous 5 minute mark as the default value. A time in the future is allowed. |
race_laps_all()¶
Returns a RaceLapsAll object with nested objects for all drivers and lap data from a session.
The class of car can be set for multiclass races. To specify laps of a single driver, use race_laps_driver().
| Args/Kwargs | Description |
|---|---|
| subsession_id | Which subsession to return lap information for. |
| car_class_id=None | For multiclass races, you can specify to return the lap data for a single class. |
| sim_session_type= SimSessionType.race.value |
Which segment of a race session to return results for. (Practice, Qualify, Race) The SimSessionType enum is from the constants module. |
season_from_session()¶
Returns a single season_id that the session_id was for.
| Args/Kwargs | Description |
|---|---|
| session_id | Which session_id to return a season_id for |
subsession_data()¶
Returns a SubsessionData object. This endpoint contains unique datapoints that are unavailable elsewhere.
!Note: The segments of a session are not seperated (Practice, Qualify, Race). Results for each driver for each segment are listed concurrently. e.g If 25 drivers participate, there will be 75 Driver objects returned. 25 for each session segment.
| Args/Kwargs | Description |
|---|---|
| subsession_id | Which subsession's data to return. |
total_registered_all()¶
Broken at the moment ~~Returns a list of every upcoming session and the number of drivers that have registered. This data is used in the small text next to each series name in /Series.do that shows number of registered drivers for that series.~~
| Args/Kwargs | Description |
|---|---|
Global Data¶
car_class_by_id()¶
Returns a CarClass object from the given car_class_id.
| Args/Kwargs | Description |
|---|---|
| car_class_id=0 | Which car_class to retrieve. The default value of 0 returns a unique CarClass: HostedAllCarsClass.Instead of returning car objects in the cars_in_class attribute, HostedAllCarsClass is a list of all CarClasses with attributes "name" and "id". |
current_seasons()¶
Returns a Season object for every season.
| Args/Kwargs | Description |
|---|---|
| only_active=1 | Set to 0 to include all previous seasons and currently active. |
| kwargs | See table below for available boolean kwargs. |
Setting any of these to =False will hide that field in the returned data
| series_short_name | cat_id | season_id | year |
| quarter | series_id | active | license_eligible |
| only_active | is_lite | car_classes | tracks |
| start | end | cars | race_week |
| category | series_lic_group_id | car_id |
world_records()¶
Returns a list of WorldRecord objects] each representing a drivers collection of lap times across various car/track combo.
| Args/Kwargs | Description |
|---|---|
| year | Which year to return lap records for. |
| quarter | Which quarter/season to return lap records for. |
| car_id | Which car to return lap records for. |
| track_id | Which track to return lap records for. |
| cust_id=None | Only works if cust_id matches the logged in user. Otherwise does nothing. |