API Reference

The following section outlines the API of rlapi.

Note

This module uses the Python logging module to log diagnostic and errors in an output independent way. If the logging module is not configured, these logs will not be output anywhere.

Platform Player IDs

The API requires certain identifiers to be used when looking up the names on each platform:

Lookup identifiers per platform
Platform name	Lookup by ID	Lookup by name
Steam	Supported SteamID (also known as steamID64)	Not recommended API matches the given name against non-unique display names cached by Rocket League’s database. Note: This identifier is omitted by `Client.find_player()`.
Epic Games	Supported Epic Account ID	Supported Epic Account display name Note: This is unique but may change over time.
PlayStation	Supported PSN Account ID (not exposed by PSN / RL API)	Supported PSN username (Online ID) Note: This is unique but may change over time.
Xbox One	Supported Xbox services ID (XUID) (not exposed by Xbox network / RL API)	Supported Xbox Gamertag Note: This is unique but may change over time.
Nintendo Switch	Unsupported by the API	Not recommended Nintendo Nickname Note: The nicknames are not unique, it’s recommended to use the linked Epic account instead.

Client

class rlapi.Client(*, client_id, client_secret, tier_breakdown=None)[source]

await close()[source]

Close underlying session.

Release all acquired resources.

destroy()[source]

Detach underlying session.

The close() method should be used instead when possible as this function does not close the session’s connector.

update_client_credentials(*, client_id, client_secret)[source]

Update client ID and client secret.

Parameters

client_id (str) – New client ID.
client_secret (str) – New client secret.

await get_player_by_id(platform, id_, /)[source]

Get player profile on the given platform matching the specified ID.

See Platform Player IDs section for supported lookup identifiers.

Parameters

id (str) – ID of player to find.

Returns

Requested player profile.

Return type

Player

Raises

HTTPException – HTTP request to Rocket League failed.
PlayerNotFound – The player could not be found.

await get_player_by_name(platform, name, /)[source]

Get player profile on the given platform matching the specified name.

See Platform Player IDs section for supported lookup identifiers.

Parameters

name (str) – Display name of player to find.

Returns

Requested player profile.

Return type

Player

Raises

HTTPException – HTTP request to Rocket League failed.
PlayerNotFound – The player could not be found.

await find_player(player_id, /)[source]

Get player profiles for given player ID by searching in all platforms.

See Platform Player IDs section for supported lookup identifiers.

Parameters

player_id (str) – ID of player to find.

Returns

Requested player profiles.

Return type

list of Player

Raises

HTTPException – HTTP request to Rocket League or Steam API failed.
PlayerNotFound – The player could not be found on any platform.

get_players(platform, *, ids=(), names=())[source]

Get an asynchronous iterable of player profiles for given player IDs and names on the selected platform.

See Platform Player IDs section for supported lookup identifiers.

Note

This function will not raise when any of the given IDs/names could not be found and will simply not include them in the results. It isn’t possible to easily map the returned players to given names (if any) and thus it’s also not easily possible to determine which (if any) names are missing (and whether any identifiers were duplicated in the parameters).

Parameters

platform (Platform) – Platform to search.
ids (str) – IDs of the players to find. This can be used on all platforms provided that you know the ID but the API only returns it for Steam and Epic and therefore you’ll probably be limited to using it on those two platforms.
names (str) –
Names of the players to find.

This can be used on all platforms and does some kind of equality check on display names, ignoring case-sensitivity and other undocumented things such as some kind of accent-sensitivity.

The above means that, for some platforms, you simply can’t lookup some players by name because the query could sometimes be fulfilled by multiple players. This is mainly a problem for Epic Games, and Nintendo Switch platforms. It is also not recommended to use this lookup method for Steam since the SteamID is easily available on this platform and display names are not unique.

Yields

Player – The requested player profile. The order the player profiles are yielded in should not be depended on.

Raises

HTTPException – HTTP request to Rocket League API failed.

await get_player_titles(platform, player_id)[source]

Get player’s titles.

Note

Some titles that the player has may not be included in the response.

Parameters

platform (Platform) – Platform to lookup the player on.
player_id (str) – Identifier to lookup the player by. This needs to be a user ID for the Steam and Epic platforms and a name for the rest of the platforms.

Returns

List of player’s titles.

Return type

list of PlayerTitle

Raises

HTTPException – HTTP request to Rocket League failed.

await get_population()[source]

Get population across different platforms and playlists.

Returns: Player population across different platforms and playlists.
Return type: Population
Raises: HTTPException – HTTP request to Rocket League failed.

await get_skill_leaderboard(platform, playlist_key)[source]

Get skill leaderboard for the playlist on the given platform.

Parameters

platform (Platform) – Platform to get the leaderboard for.
playlist_key (PlaylistKey) – Playlist to get the leaderboard for.

Returns

Skill leaderboard for the playlist on the given platform.

Return type

SkillLeaderboard

Raises

HTTPException – HTTP request to Rocket League failed.

await get_stat_leaderboard(platform, stat)[source]

Get leaderboard for the specified stat on the given platform.

Parameters

platform (Platform) – Platform to get the leaderboard for.
stat (Stat) – Stat to get the leaderboard for.

Returns

Leaderboard for the specified stat on the given platform.

Return type

StatLeaderboard

Raises

HTTPException – HTTP request to Rocket League failed.

Enumerations

The API provides some enumerations for certain types of string to avoid the API from being stringly typed in case the strings change in the future.

All enumerations are subclasses of enum.Enum.

class rlapi.PlaylistKey(value)[source]

Represents playlist’s key.

str(x)

Returns playlist’s friendly name, e.g. “Solo Duel”

This is only provided in the English language.

solo_duel = 10: The Solo Duel playlist.

doubles = 11: The Doubles playlist.

standard = 13: The Standard playlist.

hoops = 27: The Hoops playlist.

rumble = 28: The Rumble playlist.

dropshot = 29: The Dropshot playlist.

snow_day = 30: The Snow Day playlist.

tournaments = 34: The Tournaments “playlist”. This is used to determine the rank for automatic tournaments.

class rlapi.Platform(value)[source]

Represents player’s platform.

str(x): Returns platform’s friendly name, e.g. “Xbox One”

steam = 'Steam': The Steam platform.

ps4 = 'PS4': The PlayStation platform.

xboxone = 'XboxOne': The Xbox One platform.

epic = 'Epic': The Epic Games platform.

switch = 'Switch': The Nintendo Switch platform.

class rlapi.Stat(value)[source]

Represents player stat.

assists = 'Assists': Assists.

goals = 'Goals': Goals.

mvps = 'MVPs': MVPs.

saves = 'Saves': Saves.

shots = 'Shots': Shots.

wins = 'Wins': Wins.

Rocket League API Models

Models are classes that are received from Rocket League API and are not meant to be created by the user of the library.

class rlapi.Player[source]

Represents Rocket League Player

platform

Player’s platform.

Type: Platform

user_id

Player’s user ID. Present when the data was looked up by user ID or when the lookup platform was Steam or Epic Games.

Type: str, optional

user_name

Player’s username (display name).

Type: str

playlists

Dictionary mapping PlaylistKey with Playlist.

Type: dict

tier_breakdown

Tier breakdown.

Type: dict

highest_tier

Highest tier of the player. Doesn’t include the playlists that don’t count towards season rewards.

Type: int

season_rewards

Season rewards info.

Type: SeasonRewards

stats

Player’s stats (assists, goals, MVPs, etc.).

Type: PlayerStats

await titles()[source]

Get player’s titles.

Note

Some titles that the player has may not be included in the response.

Returns: List of player’s titles.
Return type: list of PlayerTitle
Raises: HTTPException – HTTP request to Rocket League failed.

get_playlist(playlist_key)[source]

Get playlist for the player.

Parameters: playlist_key (PlaylistKey) – PlaylistKey for playlist to get.
Returns: Playlist object for provided playlist key.
Return type: Playlist, optional

class rlapi.PlayerStats[source]

Represents player stats (assists, goals, MVPs, etc.).

x[key]: Lookup player’s stat value by Stat enum.

assists

Number of player’s assists.

Type: int

goals

Number of player’s goals.

Type: int

mvps

Number of player’s MVPs.

Type: int

saves

Number of player’s saves.

Type: int

shots

Number of player’s shots.

Type: int

wins

Number of player’s wins.

Type: int

class rlapi.SeasonRewards[source]

Represents season rewards informations.

level

Player’s season reward level.

Type: int

wins

Player’s season reward wins.

Type: int

can_advance

Tells if player can advance to next_level.

Type: bool

next_level

Next level of season rewards or None if max level has already been reached.

Type: int, optional

MAX_LEVEL = 8: Max season reward level, i.e. Supersonic Legend

class rlapi.Playlist[source]

Represents Rocket League playlist stats data.

str(x)

Returns playlist’s rank string, e.g. “Champion I Div III”.

This is only provided in the English language.

key

Playlist’s key. Might be int, if that key is not within the ones recognised by the enumerator.

Type: PlaylistKey or int

tier

Tier on this playlist.

Type: int

division

Division on this playlist.

Type: int

mu

Mu on this playlist.

Type: float

skill

Skill rating on this playlist.

Type: int

sigma

Sigma on this playlist.

Type: float

win_streak

Win streak on this playlist.

Type: int

matches_played

Number of matches played on this playlist during the current season.

Type: int

lifetime_matches_played

Number of matches played on this playlist since player started playing the game.

Note

This number does not seem to include some of the earlier seasons. It is estimated that it include all matches played in Season 4 (before Free To Play update) and later.

Type: int

placement_matches_played

Number of placement matches played on this playlist during the current season. Maxes out at 10.

Type: int

breakdown

Playlist tier breakdown.

Type: dict

tier_estimates

Tier estimates for this playlist.

Type: TierEstimates

TIER_MAX = 22: Max tier, i.e. Supersonic Legend

DIVISION_MAX = 3: Max division, i.e. Division IV

class rlapi.PlayerTitle[source]

Represents Rocket League player title.

id

Title’s ID.

Type: str

property name

The English name of the title, as shown in the game.

For tournament winner rewards, the following strings are used where rank images should be rendered:

{{BRONZE}} - Bronze
{{SILVER}} - Silver
{{GOLD}} - Gold
{{PLATINUM}} - Platinum
{{DIAMOND}} - Diamond
{{CHAMPION}} - Champion
{{GRANDCHAMPION}} - Grand Champion
{{SUPERSONICLEGEND}} - Supersonic Legend

Note

This is not provided by the API itself and is generated by the library using a bunch of rules and special cases based on the title’s ID. It may not remain accurate as the time goes by without updating the library.

class rlapi.SkillLeaderboard[source]

Represents Rocket League playlist’s skill leaderboard for a single platform.

platform

Platform that this leaderboard refers to.

Type: Platform

playlist_key

Playlist that this leaderboard refers to.

Type: PlaylistKey

players

List of playlist’s top 100 players on the platform.

Type: list of StatLeaderboardPlayer

class rlapi.SkillLeaderboardPlayer[source]

Represents Rocket League Player on a platform’s skill leaderboard.

platform

Platform that this leaderboard entry refers to.

Type: Platform

playlist_key

Playlist that this leaderboard entry refers to.

Type: PlaylistKey

user_id

Player’s user ID. Only present for Steam and Epic Games players.

Type: str, optional

user_name

Player’s username (display name).

Type: str

tier

Player’s tier on the specified playlist.

Type: int

skill

Player’s skill rating on the specified playlist.

Type: int

class rlapi.StatLeaderboard[source]

Represents Rocket League stat leaderboard for a single platform.

platform

Platform that this leaderboard refers to.

Type: Platform

stat

Stat that this leaderboard refers to.

Type: Stat

players

List of stat’s top 100 players on the platform.

Type: list of StatLeaderboardPlayer

class rlapi.StatLeaderboardPlayer[source]

Represents Rocket League Player on a platform’s stat leaderboard.

platform

Platform that this leaderboard entry refers to.

Type: Platform

stat

Stat that this leaderboard entry refers to.

Type: Stat

user_id

Player’s user ID. Only present for Steam and Epic Games players.

Type: str, optional

user_name

Player’s username (display name).

Type: str

value

Value of the specified stat for the player.

Type: int

class rlapi.Population[source]

Describes Rocket League’s population across all platforms.

playlists

Mapping of playlist IDs (int) to their population (PlaylistPopulation). For ranked playlists, it is possible to do a lookup by their PlaylistKey.

Type: dict

property num_players: Total number of players who are currently online on all platforms and playlists.

class rlapi.PlaylistPopulation[source]

Describes population of a Rocket League playlist.

playlist

Playlist that this instance refers to. If the playlist is known, this will use a constant value with additional information.

Type: PopulationPlaylist

platforms

Mapping of platforms (Platform) to their number of online players (int) for this playlist.

Type: dict

property num_players: Total number of players who are currently online on this playlist across all platforms.

class rlapi.PopulationPlaylist[source]

Describes a Rocket League playlist that may be returned by population endpoint.

When is_known is False, only the ID will be filled with the right value.

id

Playlist’s ID. For ranked playlists, this is consistent with PlaylistKey.

Type: int

title

Playlist’s title. When is_known is False, this will be set to “Unknown”.

Type: str

description

Playlist’s description, if available.

Type: str, optional

player_count

Number of players that the match in this playlist can have in total.

None if the value is not fixed.

1 if the playlist is not a match (e.g. Main Menu, Training, etc.).

Type: int

ranked

Indicates whether the playlist is ranked.

Type: bool

online

Indicates whether the playlist is online.

Type: bool

private

Indicates whether the match is private or if matchmaking was involved.

Type: bool

is_ltm

Indicates whether the playlist is a Limited Time Mode (LTM).

Type: bool

is_known

Indicates whether the playlist is known to this library. When this is False, all fields except for id will not have the right values.

Type: bool

class rlapi.tier_estimates.TierEstimates[source]

Represents Rocket League playlist’s tier estimates.

playlist

Playlist object which these estimates are about.

Type: rlapi.Playlist

tier

Estimated tier on this playlist.

Type: int

division

Estimated division on this playlist.

Type: int

div_down

Estimated amount of points for player to go a division down.

Type: int, optional

div_up

Estimated amount of points for player to go a division up.

Type: int, optional

tier_down

Estimated amount of points for player to go a tier down.

Type: int, optional

tier_up

Estimated amount of points for player to go a tier up.

Type: int, optional

Useful Constants

The package provides a few constants that can be useful when interpreting data from the API.

rlapi.RANKS = ('Unranked', 'Bronze I', ..., 'Supersonic Legend')

A sequence of rank names, indexed by the value of Playlist.tier.

Rank names are only provided in the English language.

rlapi.DIVISIONS = ('I', 'II', 'III', 'IV'): A sequence of roman numerals for divisions, indexed by the value of Playlist.division.

rlapi.SEASON_REWARDS = ('Unranked', 'Bronze', 'Silver', ..., 'Supersonic Legend')

A sequence of season reward level names, indexed by the value of SeasonRewards.level.

Season reward level names are only provided in the English language.

rlapi.PLAYLISTS_WITH_SEASON_REWARDS = (PlaylistKey.solo_duel, PlaylistKey.doubles, ..., PlaylistKey.snow_day): A sequence of playlists that can advance player’s season rewards.

rlapi.KNOWN_POPULATION_PLAYLISTS = {0: <PopulationPlaylist Main Menu (0) player_count=1>, ...}: A mapping of known population playlist IDs to their rlapi.PopulationPlaylist objects.

Exceptions

The following exceptions are thrown by the library.

exception rlapi.errors.RLApiException[source]

Bases: Exception

Base exception class for Rocket League API.

exception rlapi.errors.IllegalUsername[source]

Bases: rlapi.errors.RLApiException

Username has unallowed characters.

exception rlapi.errors.PlayerNotFound[source]

Bases: rlapi.errors.RLApiException

Username could not be found.

exception rlapi.errors.HTTPException(response, data)[source]

Bases: rlapi.errors.RLApiException

Exception that’s thrown when an HTTP request operation fails.

response

The response of the failed HTTP request.

Type: aiohttp.ClientResponse

status

The status code of the HTTP request.

Type: int

message

Details about error.

Type: Union[str, dict]

exception rlapi.errors.Unauthorized(response, data)[source]

Bases: rlapi.errors.HTTPException

Exception that’s thrown when status code 401 occurs.