MCC Event API

Methods

mcc_api.event.get_event(*, timeout: int = 5) → EventInformationResponse

Get event data for the current event cycle.

• Calls the /event endpoint.

• Returns an mcc_api.EventInformationResponse representing the current event cycle’s event.

• May raise a requests.Timeout exception, with the number of seconds before timing out specified by the timeout parameter and defaulting to 5.

mcc_api.event.get_events(*, timeout: int = 5) → EventsResponse

Get all event keys currently made available by the API.

• Calls the `/events <https://api.mcchampionship.com/docs/#/v1/AppController_getEventKeys>_ endpoint.

• Returns an mcc_api.EventsResponse containing all available event keys.

• May raise a requests.Timeout exception, with the number of seconds before timing out specified by the

timeout parameter and defaulting to 5.

mcc_api.event.get_hall_of_fame(*, timeout: int = 5) → HallOfFameResponse

mcc_api.event.get_hall_of_fame(game: Game, *, timeout: int = 5) → HallOfFameGameResponse

Get hall of fame data, optionally restricted to a single game.

When called with no game parameter:

• Calls the /halloffame endpoint.

• Returns a mcc_api.HallOfFameResponse representing the entire Hall of Fame.

When called with a game parameter:

• Calls the /halloffame/{game} endpoint.

• Returns a mcc_api.HallOfFameGameResponse representing a single game from the Hall of Fame.

• May raise an mcc_api.exceptions.InvalidGameError exception, which can be avoided by passing an mcc_api.Game enum.

In either case:

• May raise a requests.Timeout exception, with the number of seconds before timing out specified by the timeout parameter and defaulting to 5.

Warning

The /halloffame endpoint is deprecated and will be removed in a future release of the API. See https://github.com/Noxcrew/mcchampionship-api/releases/tag/v1.3.0

mcc_api.event.get_participant(uuid: str, *, timeout: int = 5) → ParticipantResponse

Get an individual participant in the current event cycle by their Minecraft UUID.

• Accepts both dashed (e.g. 3e7a89ee-c4e2-4392-a317-444b861b0794) and un-dashed (e.g. 3e7a89eec4e24392a317444b861b0794) UUIDs

• Calls the /participant endpoint.

• Returns an mcc_api.ParticipantResponse representing the individual participant in the current event cycle’s event.

• May raise a requests.Timeout exception, with the number of seconds before timing out specified by the timeout parameter and defaulting to 5.

mcc_api.event.get_participants(*, timeout: int = 5) → ParticipantsResponse

mcc_api.event.get_participants(team: Team, *, timeout: int = 5) → ParticipantsTeamResponse

Get the participants in the current event cycle.

When called with no team parameter:

• Calls the /participants endpoint.

• Returns a mcc_api.ParticipantsResponse representing all teams and their participants in the current event cycle.

When called with a team parameter:

• Calls the /participants/{team} endpoint.

• Returns a mcc_api.ParticipantsTeamResponse representing the given team and its participants in the current event cycle.

• May raise an mcc_api.exceptions.InvalidTeamError exception, which can be avoided by passing an mcc_api.Team enum.

In either case:

• May raise a requests.Timeout exception, with the number of seconds before timing out specified by the timeout parameter and defaulting to 5.

mcc_api.event.get_rundown(event: str | None = None, *, timeout: int = 5) → RundownResponse

Get an event’s rundown data.

When called with no event parameter:

• Calls the /rundown endpoint.

• Returns a mcc_api.RundownResponse representing the latest event.

When called with an event parameter:

• Calls the /rundown/{event} endpoint.

• Returns a mcc_api.RundownResponse representing the given event.

• May raise an mcc_api.exceptions.InvalidEventError exception.

In either case:

• May raise a requests.Timeout exception, with the number of seconds before timing out specified by the timeout parameter and defaulting to 5.

Responses

class mcc_api.event.responses.BaseResponse(request: Response | dict[str, Any])

Bases: object

The base response from which all other mcc_api responses inherit.

code: int

Response code of the request from the API.

property json: str

JSON string of the data returned by the API.

reason: str | None

Reason for the response code, if applicable.

class mcc_api.event.responses.Creator(username: str, uuid: str, stream: str, icon: str, team: Team, platform: str)

Bases: object

Detailed data for a given participant.

icon: str

The URL of the icon of the participant.

platform: str

The platform of the participant’s stream.

stream: str

The streaming URL of the participant.

team: Team

The team of the participant.

username: str

The Minecraft username of the participant.

uuid: str

The Minecraft UUID of the participant.

class mcc_api.event.responses.EventInformationData(date: datetime, event: str, updateVideo: str | None)

Bases: object

The current event cycle’s event data.

date: datetime

The date and time at which the event starts.

Stored as an offset-aware datetime object.

event: str

The name of the event.

updateVideo: str | None

The YouTube embed URL of the event’s update video.

class mcc_api.event.responses.EventInformationResponse(request: Response | dict[str, Any])

Bases: BaseResponse

Response object representing the current event cycle’s event.

code: int

Response code of the request from the API.

data: EventInformationData

Current event cycle’s event data.

property json: str

JSON string of the data returned by the API.

reason: str | None

Reason for the response code, if applicable.

class mcc_api.event.responses.EventRundown(dodgeboltData: dict[Team, int], eventPlacements: dict[Team, int], eventScores: dict[Team, int], individualScores: dict[str, int], history: dict[str, RundownHistoryGame], creators: dict[Team, list[str]])

Bases: object

Object representing score, game, and participant data for a single event.

creators: dict[Team, list[str]]

Dictionary mapping teams to lists of their players’ usernames.

dodgeboltData: dict[Team, int]

Dictionary mapping teams in Dodgebolt to the number of rounds of Dodgebolt that they won.

eventPlacements: dict[Team, int]

Dictionary mapping teams to their final placements in the event (zero-indexed).

eventScores: dict[Team, int]

Dictionary mapping teams to their final coins totals.

history: dict[str, RundownHistoryGame]

Dictionary mapping game index to a RundownHistoryGame object (zero-indexed).

Dictionary keys are the number of the game being played as a string. For example:

data = {
    ...
    history: {
        # The first game in the event to be played:
        "0": mcc_api.responses.RundownHistoryGame(...),

        # The second game in the event to be played:
        "1": mcc_api.responses.RundownHistoryGame(...),
        ...
    }
    ...
}

individualScores: dict[str, int]

Dictionary mapping player usernames to their final coins totals.

class mcc_api.event.responses.EventsResponse(request: Response | dict[str, Any])

Bases: BaseResponse

Response object containing all available event keys.

code: int

Response code of the request from the API.

data: list[str]

List of all event keys currently made available by the API.

property json: str

JSON string of the data returned by the API.

reason: str | None

Reason for the response code, if applicable.

class mcc_api.event.responses.HallOfFameGameResponse(request: Response | dict[str, Any])

Bases: BaseResponse

Response object representing a single game from the Hall of Fame.

code: int

Response code of the request from the API.

data: dict[str, HallOfFameRecord]

Dictionary of strings to Hall of Fame records.

Keys in the dictionary are strings that contain the names of the records themselves. For example:

data = {
    "RECORD NAME 1": mcc_api.responses.HallOfFameRecord(
        placement=0,
        player="MCChampionship",
        value="String value",
        changedHands=False
    ),
    "RECORD NAME 2": mcc_api.responses.HallOfFameRecord(
        placement=1,
        player="MCChampionship",
        value=0,
        changedHands=True
    )
}

property json: str

JSON string of the data returned by the API.

reason: str | None

Reason for the response code, if applicable.

class mcc_api.event.responses.HallOfFameRecord(player: str, value: str | int, placement: int, changedHands: bool)

Bases: object

A single record from the Hall of Fame.

Note

The name of the record is not kept within the record, and can instead be found in the HallOfFameResponse or HallOfFameGameResponse objects.

changedHands: bool

Whether the record changed hands in the latest event.

placement: int

The placement value used internally by MCC.live.

player: str

The username of the player that holds the record.

value: str | int

The value of the record.

class mcc_api.event.responses.HallOfFameResponse(request: Response | dict[str, Any])

Bases: BaseResponse

Response object representing the entire Hall of Fame.

code: int

Response code of the request from the API.

data: dict[Game, dict[str, HallOfFameRecord]]

Dictionary of games mapped to dictionaries of strings to Hall of Fame records.

Keys in the inner dictionaries are strings that contain the names of the records themselves. For example:

data = {
    mcc_api.Game.GLOBAL_STATISTICS: {
        "RECORD NAME 1": mcc_api.responses.HallOfFameRecord(
            placement=0,
            player="MCChampionship",
            value="String value",
            changedHands=False
        ),
        "RECORD NAME 2": mcc_api.responses.HallOfFameRecord(
            placement=1,
            player="MCChampionship",
            value=0,
            changedHands=True
        )
    },
    mcc_api.Game.LEGACY_STATISTICS: {
        "RECORD NAME 1": mcc_api.responses.HallOfFameRecord(
            placement=0,
            player="MCChampionship",
            value="String value",
            changedHands=False
        ),
        "RECORD NAME 2": mcc_api.responses.HallOfFameRecord(
            placement=1,
            player="MCChampionship",
            value=0,
            changedHands=True
        )
    }
}

property json: str

JSON string of the data returned by the API.

reason: str | None

Reason for the response code, if applicable.

class mcc_api.event.responses.ParticipantResponse(request: Response | dict[str, Any])

Bases: BaseResponse

Response object representing an individual participant in the current event cycle.

code: int

Response code of the request from the API.

property json: str

JSON string of the data returned by the API.

reason: str | None

Reason for the response code, if applicable.

class mcc_api.event.responses.ParticipantsResponse(request: Response | dict[str, Any])

Bases: BaseResponse

Response object representing all teams and their participants in the current event cycle.

code: int

Response code of the request from the API.

data: dict[Team, list[Creator]]

Dictionary mapping from teams to lists of detailed participant data.

property json: str

JSON string of the data returned by the API.

reason: str | None

Reason for the response code, if applicable.

class mcc_api.event.responses.ParticipantsTeamResponse(request: Response | dict[str, Any])

Bases: BaseResponse

Response object representing a single team and its participants in the current event cycle.

code: int

Response code of the request from the API.

data: list[Creator]

List of detailed participant data.

property json: str

JSON string of the data returned by the API.

reason: str | None

Reason for the response code, if applicable.

class mcc_api.event.responses.RundownHistoryGame(index: int, game: Game, multiplier: float, individualScores: dict[str, int] | None, gameScores: dict[Team, int] | None, eventScores: dict[Team, int] | None, gamePlacements: dict[Team, int] | None, eventPlacements: dict[Team, int] | None)

Bases: object

Object representing score and placement data for a single game from a single event.

eventPlacements: dict[Team, int] | None

Dictionary mapping teams to their placement in the event after this game (zero-indexed).

eventScores: dict[Team, int] | None

Dictionary mapping teams to their total coins after this game.

game: Game

The game that was played.

gamePlacements: dict[Team, int] | None

Dictionary mapping teams to their placement in this game (zero-indexed).

gameScores: dict[Team, int] | None

Dictionary mapping teams to their coins earned during this game (multiplied).

index: int

The number of the game in the event when this was played (zero-indexed).

individualScores: dict[str, int] | None

Dictionary mapping player usernames to their total coins after this game.

multiplier: float

The multiplier applied to coins earned during this game.

class mcc_api.event.responses.RundownResponse(request: Response | dict[str, Any])

Bases: BaseResponse

Response object representing score, game, and participant data for a single event.

code: int

Response code of the request from the API.

data: EventRundown

Object representing the event’s data.

property json: str

JSON string of the data returned by the API.

reason: str | None

Reason for the response code, if applicable.

Enums

class mcc_api.event.enums.Game(*values)

Bases: UpperStrEnum

Game identifiers accepted and returned by the MCC API.

GLOBAL_STATISTICS = 'GLOBAL_STATISTICS'

LEGACY_STATISTICS = 'LEGACY_STATISTICS'

MG_ACE_RACE = 'MG_ACE_RACE'

MG_BATTLE_BOX = 'MG_BATTLE_BOX'

MG_BINGO_BUT_FAST = 'MG_BINGO_BUT_FAST'

MG_BUILD_MART = 'MG_BUILD_MART'

MG_DODGEBOLT = 'MG_DODGEBOLT'

MG_FOOT_RACE = 'MG_FOOT_RACE'

MG_GRID_RUNNERS = 'MG_GRID_RUNNERS'

MG_HOLE_IN_THE_WALL = 'MG_HOLE_IN_THE_WALL'

MG_LOCKOUT_BINGO = 'MG_LOCKOUT_BINGO'

MG_MELTDOWN = 'MG_MELTDOWN'

MG_PARKOUR_TAG = 'MG_PARKOUR_TAG'

MG_PARKOUR_WARRIOR = 'MG_PARKOUR_WARRIOR'

MG_RAILROAD_RUSH = 'MG_RAILROAD_RUSH'

MG_ROCKET_SPLEEF = 'MG_ROCKET_SPLEEF'

MG_ROCKET_SPLEEF_OLD = 'MG_ROCKET_SPLEEF_OLD'

MG_SANDS_OF_TIME = 'MG_SANDS_OF_TIME'

MG_SKYBLOCKLE = 'MG_SKYBLOCKLE'

MG_SKY_BATTLE = 'MG_SKY_BATTLE'

MG_SURVIVAL_GAMES = 'MG_SURVIVAL_GAMES'

MG_TGTTOSAWAF = 'MG_TGTTOSAWAF'

class mcc_api.event.enums.Team(*values)

Bases: UpperStrEnum

Team identifiers accepted and returned by the MCC API.

AQUA = 'AQUA'

BLUE = 'BLUE'

CYAN = 'CYAN'

GREEN = 'GREEN'

LIME = 'LIME'

NONE = 'NONE'

ORANGE = 'ORANGE'

PINK = 'PINK'

PURPLE = 'PURPLE'

RED = 'RED'

SPECTATORS = 'SPECTATORS'

YELLOW = 'YELLOW'

class mcc_api.event.enums.UpperStrEnum(new_class_name, /, names, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: Enum

Custom Enum class that acts like enum.StrEnum, using uppercase strings.

Exceptions

exception mcc_api.event.exceptions.InvalidEventError(code: int, reason: str | None)

Bases: MCCAPIError

Exception raised when the requested event does not exist.

exception mcc_api.event.exceptions.InvalidGameError(code: int, reason: str | None)

Bases: MCCAPIError

Exception raised when the requested game does not exist.

exception mcc_api.event.exceptions.InvalidParticipantError(code: int, reason: str | None)

Bases: MCCAPIError

Exception raised when the requested participant does not exist.

exception mcc_api.event.exceptions.InvalidTeamError(code: int, reason: str | None)

Bases: MCCAPIError

Exception raised when the requested team does not exist.

exception mcc_api.event.exceptions.MCCAPIError(code: int, reason: str | None)

Bases: BaseException

The base exception from which all other mcc_api exceptions inherit.

code: int

Response code of the request from the API.

reason: str | None

Reason for the response code, if applicable.

exception mcc_api.event.exceptions.RateLimitError(code: int, reason: str | None)

Bases: MCCAPIError

Exception raised when the MCC API returns a rate limit error.