falcon_alliance.Event

class falcon_alliance.Event(*args, **kwargs)

Class representing an event containing methods to get specific event information

key

TBA event key with the format yyyy[EVENT_CODE], where yyyy is the year, and EVENT_CODE is the event code of the event.

Type:: str

name

Official name of event on record either provided by FIRST or organizers of offseason event.

Type:: str, optional

event_code

Event short code, as provided by FIRST.

Type:: str

event_type

Event Type, as defined here: https://github.com/the-blue-alliance/the-blue-alliance/blob/master/consts/event_type.py#L2

Type:: int, optional

district

The district the event occurred in.

Type:: District, optional

city

City, town, village, etc. the event is located in.

Type:: str, optional

state_prov

State or Province the event is located in.

Type:: str, optional

country

Country the event is located in.

Type:: str, optional

start_date

Event start date in yyyy-mm-dd format.

Type:: datetime.datetime, optional

end_date

Event end date in yyyy-mm-dd format.

Type:: datetime.datetime, optional

year

Year the event data is for.

Type:: int

short_name

Same as name but doesn’t include event specifiers, such as ‘Regional’ or ‘District’. May be None.

Type:: str, optional

event_type_string

Event Type, eg Regional, District, or Offseason.

Type:: str

week

Week of the event relative to the first official season event, zero-indexed. Only valid for Regionals, Districts, and District Championships. Equal to None otherwise. (Eg. A season with a week 0 ‘preseason’ event does not count, and week 1 events will show 0 here. Seasons with a week 0.5 regional event will show week 0 for those event(s) and week 1 for week 1 events and so on.)

Type:: int, optional

address

Address of the event’s venue, if available.

Type:: str, optional

postal_code

Postal code from the event address.

Type:: str, optional

gmaps_place_id

Google Maps Place ID for the event address.

Type:: str, optional

gmaps_url

Link to address location on Google Maps.

Type:: str, optional

lat

Latitude for the event address.

Type:: float, optional

lng

Longitude for the event address.

Type:: float, optional

location_name

Name of the location at the address for the event, eg. Blue Alliance High School.

Type:: str, optional

timezone

Timezone name.

Type:: str, optional

website

The event’s website, if any.

Type:: str, optional

first_event_id

The FIRST internal Event ID, used to link to the event on the FRC webpage.

Type:: str, optional

first_event_code

Public facing event code used by FIRST (on frc-events.firstinspires.org, for example)

Type:: str, optional

webcasts

A list of all webcasts recording the event.

Type:: list[falcon_alliance.Event.Webcast, optional

division_keys

A list of event keys for the divisions of the event.

Type:: list, optional

parent_event_key

The TBA Event key that represents the event’s parent. Used to link back to the event from a division event. It is also the inverse relation of divison_keys.

Type:: str, optional

playoff_type

Playoff Type, as defined here: https://github.com/the-blue-alliance/the-blue-alliance/blob/master/consts/playoff_type.py#L4, or None.

Type:: int, optional

playoff_type_string

String representation of the playoff_type, or None.

Type:: str, optional

class Alliance(name: str, declines: List[str], picks: List[str], status: dict, backup: dict | None = None): Class representing an alliance in an event.

class DistrictPoints(points: Dict[str, Dict[str, int]], tiebreakers: Dict[str, Dict[str, int]]): Class representing an event’s district points given for all teams.

class ExtraStats(extra_stats: list, extra_stats_info: List[dict]): Information about extra statistics regarding the ranking of a team during an event.

class Insights(qual: dict, playoff: dict): Class representing the insights of an event (specific by year)

class OPRs(oprs: dict, dprs: dict, ccwms: dict)

Class representing different metrics (OPR/DPR/CCWMs) for teams during an event.

average(metric: str | None = None) → dict | float

Gets the average of all the metrics for said event; could also only get one average for a specific metric if you aren’t interested in all metrics.

Parameters:: metric (str) – A string representing which metric to get the average for (opr/dpr/ccwm). metric is optional, and if not passed in, the averages for all metrics will be retrieved.
Returns:: A dictionary containing the averages for all metrics or a decimal (float object) representing the average of one of the metrics if specified.
Return type:: Union[dict, float]

class Ranking(dq: int, extra_stats: ExtraStats, matches_played: int, qual_average: int, rank: int, record: Record, sort_orders: SortOrders, team_key: str): Class representing a team’s ranking during an event.

class Record(losses: int, ties: int, wins: int): Class representing a record of wins, losses and ties for either a certain level or throughout the event.

class SortOrders(sort_orders: list, sort_order_info: List[dict]): Information about the team used to determine ranking for an event.

class Status(playoff_average: float, level: str, record: Record, current_level_record: Record, status: str): Class representing a status of an alliance during an event.

class Webcast(type: str, channel: str, date: str | None = None, file: str | None = None): Class representing metadata and information about a webcast for an event.

alliances() → List[Alliance]

Retrieves all alliances of an event.

Returns:: A list of Alliance objects representing each alliance in the event.
Return type:: List[falcon_alliance.Event.Alliance]

average(metric: Metrics) → float

Retrieves the aveage of a certain metric based on the year.

Parameters:: metric (Metrics) – An Enum object representing which metric to use to find the average of something relating to a team of your desire.
Returns:: A float representing the average match score if Metrics.MATCH_SCORE is passed into metric or a float representing the average OPR/DPR/CCWM.
Return type:: float

awards() → List[Award]

Retrieves all awards distributed in an event.

Returns:: A list of Award objects representing each award distributed in an event.
Return type:: List[falcon_alliance.Award]

delete_matches(data: List[str]) → None

POST request to delete matches by match keys for an event.

Parameters:: data (list[str]) – List of matches to delete (eg [“qm1”, “qm2”, …])

district_points() → DistrictPoints | None

Retrieves district points for teams during an event for both qualification and tiebreaker matches.

Returns:: A DistrictPoints object containing “points” and “tiebreakers” fields, with each field possessing a dictionary mapping team keys to their points or None if the event doesn’t take place in a district or district points are not applicable to the event.
Return type:: Optional[Event.DistrictPoints]

insights() → Insights | None

Retrieves insights of an event (specific data about performance and the like at the event; specific by game). Insights can only be retrieved for any events from 2016 and onwards.

Returns:: An Insight object containing qualification and playoff insights from the event. Can be None if the event hasn’t occurred yet, and the fields of Insight may be None depending on how far the event has advanced.
Return type:: Optional[falcon_alliance.Event.Insights]

matches(simple: bool = False, keys: bool = False, timeseries: bool = False) → List[str | Match]

Retrieves all matches that occurred during an event.

Per TBA, the timeseries data is in development and therefore you should NOT rely on it.

Parameters:

simple (bool) – A boolean that specifies whether the results for each match should be ‘shortened’ and only contain more relevant information.
keys (bool) – A boolean that specifies whether only the keys of the matches should be retrieved.
timeseries (bool) – A boolean that specifies whether only the keys of the matches that have timeseries data should be retrieved.

Returns:

A dictionary with team keys as the keys of the dictionary and an EventTeamStatus object representing the status of said team as the values of the dictionary or a list of strings representing the keys of the teams that participated in an event or a list of Team objects, each representing a team that participated in an event.

Return type:

List[Union[str, falcon_alliance.Match]]

max(metric: Metrics) → Match | Tuple[float, Team]

Retrieves the maximum of a certain metric based on the year.

Parameters:: metric (Metrics) – An Enum object representing which metric to use to find the maximum of something relating to a team of your desire.
Returns:: A Match object representing the match with the maximum cumulative score (red alliance’s score + blue alliance’s score) if Metrics.MATCH_SCORE is passed into metric or a tuple containing the float representing the maximum OPR/DPR/CCWM during an event and a Team object representing the team that had the maximum OPR.
Return type:: Union[Match, tuple[float, falcon_alliance.Team]]

min(metric: Metrics) → Match | Tuple[float, Team]

Retrieves the minimum of a certain metric based on the year.

Parameters:: metric (Metrics) – An Enum object representing which metric to use to find the minimum of something relating to a team of your desire.
Returns:: A Match object representing the match with the minimum cumulative score (red alliance’s score + blue alliance’s score) if Metrics.MATCH_SCORE is passed into metric or a tuple containing the float representing the minimum OPR/DPR/CCWM during an event and a Team object representing the team that had the minimum OPR.
Return type:: Union[Match, tuple[float, falcon_alliance.Team]]

oprs() → OPRs

Retrieves different metrics for all teams during an event. To see an explanation on OPR and other metrics retrieved from an event, see https://www.thebluealliance.com/opr.

Returns:: An OPRs object containing a key/value pair for the OPRs, DPRs, and CCWMs of all teams at an event. The fields of OPRs may be empty if OPRs, DPRs, and CCWMs weren’t calculated.
Return type:: falcon_alliance.Event.OPRs

predictions() → dict

Retrieves predictions for matches of an event. May not work for all events since this endpoint is in beta per TBA.

Returns:: A dictionary containing the predictions of an event from TBA (contains year-specific information). May be an empty dictionary if there are no predictions available for that event.
Return type:: dict

rankings() → Dict[str, Ranking]

Retrieves a list of team rankings for an event.

Returns:: A dictionary with team keys as the keys of the dictionary and Ranking objects for that team’s information about their ranking at an event as values of the dictionary.
Return type:: Dict[str, falcon_alliance.Event.Ranking]

teams(simple: bool = False, keys: bool = False, statuses: bool = False) → List[str | Team] | Dict[str, EventTeamStatus]

Retrieves all teams who participated at an event.

Parameters:

simple (bool) – A boolean that specifies whether the results for each team should be ‘shortened’ and only contain more relevant information.
keys (bool) – A boolean that specifies whether only the names of the FRC teams should be retrieved.
statuses (bool) – A boolean that specifies whether a key/value pair of the statuses of teams in an event should be returned.

Returns:

A dictionary with team keys as the keys of the dictionary and an EventTeamStatus object representing the status of said team as the values of the dictionary or a list of strings representing the keys of the teams that participated in an event or a list of Team objects, each representing a team that participated in an event.

Return type:

Union[List[Union[str, falcon_alliance.Team]], Dict[str, falcon_alliance.EventTeamStatus]]

update_alliance_selections(data: List[list]) → None

POST request to update info about alliance selections for an event.

Parameters:: data (list[list]) – 2D list with each list representing an alliance and the elements inside each sublist representing keys in the corresponding alliance.

update_awards(data: List[dict]) → None

POST request to update info regarding awards for an event.

Parameters:: data (list[dict]) – List of dictionaries containing information about each award (eg name of the award, recipient of the award, and the awardee).

update_info(data: dict) → None

POST request to update info for an event.

Parameters:: data (dict) – Dictionary containing info that the event needs to be updated with (eg FIRST code, playoff type, and webcast URLs).

update_match_videos(data: dict) → None: POST request to update the match videos for an event. :param data: Mapping of partial match keys (i.e. qm1) to YouTube video IDs. :type data: dict

update_matches(data: List[dict]) → None

POST request to update info regarding matches for an event.

Parameters:: data (list[dict]) – List of dictionaries containing information about each match.

update_media(data: List[str]) → None: POST request to update the media for an event. :param data: List of YouTube video IDs to add as media for an event. :type data: list[str]

update_team_list(data: List[str]) → None: POST request to update the team list for an event. :param data: List containing the keys of each team at the event. :type data: list[str]