PaladinsAPI

class arez.PaladinsAPI(dev_id, auth_key, *, cache=True, initialize=False, loop=None)

The main Paladins API.

Inherits from DataCache.

Note

You can request your developer ID and authorization key here.

Note

In addition to the exceptions specified for each method, each API request can result in the following exceptions being raised:

Unavailable

The API is currently unavailable.

LimitReached

Your daily limit of requests has been reached.

HTTPException

Fetching the information requested failed due to connection or API problems.

Parameters

• dev_id (int | str) – Your developer’s ID (devId).

• auth_key (str) – Your developer’s authentication key (authKey).

• cache (bool) –

  When set to False, this disables the data cache. This makes most objects returned from the API be CacheObject instead of their respective data-rich counterparts.

  Defaults to True.

• initialize (bool | Language) –

  When set to True, it launches a task that will initialize the cache with the default (English) language.

  Can be set to a Language instance, in which case that language will be set as default first, before initializing.

  Defaults to False, where no initialization occurs.

• loop (asyncio.AbstractEventLoop | None) –

  The event loop you want to use for this API.

  Default loop is used when not provided.

await close()

Closes the underlying API connection, and stops the server status checking loop (see register_status_callback).

Attempting to make a request after the connection is closed will result in a RuntimeError.

await get_data_used()

Allows you to check API usage statistics.

Returns

An object describing API usage.

Return type

DataUsed

await get_server_status(*, force_refresh=False)

Fetches the server status.

To preserve requests, the status returned is cached once every minute. Use the force_refresh parameter to override this behavior.

Uses up one request each time the cache is refreshed.

Parameters

force_refresh (bool) –

Bypasses the cache, forcing a fetch and returning a new object.

Defaults to False.

Returns

The server status object.

Return type

ServerStatus

Raises

NotFound – There was no cached status and fetching has failed.

register_status_callback(callback, check_interval=datetime.timedelta(seconds=180), recheck_interval=datetime.timedelta(seconds=60))

Registers a callback function, that will periodically check the status of the servers, every check_interval specified. If the status changes, the callback function will then be called with the new status (and optionally the previous one) passed as the arguments, like so: callback(after) or callback(before, after).

This can be used to easily setup server status monitoring and notifications systems:

api: arez.PaladinsAPI  # wrapper instance

async def notify(after: arez.ServerStatus):
    # do anything when the status changes - in this case, just print a message
    print(f"Current server status: {after.status}")

api.register_status_callback(notify)

Note

• The checking loop will call get_server_status with force_refresh set to True, to handle the refreshing. To avoid wasting request, it’s recommended to use intervals at least 1 minute long, and not set force_refresh to True anywhere else in your code, relying on the cached status being refreshed by the loop.

• The callback is wrapped inside a task, to prevent it from delaying the checking loop. Please make sure that it’s execution time is shorter than the check / recheck intervals, otherwise you may end up with two callbacks running at once.

• Any exceptions raised by the callback function, will be logged by the library’s logger, and ultimately ignored otherwise. If you’d be interested in those, try either catching and processing those yourself (within the callback), or hooking up a logger handler and setting the logger to at least ERROR level.

Parameters

• callback (Callable[[ServerStatus], Any] | Callable[[ServerStatus, ServerStatus], Any]] | None) –

  The callback function you want to register. This can be either a normal function or an async one, accepting either 1 or 2 positional arguments, with any return type.

  Passing a new callback function, while one is already running, will overwrite the previous one and reset the timer.

  Passing None removes the callback and stops the checking loop.

• check_interval (timedelta) –

  The length of the interval used between Operational (all servers up, no limited access, not including PTS) server status checks.

  The default check interval is 3 minutes.

• recheck_interval (timedelta) –

  The length of the interval used between non-Operational (at least one server is down, or limited access, not including PTS) server status checks.

  The default recheck interval is 1 minute.

Raises

• TypeError – The callback passed was not a function.

• ValueError – The callback passed had an incorrect number (or types) of its parameters.

await get_champion_info(language=None, *, force_refresh=False, cache=None)

Fetches the champions, talents, cards, shop items and skins information.

To preserve requests, the information returned is cached once every 12 hours. Use the force_refresh parameter to override this behavior.

Uses up three requests each time the cache is refreshed, per language.

Parameters

• language (Language | None) –

  The Language you want to fetch the information in.

  Default language is used if not provided.

• force_refresh (bool) –

  Bypasses the cache, forcing a fetch and returning a new object.

  Defaults to False.

• cache (bool | None) –

  Lets you decide if the received information should be cached or not.

  Setting this to True forces the object to be cached, even when the cache is disabled.

  Setting this to False will never cache the object.

  Default behavior (None) follows the cache existence setting.

Returns

An object containing all champions, cards, talents, shop items and skins information, in the chosen language.

Return type

CacheEntry

Raises

NotFound – The champion information wasn’t available on the server.

wrap_player(player_id, player_name='', platform=0, private=False)

Wraps player ID, Name and Platform into a PartialPlayer object.

Warning

Note that since there is no input validation, there’s no guarantee an object created this way will return any meaningful results when it’s methods are used. This method is here purely for those who’d like to store player objects in something like a database, offering the possibility of re-wrapping the stored data back into a valid player object.

This should not be used to fetch stats for players based on their ID - use get_player for this purpose instead.

Parameters

• player_id (int) – The player ID you want to get the object for.

• player_name (str) –

  The player Name you want the object to have.

  Defaults to an empty string.

• platform (str | int) –

  The platform you want the object to have.

  Defaults to Platform.Unknown.

• private (bool) –

  A boolean flag indicating if this profile should be considered private or not.

  Defaults to False.

Returns

The wrapped player object.

Return type

PartialPlayer

await get_player(player, *, return_private=False)

Fetches a Player object for the given player ID or player name.

Only players with Platform.PC, Platform.Steam and Platform.Discord platforms (PC players) will be returned when using this method with player name as input. For player ID inputs, players from all platforms will be returned.

Uses up a single request.

Parameters

• player (int | str) – Player ID or player name of the player you want to get object for.

• return_private (bool) –

  When set to True and the requested profile is determined private, this method will return a PartialPlayer object with the player ID and privacy flag set.

  When set to False, the Private exception will be raised instead.

  Defaults to False.

Returns

An object containing stats information about the player requested.

PartialPlayer objects are only returned for private profiles and appropriate arguments used.

Return type

Player | PartialPlayer

Raises

• NotFound – The player’s profile doesn’t exist / couldn’t be found.

• Private – The player’s profile was private.

await get_players(player_ids, *, return_private=False)

Fetches multiple players in a batch, and returns their list. Removes duplicates.

Uses up a single request for every multiple of 20 unique player IDs passed.

Parameters

• player_ids (Iterable[int]) – An iterable of player IDs you want to fetch.

• return_private (bool) –

  When set to True and one of the requested profiles is determined private, this method will return a PartialPlayer object with the player ID and privacy flag set.

  When set to False, private profiles are omitted from the output list.

  Defaults to False.

Returns

A list of players requested.

PartialPlayer objects are only returned for private profiles and appropriate arguments used. Some players might not be included in the output if they weren’t found, or their profile was private.

Return type

list[Player | PartialPlayer]

await search_players(player_name, platform=None, *, return_private=True, exact=True)

Fetches all players whose name matches the name specified. The search is fuzzy - player name capitalisation doesn’t matter.

Uses up a single request.

Note

Searching on all platforms will limit the number of players returned to ~500. Specifying a particular platform does not have this limitation.

Parameters

• player_name (str) – Player name you want to search for.

• platform (Platform | None) –

  Platform you want to limit the search to.

  Specifying None will search on all platforms.

  Defaults to None.

• return_private (bool) –

  When set to True and one of the requested profiles is determined private, this method will return a PartialPlayer object with the player ID and privacy flag set.

  When set to False, private profiles are omitted from the output list.

  Defaults to True.

• exact (bool) –

  When set to True, only players whose name matches exactly the name provided, will be returned.

  When set to False, exact matches will be returned first, followed by players whose name starts with the privided string.

  Defaults to True.

  Warning

  Settings this to False will limit the number of players returned to ~500.

Returns

A list of players whose name (and optionally platform) matches the specified name.

Note that some of them might be set as private, unless appropriate input parameters were used.

Return type

list[PartialPlayer]

Raises

NotFound – There was no player for the given name (and optional platform) found.

await get_from_platform(platform_id, platform)

Fetches a PartialPlayer linked with the platform ID specified.

Note

This method doesn’t set the PartialPlayer.name attribute, meaning that it will remain as an empty string. This is a limitation of the Hi-Rez API, not the library.

Uses up a single request.

Parameters

• platform_id (int) –

  The platform-specific ID of the linked player.

  This is usually a Hi-Rez account ID, SteamID64, Discord User ID, etc.

• platform (Platform) – The platform this ID is for.

Returns

The player this platform ID is linked to.

Return type

PartialPlayer

Raises

NotFound – The linked profile doesn’t exist / couldn’t be found.

get_entry(language=None)

Returns a cache entry for the given language specified.

Note

This method can return None or stale data if the entry hasn’t been fetched yet, or haven’t been updated in a while.

Consider using the get_champion_info method from the main API instead.

Parameters

language (Language | None) –

The Language you want to get the entry in.

Default language is used if not provided.

Returns

The cache entry you requested.

None is returned if the entry for the language specified hasn’t been fetched yet.

Return type

CacheEntry | None

await get_match(match_id, language=None, *, expand_players=False)

Fetches a match for the given Match ID.

Uses up a single request.

Parameters

• match_id (int) – Match ID you want to get a match for.

• language (Language | None) –

  The Language you want to fetch the information in.

  Default language is used if not provided.

• expand_players (bool) –

  When set to True, partial player objects in the returned match object will automatically be expanded into full Player objects, if possible.

  Uses an addtional request to do the expansion.

  Defaults to False.

Returns

A match for the ID specified.

Return type

Match

Raises

NotFound – The match wasn’t available on the server. This can happen if the match is older than 30 days, or is currently in progress.

await initialize(*, language=None)

Initializes the data cache, by pre-fetching and storing the CacheEntry for the default language currently set.

Note

This will both, force the champion information fetching, as well as cache the resulting object.

Parameters

language (Language | None) –

The Language you want to initialize the information for.

Default language is used if not provided.

Returns

True if the initialization succeeded without problems, False otherwise.

Return type

bool

await request(method_name, /, *data)

Makes a direct request to the HiRez API.

For all methods available (and their parameters), please see Hi-Rez API docs.

Parameters

• method_name (str) – The name of the method requested. This shouldn’t include the reponse type as it’s added for you.

• *data (int | str) – Method parameters requested to add at the end of the request, if applicable. These should be either integers or strings.

Returns

A raw server’s response as a string, list or a dictionary (depending on the endpoint).

Return type

str | dict[str, Any] | list[dict[str, Any]]

Raises

• HTTPException – Whenever it was impossible to fetch the data in a reliable manner. Check the HTTPException.cause attribute for the original exception (and reason) that lead to this.

• Unauthorized – When the developer’s ID (devId) or the developer’s authentication key (authKey) are deemed invalid.

• Unavailable – When the Hi-Rez API switches to emergency mode, and no data could be returned at this time.

• LimitReached – Your daily limit of requests has been reached.

set_default_language(language)

Sets the default language used by the cache in places where one is not provided by the user.

The default language set is Language.English.

Parameters

language (Language) – The new default language you want to set.

await get_matches(match_ids, language=None, *, expand_players=False)

Fetches multiple matches in a batch, for the given Match IDs. Removes duplicates.

Uses up a single request for every multiple of 10 unique match IDs passed.

Parameters

• match_ids (Iterable[int]) – An iterable of Match IDs you want to fetch.

• language (Language | None) –

  The Language you want to fetch the information in.

  Default language is used if not provided.

• expand_players (bool) –

  When set to True, partial player objects in the returned match objects will automatically be expanded into full Player objects, if possible.

  Uses an addtional request for every 20 unique players to do the expansion.

  Defaults to False.

Returns

A list of the available matches requested.

Some of the matches can be not present if they weren’t available on the server.

Return type

list[Match]

async for ... in get_matches_for_queue(queue, *, start, end, language=None, region=None, reverse=False, local_time=False, expand_players=False)

Creates an async generator that lets you iterate over all matches played in a particular queue, between the timestamps provided.

Uses up a single request for every:

• multiple of 10 matches fetched, according to the following points

• 1 day worth of matches fetched, between midnights

• 1 hour worth of matches fetched, between round hours

• 10 minutes worth of matches fetched, between round 10 minutes intervals

Depending on the timestamps provided, the longest possible fetching interval is used.

Note

To avoid wasting requests, it’s recommended to invoke this generator with timestamps representing at least 10 minutes long interval, rounded to the nearest multiple of 10 minutes. Being more granular will still work, and only return matches that fit within the interval specified though.

Note

Both naive and aware objects are supported for the timestamps. Aware objects will be internally converted to UTC according to their timezone. Naive objects are assumed to represent UTC time already, unless the local_time argument is used.

Parameters

• queue (Queue) – The Queue you want to fetch the matches for.

• language (Language | None) –

  The Language you want to fetch the information in.

  Default language is used if not provided.

• region (Region | None) –

  The Region to filter the returned matches to.

  None means that no filtering is done.

• start (datetime.datetime) – A timestamp indicating the starting point of a time slice you want to fetch the matches in.

• end (datetime.datetime) – A timestamp indicating the ending point of a time slice you want to fetch the matches in.

• reverse (bool) –

  Reverses the order of the matches being returned.

  Defaults to False.

• local_time (bool) –

  When set to True, the timestamps provided are assumed to represent the local system time (in your local timezone), and will be converted to UTC before processing.

  When set to False, the timestamps provided are assumed to already represent UTC and no conversion will occur.

  Defaults to False.

• expand_players (bool) –

  When set to True, partial player objects in the returned match object will automatically be expanded into full Player objects, if possible.

  Uses an addtional request for every 20 unique players to do the expansion.

  Defaults to False.

Returns

An async generator yielding matches played in the queue specified, between the timestamps specified, optionally filtered to the region specified.

Return type

AsyncGenerator[Match, None]

await get_bounty(*, language=None)

Returns a 2-item tuple denoting the (active, past) bounty store items, sorted by their expiration time.

Parameters

language (Language | None) –

The Language you want to fetch the information in.

Default language is used if not provided.

Returns

An tuple containing a list of active bounty store items, followed by a list of items that have already expired.

Return type

tuple[list[BountyItem], list[BountyItem]]

Raises

NotFound – No bounty items were returned. This can happen if the bounty store is unavailable for a long time.