Module aoe2netwrapper
aoe2netwrapper library
aoe2netwrapper is a utility library, written in Python 3, that provides high level clients to query the APIs provided by aoe2.net, and get data about the Age of Empires II video game.
View Source
"""
aoe2netwrapper library
----------------------
aoe2netwrapper is a utility library, written in Python 3, that provides high level clients to
query the APIs provided by aoe2.net, and get data about the Age of Empires II video game.
:copyright: (c) 2021 by Felix Soubelet.
:license: MIT, see LICENSE file for more details.
"""
from .api import AoE2NetAPI # noqa: TID252
from .nightbot import AoE2NightbotAPI # noqa: TID252
__version__ = "0.4.0"
__all__ = ["AoE2NetAPI", "AoE2NightbotAPI"]
Sub-modules
- aoe2netwrapper.api
- aoe2netwrapper.converters
- aoe2netwrapper.exceptions
- aoe2netwrapper.models
- aoe2netwrapper.nightbot
Classes
AoE2NetAPI
class AoE2NetAPI(
timeout: 'float | tuple[float, float]' = 5
)
The 'AoE2NetAPI' class is a client that encompasses the https://aoe2.net/#api API endpoints.
Each method in this class corresponds name for name to an endpoint, and will do the work in querying then parsing and validating the response before returning it.
View Source
class AoE2NetAPI:
"""
The 'AoE2NetAPI' class is a client that encompasses the https://aoe2.net/#api API endpoints.
Each method in this class corresponds name for name to an endpoint, and will do the work in querying then
parsing and validating the response before returning it.
"""
_API_BASE_URL: str = "https://aoe2.net/api"
_STRINGS_ENDPOINT: str = _API_BASE_URL + "/strings"
_LEADERBOARD_ENDPOINT: str = _API_BASE_URL + "/leaderboard"
_LOBBIES_ENDPOINT: str = _API_BASE_URL + "/lobbies"
_LAST_MATCH_ENDPOINT: str = _API_BASE_URL + "/player/lastmatch"
_MATCH_HISTORY_ENDPOINT: str = _API_BASE_URL + "/player/matches"
_RATING_HISTORY_ENDPOINT: str = _API_BASE_URL + "/player/ratinghistory"
_MATCHES_ENDPOINT: str = _API_BASE_URL + "/matches"
_MATCH_ENDPOINT: str = _API_BASE_URL + "/match"
_NUMBER_ONLINE_ENDPOINT: str = _API_BASE_URL + "/stats/players"
def __init__(self, timeout: float | tuple[float, float] = 5):
"""Creating a Session for connection pooling since we're always querying the same host."""
self.session = requests.Session()
self.timeout = timeout
def __repr__(self) -> str:
return f"Client for <{self._API_BASE_URL}>"
def strings(self, game: str = "aoe2de") -> StringsResponse:
"""
Requests a list of strings used by the API.
Args:
game (str): The game for which to extract the list of strings. Defaults to 'aoe2de'.
Possibilities are 'aoe2hd' (Age of Empires 2: HD Edition) and 'aoe2de' (Age of
Empires 2: Definitive Edition).
Returns:
A StringsResponse validated object encapsulating the strings used by the API.
"""
logger.debug("Preparing parameters for strings query")
query_params = {"game": game}
processed_response = _get_request_response_json(
session=self.session,
url=self._STRINGS_ENDPOINT,
params=query_params,
timeout=self.timeout,
)
logger.trace(f"Validating response from '{self._STRINGS_ENDPOINT}'")
return StringsResponse(**processed_response)
def leaderboard(
self,
game: str = "aoe2de",
leaderboard_id: int = 3,
start: int = 1,
count: int = 10,
search: str | None = None,
steam_id: int | None = None,
profile_id: int | None = None,
) -> LeaderBoardResponse:
"""
Request the current leaderboards.
Args:
game (str): The game for which to extract the list of strings. Defaults to 'aoe2de'.
Possibilities are 'aoe2hd' (Age of Empires 2: HD Edition) and 'aoe2de' (Age of
Empires 2: Definitive Edition).
leaderboard_id (int): Leaderboard to extract the data for (Unranked=0,
1v1 Deathmatch=1, Team Deathmatch=2, 1v1 Random Map=3, Team Random Map=4).
Defaults to 3.
start (int): Starting rank (ignored if search, steam_id, or profile_id are defined).
Defaults to 1.
count (int): Number of leaderboard entries to get (warning: must be 10000 or less).
Defaults to 10.
search (str): Optional. To perform the search for a specific player, from their name.
steam_id (int): Optional. To perform the search for a specific player, from their
steamID64 (ex: 76561199003184910).
profile_id (int): Optional. To perform the search for a specific player, from their
profile ID (ex: 459658).
Raises:
Aoe2NetError: if the 'count' parameter exceeds 10 000.
Returns:
A LeaderBoardResponse validated object with the different parameters used for the
query, the total amount of hits, and the leaderboard as a list profile entries for
each ranking.
"""
if count > _MAX_LEADERBOARD_COUNT:
logger.error(f"'count' has to be 10000 or less, but {count} was provided.")
msg = "Invalid value for parameter 'count'."
raise Aoe2NetError(msg)
logger.debug("Preparing parameters for leaderboard query")
query_params = {
"game": game,
"leaderboard_id": leaderboard_id,
"start": start,
"count": count,
"search": search,
"steam_id": steam_id,
"profile_id": profile_id,
}
processed_response = _get_request_response_json(
session=self.session,
url=self._LEADERBOARD_ENDPOINT,
params=query_params,
timeout=self.timeout,
)
logger.trace(f"Validating response from '{self._LEADERBOARD_ENDPOINT}'")
return LeaderBoardResponse(**processed_response)
def lobbies(self, game: str = "aoe2de") -> list[MatchLobby]:
"""
Request all open lobbies.
Args:
game (str): The game for which to extract the list of strings. Defaults to 'aoe2de'.
Possibilities are 'aoe2hd' (Age of Empires 2: HD Edition) and 'aoe2de' (Age of
Empires 2: Definitive Edition).
Returns:
A list of MatchLobby valideted objects, each one encapsulating the data for a currently
open lobby.
"""
# logger.debug("Preparing parameters for open lobbies query")
# query_params = {"game": game}
# processed_response = _get_request_response_json(
# session=self.session,
# url=self._LOBBIES_ENDPOINT,
# params=query_params,
# timeout=self.timeout,
# )
# logger.trace(f"Validating response from '{self._LOBBIES_ENDPOINT}'")
# return _LIST_MATCHLOBBY_ADAPTER.validate_python(processed_response)
logger.error(f"Tried to query {self._LOBBIES_ENDPOINT} endpoint, which was removed by aoe2.net")
raise RemovedApiEndpointError(self._LOBBIES_ENDPOINT)
def last_match(
self, game: str = "aoe2de", steam_id: int | None = None, profile_id: int | None = None
) -> LastMatchResponse:
"""
Request the last match the player started playing, this will be the current match if they
are still in game. Either 'steam_id' or 'profile_id' required.
Args:
game (str): The game for which to extract the list of strings. Defaults to 'aoe2de'.
Possibilities are 'aoe2hd' (Age of Empires 2: HD Edition) and 'aoe2de' (Age of
Empires 2: Definitive Edition).
steam_id (int): The player's steamID64 (ex: 76561199003184910).
profile_id (int): The player's profile ID (ex: 459658).
Raises:
Aoe2NetError: if the not one of 'steam_id' or 'profile_id' are provided.
Returns:
A LastMatchResponse validated object with the information of the game, including the
following attributes: 'profile_id', 'steam_id', 'name', 'clan', 'country' and
'last_match'.
"""
# if not steam_id and not profile_id:
# logger.error("Missing one of 'steam_id', 'profile_id'.")
# msg = "Either 'steam_id' or 'profile_id' required, please provide one."
# raise Aoe2NetError(msg)
# logger.debug("Preparing parameters for last match query")
# query_params = {"game": game, "steam_id": steam_id, "profile_id": profile_id}
# processed_response = _get_request_response_json(
# session=self.session,
# url=self._LAST_MATCH_ENDPOINT,
# params=query_params,
# timeout=self.timeout,
# )
# logger.trace(f"Validating response from '{self._LAST_MATCH_ENDPOINT}'")
# return LastMatchResponse(**processed_response)
logger.error(f"Tried to query {self._LAST_MATCH_ENDPOINT} endpoint, which was removed by aoe2.net")
raise RemovedApiEndpointError(self._LAST_MATCH_ENDPOINT)
def match_history(
self,
game: str = "aoe2de",
start: int = 0,
count: int = 10,
steam_id: int | None = None,
profile_id: int | None = None,
) -> list[MatchLobby]:
"""
Request the match history for a player. Either 'steam_id' or 'profile_id' required.
Args:
game (str): The game for which to extract the list of strings. Defaults to 'aoe2de'.
Possibilities are 'aoe2hd' (Age of Empires 2: HD Edition) and 'aoe2de' (Age of
Empires 2: Definitive Edition).
start (int): starting match (0 is the most recent match). Defaults to 0.
count (int): number of matches to get (must be 1000 or less). Defaults to 10.
steam_id (int): The player's steamID64 (ex: 76561199003184910).
profile_id (int): The player's profile ID (ex: 459658).
Raises:
Aoe2NetError: if the 'count' parameter exceeds 1000.
Aoe2NetError: if the not one of 'steam_id' or 'profile_id' are provided.
Returns:
A list of MatchLobby validated objects, each one encapsulating the data for one of the
player's previous matches.
"""
if count > _MAX_MATCH_HISTORY_COUNT:
logger.error(f"'count' has to be 1000 or less, but {count} was provided.")
msg = "Invalid value for parameter 'count'."
raise Aoe2NetError(msg)
if not steam_id and not profile_id:
logger.error("Missing one of 'steam_id', 'profile_id'.")
msg = "Either 'steam_id' or 'profile_id' required, please provide one."
raise Aoe2NetError(msg)
logger.debug("Preparing parameters for match history query")
query_params = {
"game": game,
"start": start,
"count": count,
"steam_id": steam_id,
"profile_id": profile_id,
}
processed_response = _get_request_response_json(
session=self.session,
url=self._MATCH_HISTORY_ENDPOINT,
params=query_params,
timeout=self.timeout,
)
logger.trace(f"Validating response from '{self._MATCH_HISTORY_ENDPOINT}'")
return _LIST_MATCHLOBBY_ADAPTER.validate_python(processed_response)
def rating_history(
self,
game: str = "aoe2de",
leaderboard_id: int = 3,
start: int = 0,
count: int = 20,
steam_id: int | None = None,
profile_id: int | None = None,
) -> list[RatingTimePoint]:
"""
Requests the rating history for a player. Either 'steam_id' or 'profile_id' required.
Args:
game (str): The game for which to extract the list of strings. Defaults to 'aoe2de'.
Possibilities are 'aoe2hd' (Age of Empires 2: HD Edition) and 'aoe2de' (Age of
Empires 2: Definitive Edition).
leaderboard_id (int): Leaderboard to extract the data for (Unranked=0,
1v1 Deathmatch=1, Team Deathmatch=2, 1v1 Random Map=3, Team Random Map=4).
Defaults to 3.
start (int): starting match (0 is the most recent match). Defaults to 0.
count (int): number of matches to get the rating for (must be 1000 or less). Defaults
to 100.
steam_id (int): The player's steamID64 (ex: 76561199003184910).
profile_id (int): The player's profile ID (ex: 459658).
Raises:
Aoe2NetError: if the 'count' parameter exceeds 10 000.
Aoe2NetError: if the not one of 'steam_id' or 'profile_id' are provided.
Returns:
A list of RatingTimePoint validated objects, each one encapsulating data at a certain
point in time corresponding to a match played by the player, including the rating,
timestamp of the match, streaks etc.
"""
if count > _MAX_RATING_HISTORY_COUNT:
logger.error(f"'count' has to be 10 000 or less, but {count} was provided.")
msg = "Invalid value for parameter 'count'."
raise Aoe2NetError(msg)
if not steam_id and not profile_id:
logger.error("Missing one of 'steam_id', 'profile_id'.")
msg = "Either 'steam_id' or 'profile_id' required, please provide one."
raise Aoe2NetError(msg)
logger.debug("Preparing parameters for rating history query")
query_params = {
"game": game,
"leaderboard_id": leaderboard_id,
"start": start,
"count": count,
"steam_id": steam_id,
"profile_id": profile_id,
}
processed_response = _get_request_response_json(
session=self.session,
url=self._RATING_HISTORY_ENDPOINT,
params=query_params,
timeout=self.timeout,
)
logger.trace(f"Validating response from '{self._RATING_HISTORY_ENDPOINT}'")
return _LIST_RATINGTIMEPOINT_ADAPTER.validate_python(processed_response)
def matches(self, game: str = "aoe2de", count: int = 10, since: int | None = None) -> list[MatchLobby]:
"""
Request matches after a specific time: the match history in an optionally given time
window.
If 'since' is not set, only the X amount of current past matches (specified by 'count')
will be returned.
Args:
game (str): The game for which to extract the list of strings. Defaults to 'aoe2de'.
Possibilities are 'aoe2hd' (Age of Empires 2: HD Edition) and 'aoe2de' (Age of
Empires 2: Definitive Edition).
count (int): number of matches to get (must be 1000 or less). Defaults to 10.
since (int): only show matches starting after 'since' timestamp (epoch).
Raises:
Aoe2NetError: if the 'count' parameter exceeds 1000.
Returns:
A list of MatchLobby validated objects, each one encapsulating the data for one of the
played matches during the time window queried for.
"""
# if count > _MAX_MATCHES_COUNT:
# logger.error(f"'count' has to be 1000 or less, but {count} was provided.")
# msg = "Invalid value for parameter 'count'."
# raise Aoe2NetError(msg)
# logger.debug("Preparing parameters for matches query")
# query_params = {
# "game": game,
# "count": count,
# "since": since,
# }
# processed_response = _get_request_response_json(
# session=self.session,
# url=self._MATCHES_ENDPOINT,
# params=query_params,
# timeout=self.timeout,
# )
# logger.trace(f"Validating response from '{self._MATCHES_ENDPOINT}'")
# return _LIST_MATCHLOBBY_ADAPTER.validate_python(processed_response)
logger.error(f"Tried to query {self._MATCHES_ENDPOINT} endpoint, which was removed by aoe2.net")
raise RemovedApiEndpointError(self._MATCHES_ENDPOINT)
def match(self, game: str = "aoe2de", uuid: str | None = None, match_id: int | None = None) -> MatchLobby:
"""
Request details about a match. Either 'uuid' or 'match_id' required.
Args:
game (str): The game for which to extract the list of strings. Defaults to 'aoe2de'.
Possibilities are 'aoe2hd' (Age of Empires 2: HD Edition) and 'aoe2de' (Age of
Empires 2: Definitive Edition).
uuid (str): match UUID (ex: '66ec2575-5ee4-d241-a1fc-d7ffeffb48b6').
match_id (int): match ID.
Raises:
Aoe2NetError: if the not one of 'uuid' or 'match_id' are provided.
Returns:
A MatchLobby validated object with the information of the specific match, including.
"""
# if not uuid and not match_id:
# logger.error("Missing one of 'uuid', 'match_id'.")
# msg = "Either 'uuid' or 'match_id' required, please provide one."
# raise Aoe2NetError(msg)
# logger.debug("Preparing parameters for single match query")
# query_params = {
# "game": game,
# "uuid": uuid,
# "match_id": match_id,
# }
# processed_response = _get_request_response_json(
# session=self.session,
# url=self._MATCH_ENDPOINT,
# params=query_params,
# timeout=self.timeout,
# )
# logger.trace(f"Validating response from '{self._MATCH_ENDPOINT}'")
# return MatchLobby(**processed_response)
logger.error(f"Tried to query {self._MATCH_ENDPOINT} endpoint, which was removed by aoe2.net")
raise RemovedApiEndpointError(self._MATCH_ENDPOINT)
def num_online(self, game: str = "aoe2de") -> NumOnlineResponse:
"""
Number of players in game and an estimate of the number current playing multiplayer.
Args:
game (str): The game for which to extract the list of strings. Defaults to 'aoe2de'.
Possibilities are 'aoe2hd' (Age of Empires 2: HD Edition) and 'aoe2de' (Age of
Empires 2: Definitive Edition).
Returns:
A NumOnlineResponse validated object with the app id and a list of PlayerCountTimePoint
validated objects encapsulating estimated metrics at different timestamps ('steam',
'multiplayer', 'looking', 'in_game', 'multiplayer_1h' & 'multiplayer_24h').
"""
# logger.debug("Preparing parameters for number of online players query")
# query_params = {"game": game}
# processed_response = _get_request_response_json(
# session=self.session,
# url=self._NUMBER_ONLINE_ENDPOINT,
# params=query_params,
# timeout=self.timeout,
# )
# logger.trace(f"Validating response from '{self._NUMBER_ONLINE_ENDPOINT}'")
# return NumOnlineResponse(**processed_response)
logger.error(f"Tried to query {self._NUMBER_ONLINE_ENDPOINT} endpoint, which was removed by aoe2.net")
raise RemovedApiEndpointError(self._NUMBER_ONLINE_ENDPOINT)
Methods
last_match
def last_match(
self,
game: 'str' = 'aoe2de',
steam_id: 'int | None' = None,
profile_id: 'int | None' = None
) -> 'LastMatchResponse'
Request the last match the player started playing, this will be the current match if they
are still in game. Either 'steam_id' or 'profile_id' required.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
| game | str | The game for which to extract the list of strings. Defaults to 'aoe2de'. Possibilities are 'aoe2hd' (Age of Empires 2: HD Edition) and 'aoe2de' (Age of Empires 2: Definitive Edition). |
'aoe2de' |
| steam_id | int | The player's steamID64 (ex: 76561199003184910). | None |
| profile_id | int | The player's profile ID (ex: 459658). | None |
Returns:
| Type | Description |
|---|---|
| None | A LastMatchResponse validated object with the information of the game, including the following attributes: 'profile_id', 'steam_id', 'name', 'clan', 'country' and 'last_match'. |
Raises:
| Type | Description |
|---|---|
| Aoe2NetError | if the not one of 'steam_id' or 'profile_id' are provided. |
View Source
def last_match(
self, game: str = "aoe2de", steam_id: int | None = None, profile_id: int | None = None
) -> LastMatchResponse:
"""
Request the last match the player started playing, this will be the current match if they
are still in game. Either 'steam_id' or 'profile_id' required.
Args:
game (str): The game for which to extract the list of strings. Defaults to 'aoe2de'.
Possibilities are 'aoe2hd' (Age of Empires 2: HD Edition) and 'aoe2de' (Age of
Empires 2: Definitive Edition).
steam_id (int): The player's steamID64 (ex: 76561199003184910).
profile_id (int): The player's profile ID (ex: 459658).
Raises:
Aoe2NetError: if the not one of 'steam_id' or 'profile_id' are provided.
Returns:
A LastMatchResponse validated object with the information of the game, including the
following attributes: 'profile_id', 'steam_id', 'name', 'clan', 'country' and
'last_match'.
"""
# if not steam_id and not profile_id:
# logger.error("Missing one of 'steam_id', 'profile_id'.")
# msg = "Either 'steam_id' or 'profile_id' required, please provide one."
# raise Aoe2NetError(msg)
# logger.debug("Preparing parameters for last match query")
# query_params = {"game": game, "steam_id": steam_id, "profile_id": profile_id}
# processed_response = _get_request_response_json(
# session=self.session,
# url=self._LAST_MATCH_ENDPOINT,
# params=query_params,
# timeout=self.timeout,
# )
# logger.trace(f"Validating response from '{self._LAST_MATCH_ENDPOINT}'")
# return LastMatchResponse(**processed_response)
logger.error(f"Tried to query {self._LAST_MATCH_ENDPOINT} endpoint, which was removed by aoe2.net")
raise RemovedApiEndpointError(self._LAST_MATCH_ENDPOINT)
leaderboard
def leaderboard(
self,
game: 'str' = 'aoe2de',
leaderboard_id: 'int' = 3,
start: 'int' = 1,
count: 'int' = 10,
search: 'str | None' = None,
steam_id: 'int | None' = None,
profile_id: 'int | None' = None
) -> 'LeaderBoardResponse'
Request the current leaderboards.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
| game | str | The game for which to extract the list of strings. Defaults to 'aoe2de'. Possibilities are 'aoe2hd' (Age of Empires 2: HD Edition) and 'aoe2de' (Age of Empires 2: Definitive Edition). |
'aoe2de' |
| leaderboard_id | int | Leaderboard to extract the data for (Unranked=0, 1v1 Deathmatch=1, Team Deathmatch=2, 1v1 Random Map=3, Team Random Map=4). Defaults to 3. |
None |
| start | int | Starting rank (ignored if search, steam_id, or profile_id are defined). Defaults to 1. |
None |
| count | int | Number of leaderboard entries to get (warning: must be 10000 or less). Defaults to 10. |
None |
| search | str | Optional. To perform the search for a specific player, from their name. | None |
| steam_id | int | Optional. To perform the search for a specific player, from their steamID64 (ex: 76561199003184910). |
None |
| profile_id | int | Optional. To perform the search for a specific player, from their profile ID (ex: 459658). |
None |
Returns:
| Type | Description |
|---|---|
| None | A LeaderBoardResponse validated object with the different parameters used for the query, the total amount of hits, and the leaderboard as a list profile entries for each ranking. |
Raises:
| Type | Description |
|---|---|
| Aoe2NetError | if the 'count' parameter exceeds 10 000. |
View Source
def leaderboard(
self,
game: str = "aoe2de",
leaderboard_id: int = 3,
start: int = 1,
count: int = 10,
search: str | None = None,
steam_id: int | None = None,
profile_id: int | None = None,
) -> LeaderBoardResponse:
"""
Request the current leaderboards.
Args:
game (str): The game for which to extract the list of strings. Defaults to 'aoe2de'.
Possibilities are 'aoe2hd' (Age of Empires 2: HD Edition) and 'aoe2de' (Age of
Empires 2: Definitive Edition).
leaderboard_id (int): Leaderboard to extract the data for (Unranked=0,
1v1 Deathmatch=1, Team Deathmatch=2, 1v1 Random Map=3, Team Random Map=4).
Defaults to 3.
start (int): Starting rank (ignored if search, steam_id, or profile_id are defined).
Defaults to 1.
count (int): Number of leaderboard entries to get (warning: must be 10000 or less).
Defaults to 10.
search (str): Optional. To perform the search for a specific player, from their name.
steam_id (int): Optional. To perform the search for a specific player, from their
steamID64 (ex: 76561199003184910).
profile_id (int): Optional. To perform the search for a specific player, from their
profile ID (ex: 459658).
Raises:
Aoe2NetError: if the 'count' parameter exceeds 10 000.
Returns:
A LeaderBoardResponse validated object with the different parameters used for the
query, the total amount of hits, and the leaderboard as a list profile entries for
each ranking.
"""
if count > _MAX_LEADERBOARD_COUNT:
logger.error(f"'count' has to be 10000 or less, but {count} was provided.")
msg = "Invalid value for parameter 'count'."
raise Aoe2NetError(msg)
logger.debug("Preparing parameters for leaderboard query")
query_params = {
"game": game,
"leaderboard_id": leaderboard_id,
"start": start,
"count": count,
"search": search,
"steam_id": steam_id,
"profile_id": profile_id,
}
processed_response = _get_request_response_json(
session=self.session,
url=self._LEADERBOARD_ENDPOINT,
params=query_params,
timeout=self.timeout,
)
logger.trace(f"Validating response from '{self._LEADERBOARD_ENDPOINT}'")
return LeaderBoardResponse(**processed_response)
lobbies
def lobbies(
self,
game: 'str' = 'aoe2de'
) -> 'list[MatchLobby]'
Request all open lobbies.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
| game | str | The game for which to extract the list of strings. Defaults to 'aoe2de'. Possibilities are 'aoe2hd' (Age of Empires 2: HD Edition) and 'aoe2de' (Age of Empires 2: Definitive Edition). |
'aoe2de' |
Returns:
| Type | Description |
|---|---|
| None | A list of MatchLobby valideted objects, each one encapsulating the data for a currently open lobby. |
View Source
def lobbies(self, game: str = "aoe2de") -> list[MatchLobby]:
"""
Request all open lobbies.
Args:
game (str): The game for which to extract the list of strings. Defaults to 'aoe2de'.
Possibilities are 'aoe2hd' (Age of Empires 2: HD Edition) and 'aoe2de' (Age of
Empires 2: Definitive Edition).
Returns:
A list of MatchLobby valideted objects, each one encapsulating the data for a currently
open lobby.
"""
# logger.debug("Preparing parameters for open lobbies query")
# query_params = {"game": game}
# processed_response = _get_request_response_json(
# session=self.session,
# url=self._LOBBIES_ENDPOINT,
# params=query_params,
# timeout=self.timeout,
# )
# logger.trace(f"Validating response from '{self._LOBBIES_ENDPOINT}'")
# return _LIST_MATCHLOBBY_ADAPTER.validate_python(processed_response)
logger.error(f"Tried to query {self._LOBBIES_ENDPOINT} endpoint, which was removed by aoe2.net")
raise RemovedApiEndpointError(self._LOBBIES_ENDPOINT)
match
def match(
self,
game: 'str' = 'aoe2de',
uuid: 'str | None' = None,
match_id: 'int | None' = None
) -> 'MatchLobby'
Request details about a match. Either 'uuid' or 'match_id' required.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
| game | str | The game for which to extract the list of strings. Defaults to 'aoe2de'. Possibilities are 'aoe2hd' (Age of Empires 2: HD Edition) and 'aoe2de' (Age of Empires 2: Definitive Edition). |
'aoe2de' |
| uuid | str | match UUID (ex: '66ec2575-5ee4-d241-a1fc-d7ffeffb48b6'). | None |
| match_id | int | match ID. | None |
Returns:
| Type | Description |
|---|---|
| None | A MatchLobby validated object with the information of the specific match, including. |
Raises:
| Type | Description |
|---|---|
| Aoe2NetError | if the not one of 'uuid' or 'match_id' are provided. |
View Source
def match(self, game: str = "aoe2de", uuid: str | None = None, match_id: int | None = None) -> MatchLobby:
"""
Request details about a match. Either 'uuid' or 'match_id' required.
Args:
game (str): The game for which to extract the list of strings. Defaults to 'aoe2de'.
Possibilities are 'aoe2hd' (Age of Empires 2: HD Edition) and 'aoe2de' (Age of
Empires 2: Definitive Edition).
uuid (str): match UUID (ex: '66ec2575-5ee4-d241-a1fc-d7ffeffb48b6').
match_id (int): match ID.
Raises:
Aoe2NetError: if the not one of 'uuid' or 'match_id' are provided.
Returns:
A MatchLobby validated object with the information of the specific match, including.
"""
# if not uuid and not match_id:
# logger.error("Missing one of 'uuid', 'match_id'.")
# msg = "Either 'uuid' or 'match_id' required, please provide one."
# raise Aoe2NetError(msg)
# logger.debug("Preparing parameters for single match query")
# query_params = {
# "game": game,
# "uuid": uuid,
# "match_id": match_id,
# }
# processed_response = _get_request_response_json(
# session=self.session,
# url=self._MATCH_ENDPOINT,
# params=query_params,
# timeout=self.timeout,
# )
# logger.trace(f"Validating response from '{self._MATCH_ENDPOINT}'")
# return MatchLobby(**processed_response)
logger.error(f"Tried to query {self._MATCH_ENDPOINT} endpoint, which was removed by aoe2.net")
raise RemovedApiEndpointError(self._MATCH_ENDPOINT)
match_history
def match_history(
self,
game: 'str' = 'aoe2de',
start: 'int' = 0,
count: 'int' = 10,
steam_id: 'int | None' = None,
profile_id: 'int | None' = None
) -> 'list[MatchLobby]'
Request the match history for a player. Either 'steam_id' or 'profile_id' required.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
| game | str | The game for which to extract the list of strings. Defaults to 'aoe2de'. Possibilities are 'aoe2hd' (Age of Empires 2: HD Edition) and 'aoe2de' (Age of Empires 2: Definitive Edition). |
'aoe2de' |
| start | int | starting match (0 is the most recent match). Defaults to 0. | 0 |
| count | int | number of matches to get (must be 1000 or less). Defaults to 10. | 10 |
| steam_id | int | The player's steamID64 (ex: 76561199003184910). | None |
| profile_id | int | The player's profile ID (ex: 459658). | None |
Returns:
| Type | Description |
|---|---|
| None | A list of MatchLobby validated objects, each one encapsulating the data for one of the player's previous matches. |
Raises:
| Type | Description |
|---|---|
| Aoe2NetError | if the 'count' parameter exceeds 1000. |
| Aoe2NetError | if the not one of 'steam_id' or 'profile_id' are provided. |
View Source
def match_history(
self,
game: str = "aoe2de",
start: int = 0,
count: int = 10,
steam_id: int | None = None,
profile_id: int | None = None,
) -> list[MatchLobby]:
"""
Request the match history for a player. Either 'steam_id' or 'profile_id' required.
Args:
game (str): The game for which to extract the list of strings. Defaults to 'aoe2de'.
Possibilities are 'aoe2hd' (Age of Empires 2: HD Edition) and 'aoe2de' (Age of
Empires 2: Definitive Edition).
start (int): starting match (0 is the most recent match). Defaults to 0.
count (int): number of matches to get (must be 1000 or less). Defaults to 10.
steam_id (int): The player's steamID64 (ex: 76561199003184910).
profile_id (int): The player's profile ID (ex: 459658).
Raises:
Aoe2NetError: if the 'count' parameter exceeds 1000.
Aoe2NetError: if the not one of 'steam_id' or 'profile_id' are provided.
Returns:
A list of MatchLobby validated objects, each one encapsulating the data for one of the
player's previous matches.
"""
if count > _MAX_MATCH_HISTORY_COUNT:
logger.error(f"'count' has to be 1000 or less, but {count} was provided.")
msg = "Invalid value for parameter 'count'."
raise Aoe2NetError(msg)
if not steam_id and not profile_id:
logger.error("Missing one of 'steam_id', 'profile_id'.")
msg = "Either 'steam_id' or 'profile_id' required, please provide one."
raise Aoe2NetError(msg)
logger.debug("Preparing parameters for match history query")
query_params = {
"game": game,
"start": start,
"count": count,
"steam_id": steam_id,
"profile_id": profile_id,
}
processed_response = _get_request_response_json(
session=self.session,
url=self._MATCH_HISTORY_ENDPOINT,
params=query_params,
timeout=self.timeout,
)
logger.trace(f"Validating response from '{self._MATCH_HISTORY_ENDPOINT}'")
return _LIST_MATCHLOBBY_ADAPTER.validate_python(processed_response)
matches
def matches(
self,
game: 'str' = 'aoe2de',
count: 'int' = 10,
since: 'int | None' = None
) -> 'list[MatchLobby]'
Request matches after a specific time: the match history in an optionally given time
window.
If 'since' is not set, only the X amount of current past matches (specified by 'count') will be returned.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
| game | str | The game for which to extract the list of strings. Defaults to 'aoe2de'. Possibilities are 'aoe2hd' (Age of Empires 2: HD Edition) and 'aoe2de' (Age of Empires 2: Definitive Edition). |
'aoe2de' |
| count | int | number of matches to get (must be 1000 or less). Defaults to 10. | 10 |
| since | int | only show matches starting after 'since' timestamp (epoch). | None |
Returns:
| Type | Description |
|---|---|
| None | A list of MatchLobby validated objects, each one encapsulating the data for one of the played matches during the time window queried for. |
Raises:
| Type | Description |
|---|---|
| Aoe2NetError | if the 'count' parameter exceeds 1000. |
View Source
def matches(self, game: str = "aoe2de", count: int = 10, since: int | None = None) -> list[MatchLobby]:
"""
Request matches after a specific time: the match history in an optionally given time
window.
If 'since' is not set, only the X amount of current past matches (specified by 'count')
will be returned.
Args:
game (str): The game for which to extract the list of strings. Defaults to 'aoe2de'.
Possibilities are 'aoe2hd' (Age of Empires 2: HD Edition) and 'aoe2de' (Age of
Empires 2: Definitive Edition).
count (int): number of matches to get (must be 1000 or less). Defaults to 10.
since (int): only show matches starting after 'since' timestamp (epoch).
Raises:
Aoe2NetError: if the 'count' parameter exceeds 1000.
Returns:
A list of MatchLobby validated objects, each one encapsulating the data for one of the
played matches during the time window queried for.
"""
# if count > _MAX_MATCHES_COUNT:
# logger.error(f"'count' has to be 1000 or less, but {count} was provided.")
# msg = "Invalid value for parameter 'count'."
# raise Aoe2NetError(msg)
# logger.debug("Preparing parameters for matches query")
# query_params = {
# "game": game,
# "count": count,
# "since": since,
# }
# processed_response = _get_request_response_json(
# session=self.session,
# url=self._MATCHES_ENDPOINT,
# params=query_params,
# timeout=self.timeout,
# )
# logger.trace(f"Validating response from '{self._MATCHES_ENDPOINT}'")
# return _LIST_MATCHLOBBY_ADAPTER.validate_python(processed_response)
logger.error(f"Tried to query {self._MATCHES_ENDPOINT} endpoint, which was removed by aoe2.net")
raise RemovedApiEndpointError(self._MATCHES_ENDPOINT)
num_online
def num_online(
self,
game: 'str' = 'aoe2de'
) -> 'NumOnlineResponse'
Number of players in game and an estimate of the number current playing multiplayer.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
| game | str | The game for which to extract the list of strings. Defaults to 'aoe2de'. Possibilities are 'aoe2hd' (Age of Empires 2: HD Edition) and 'aoe2de' (Age of Empires 2: Definitive Edition). |
'aoe2de' |
Returns:
| Type | Description |
|---|---|
| None | A NumOnlineResponse validated object with the app id and a list of PlayerCountTimePoint validated objects encapsulating estimated metrics at different timestamps ('steam', 'multiplayer', 'looking', 'in_game', 'multiplayer_1h' & 'multiplayer_24h'). |
View Source
def num_online(self, game: str = "aoe2de") -> NumOnlineResponse:
"""
Number of players in game and an estimate of the number current playing multiplayer.
Args:
game (str): The game for which to extract the list of strings. Defaults to 'aoe2de'.
Possibilities are 'aoe2hd' (Age of Empires 2: HD Edition) and 'aoe2de' (Age of
Empires 2: Definitive Edition).
Returns:
A NumOnlineResponse validated object with the app id and a list of PlayerCountTimePoint
validated objects encapsulating estimated metrics at different timestamps ('steam',
'multiplayer', 'looking', 'in_game', 'multiplayer_1h' & 'multiplayer_24h').
"""
# logger.debug("Preparing parameters for number of online players query")
# query_params = {"game": game}
# processed_response = _get_request_response_json(
# session=self.session,
# url=self._NUMBER_ONLINE_ENDPOINT,
# params=query_params,
# timeout=self.timeout,
# )
# logger.trace(f"Validating response from '{self._NUMBER_ONLINE_ENDPOINT}'")
# return NumOnlineResponse(**processed_response)
logger.error(f"Tried to query {self._NUMBER_ONLINE_ENDPOINT} endpoint, which was removed by aoe2.net")
raise RemovedApiEndpointError(self._NUMBER_ONLINE_ENDPOINT)
rating_history
def rating_history(
self,
game: 'str' = 'aoe2de',
leaderboard_id: 'int' = 3,
start: 'int' = 0,
count: 'int' = 20,
steam_id: 'int | None' = None,
profile_id: 'int | None' = None
) -> 'list[RatingTimePoint]'
Requests the rating history for a player. Either 'steam_id' or 'profile_id' required.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
| game | str | The game for which to extract the list of strings. Defaults to 'aoe2de'. Possibilities are 'aoe2hd' (Age of Empires 2: HD Edition) and 'aoe2de' (Age of Empires 2: Definitive Edition). |
'aoe2de' |
| leaderboard_id | int | Leaderboard to extract the data for (Unranked=0, 1v1 Deathmatch=1, Team Deathmatch=2, 1v1 Random Map=3, Team Random Map=4). Defaults to 3. |
None |
| start | int | starting match (0 is the most recent match). Defaults to 0. | 0 |
| count | int | number of matches to get the rating for (must be 1000 or less). Defaults to 100. |
None |
| steam_id | int | The player's steamID64 (ex: 76561199003184910). | None |
| profile_id | int | The player's profile ID (ex: 459658). | None |
Returns:
| Type | Description |
|---|---|
| None | A list of RatingTimePoint validated objects, each one encapsulating data at a certain point in time corresponding to a match played by the player, including the rating, timestamp of the match, streaks etc. |
Raises:
| Type | Description |
|---|---|
| Aoe2NetError | if the 'count' parameter exceeds 10 000. |
| Aoe2NetError | if the not one of 'steam_id' or 'profile_id' are provided. |
View Source
def rating_history(
self,
game: str = "aoe2de",
leaderboard_id: int = 3,
start: int = 0,
count: int = 20,
steam_id: int | None = None,
profile_id: int | None = None,
) -> list[RatingTimePoint]:
"""
Requests the rating history for a player. Either 'steam_id' or 'profile_id' required.
Args:
game (str): The game for which to extract the list of strings. Defaults to 'aoe2de'.
Possibilities are 'aoe2hd' (Age of Empires 2: HD Edition) and 'aoe2de' (Age of
Empires 2: Definitive Edition).
leaderboard_id (int): Leaderboard to extract the data for (Unranked=0,
1v1 Deathmatch=1, Team Deathmatch=2, 1v1 Random Map=3, Team Random Map=4).
Defaults to 3.
start (int): starting match (0 is the most recent match). Defaults to 0.
count (int): number of matches to get the rating for (must be 1000 or less). Defaults
to 100.
steam_id (int): The player's steamID64 (ex: 76561199003184910).
profile_id (int): The player's profile ID (ex: 459658).
Raises:
Aoe2NetError: if the 'count' parameter exceeds 10 000.
Aoe2NetError: if the not one of 'steam_id' or 'profile_id' are provided.
Returns:
A list of RatingTimePoint validated objects, each one encapsulating data at a certain
point in time corresponding to a match played by the player, including the rating,
timestamp of the match, streaks etc.
"""
if count > _MAX_RATING_HISTORY_COUNT:
logger.error(f"'count' has to be 10 000 or less, but {count} was provided.")
msg = "Invalid value for parameter 'count'."
raise Aoe2NetError(msg)
if not steam_id and not profile_id:
logger.error("Missing one of 'steam_id', 'profile_id'.")
msg = "Either 'steam_id' or 'profile_id' required, please provide one."
raise Aoe2NetError(msg)
logger.debug("Preparing parameters for rating history query")
query_params = {
"game": game,
"leaderboard_id": leaderboard_id,
"start": start,
"count": count,
"steam_id": steam_id,
"profile_id": profile_id,
}
processed_response = _get_request_response_json(
session=self.session,
url=self._RATING_HISTORY_ENDPOINT,
params=query_params,
timeout=self.timeout,
)
logger.trace(f"Validating response from '{self._RATING_HISTORY_ENDPOINT}'")
return _LIST_RATINGTIMEPOINT_ADAPTER.validate_python(processed_response)
strings
def strings(
self,
game: 'str' = 'aoe2de'
) -> 'StringsResponse'
Requests a list of strings used by the API.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
| game | str | The game for which to extract the list of strings. Defaults to 'aoe2de'. Possibilities are 'aoe2hd' (Age of Empires 2: HD Edition) and 'aoe2de' (Age of Empires 2: Definitive Edition). |
'aoe2de' |
Returns:
| Type | Description |
|---|---|
| None | A StringsResponse validated object encapsulating the strings used by the API. |
View Source
def strings(self, game: str = "aoe2de") -> StringsResponse:
"""
Requests a list of strings used by the API.
Args:
game (str): The game for which to extract the list of strings. Defaults to 'aoe2de'.
Possibilities are 'aoe2hd' (Age of Empires 2: HD Edition) and 'aoe2de' (Age of
Empires 2: Definitive Edition).
Returns:
A StringsResponse validated object encapsulating the strings used by the API.
"""
logger.debug("Preparing parameters for strings query")
query_params = {"game": game}
processed_response = _get_request_response_json(
session=self.session,
url=self._STRINGS_ENDPOINT,
params=query_params,
timeout=self.timeout,
)
logger.trace(f"Validating response from '{self._STRINGS_ENDPOINT}'")
return StringsResponse(**processed_response)
AoE2NightbotAPI
class AoE2NightbotAPI(
timeout: 'float | tuple[float, float]' = 5
)
The 'AoE2NightbotAPI' class is a client that encompasses the https://aoe2.net/#nightbot API endpoints,
which only return their requested data as plain text.
View Source
class AoE2NightbotAPI:
"""
The 'AoE2NightbotAPI' class is a client that encompasses the https://aoe2.net/#nightbot API endpoints,
which only return their requested data as plain text.
"""
NIGHTBOT_BASE_URL: str = "https://aoe2.net/api/nightbot"
RANK_DETAILS_ENDPOINT = NIGHTBOT_BASE_URL + "/rank"
RECENT_OPPONENT_ENDPOINT = NIGHTBOT_BASE_URL + "/opponent"
CURRENT_MATCH_ENDPOINT = NIGHTBOT_BASE_URL + "/match"
CURRENT_CIVS_ENDPOINT = NIGHTBOT_BASE_URL + "/civs"
CURRENT_MAP_ENDPOINT = NIGHTBOT_BASE_URL + "/map"
def __init__(self, timeout: float | tuple[float, float] = 5):
"""Creating a Session for connection pooling since we're always querying the same host."""
self.session = requests.Session()
self.timeout = timeout
def __repr__(self) -> str:
return f"Client for <{self.NIGHTBOT_BASE_URL}>"
def rank(
self,
game: str = "aoe2de",
leaderboard_id: int = 3,
language: str = "en",
flag: str = "true",
search: str | None = None,
steam_id: int | None = None,
profile_id: int | None = None,
) -> str:
"""
Request rank details about a player. Either 'search', 'steam_id' or 'profile_id' required.
Args:
game (str): The game for which to extract the list of strings. Defaults to 'aoe2de'.
Possibilities are 'aoe2hd' (Age of Empires 2: HD Edition) and 'aoe2de' (Age of
Empires 2: Definitive Edition).
leaderboard_id (int): Leaderboard to extract the data for (Unranked=0,
1v1 Deathmatch=1, Team Deathmatch=2, 1v1 Random Map=3, Team Random Map=4).
Defaults to 3.
language (str): language for the returned response ('en', 'de', 'el', 'es', 'es-MX',
'fr', 'hi', 'it', 'ja', 'ko', 'ms', 'nl', 'pt', 'ru', 'tr', 'vi', 'zh', 'zh-TW').
Defaults to 'en'.
flag (str): boolean to show the player flag. Defaults to 'true'. Needs to be a string
for now since requests transforms True boolean to 'True' and the API rejects that.
search (str): To perform the search for a specific player, from their name. Will
return the highest rated player that matches the search.
steam_id (int): To perform the search for a specific player, from their steamID64
(ex: 76561199003184910).
profile_id (int): To perform the search for a specific player, from their profile ID
(ex: 459658).
Raises:
NightBotError: if the not one of 'search', 'steam_id' or 'profile_id' are provided.
Returns:
The text content of the response, as a decoded unicode string, with a quick sentence
of information about the player.
"""
if not any((search, steam_id, profile_id)):
logger.error("Missing one of 'search', 'steam_id', 'profile_id'.")
msg = "Either 'search', 'steam_id' or 'profile_id' required, please provide one."
raise NightBotError(msg)
logger.debug("Preparing parameters for rank details query")
query_params = {
"game": game,
"leaderboard_id": leaderboard_id,
"language": language,
"flag": flag,
"search": search,
"steam_id": steam_id,
"profile_id": profile_id,
}
return _get_request_text_response_decoded(
session=self.session,
url=self.RANK_DETAILS_ENDPOINT,
params=query_params,
timeout=self.timeout,
)
def opponent(
self,
game: str = "aoe2de",
leaderboard_id: int = 3,
language: str = "en",
flag: str = "true",
search: str | None = None,
steam_id: int | None = None,
profile_id: int | None = None,
) -> str:
"""
Request rank details about a player's most recent opponent (1v1 only). Either 'search',
'steam_id' or 'profile_id' required.
Args:
game (str): The game for which to extract the list of strings. Defaults to 'aoe2de'.
Possibilities are 'aoe2hd' (Age of Empires 2: HD Edition) and 'aoe2de' (Age of
Empires 2: Definitive Edition).
leaderboard_id (int): Leaderboard to extract the data for (Unranked=0,
1v1 Deathmatch=1, Team Deathmatch=2, 1v1 Random Map=3, Team Random Map=4).
Defaults to 3.
language (str): language for the returned response ('en', 'de', 'el', 'es', 'es-MX',
'fr', 'hi', 'it', 'ja', 'ko', 'ms', 'nl', 'pt', 'ru', 'tr', 'vi', 'zh', 'zh-TW').
Defaults to 'en'.
flag (str): boolean to show the player flag. Defaults to 'true'. Needs to be a string
for now since requests transforms True boolean to 'True' and the API rejects that.
search (str): To perform the search for a specific player, from their name. Will
return the highest rated player that matches the search.
steam_id (int): To perform the search for a specific player, from their steamID64
(ex: 76561199003184910).
profile_id (int): To perform the search for a specific player, from their profile ID
(ex: 459658).
Raises:
NightBotError: if the not one of 'search', 'steam_id' or 'profile_id' are provided.
Returns:
The text content of the response, as a decoded unicode string, with a quick sentence
of information about the player's last opponent.
"""
if not any((search, steam_id, profile_id)):
logger.error("Missing one of 'search', 'steam_id', 'profile_id'.")
msg = "Either 'search', 'steam_id' or 'profile_id' required, please provide one."
raise NightBotError(msg)
logger.debug("Preparing parameters for opponent details query")
query_params = {
"game": game,
"leaderboard_id": leaderboard_id,
"language": language,
"flag": flag,
"search": search,
"steam_id": steam_id,
"profile_id": profile_id,
}
return _get_request_text_response_decoded(
session=self.session,
url=self.RECENT_OPPONENT_ENDPOINT,
params=query_params,
timeout=self.timeout,
)
def match(
self,
game: str = "aoe2de",
leaderboard_id: int = 3,
language: str = "en",
color: str = "true",
flag: str = "true",
search: str | None = None,
steam_id: int | None = None,
profile_id: int | None = None,
) -> str:
"""
Request details about the current or last match. Either 'search', 'steam_id' or
'profile_id' required.
Args:
game (str): The game for which to extract the list of strings. Defaults to 'aoe2de'.
Possibilities are 'aoe2hd' (Age of Empires 2: HD Edition) and 'aoe2de' (Age of
Empires 2: Definitive Edition).
leaderboard_id (int): Leaderboard to extract the data for (Unranked=0,
1v1 Deathmatch=1, Team Deathmatch=2, 1v1 Random Map=3, Team Random Map=4).
Defaults to 3.
language (str): language for the returned response ('en', 'de', 'el', 'es', 'es-MX',
'fr', 'hi', 'it', 'ja', 'ko', 'ms', 'nl', 'pt', 'ru', 'tr', 'vi', 'zh', 'zh-TW').
Defaults to 'en'.
color (str): boolean to show player colors. Defaults to 'true'. Needs to be a string
for now since requests transforms True boolean to 'True' and the API rejects that.
flag (str): boolean to show the player flag. Defaults to 'true'. Needs to be a string
for now since requests transforms True boolean to 'True' and the API rejects that.
search (str): To perform the search for a specific player, from their name. Will
return the highest rated player that matches the search.
steam_id (int): To perform the search for a specific player, from their steamID64
(ex: 76561199003184910).
profile_id (int): To perform the search for a specific player, from their profile ID
(ex: 459658).
Raises:
NightBotError: if the not one of 'search', 'steam_id' or 'profile_id' are provided.
Returns:
The text content of the response, as a decoded unicode string, with a quick sentence
of information about the players in the match.
"""
if not any((search, steam_id, profile_id)):
logger.error("Missing one of 'search', 'steam_id', 'profile_id'.")
msg = "Either 'search', 'steam_id' or 'profile_id' required, please provide one."
raise NightBotError(msg)
logger.debug("Preparing parameters for match details query")
query_params = {
"game": game,
"leaderboard_id": leaderboard_id,
"language": language,
"color": color,
"flag": flag,
"search": search,
"steam_id": steam_id,
"profile_id": profile_id,
}
return _get_request_text_response_decoded(
session=self.session,
url=self.CURRENT_MATCH_ENDPOINT,
params=query_params,
timeout=self.timeout,
)
def civs(
self,
game: str = "aoe2de",
leaderboard_id: int = 3,
language: str = "en",
search: str | None = None,
steam_id: int | None = None,
profile_id: int | None = None,
) -> str:
"""
Request civilisations from the current or last match. Either 'search', 'steam_id' or
'profile_id' required.
Args:
game (str): The game for which to extract the list of strings. Defaults to 'aoe2de'.
Possibilities are 'aoe2hd' (Age of Empires 2: HD Edition) and 'aoe2de' (Age of
Empires 2: Definitive Edition).
leaderboard_id (int): Leaderboard to extract the data for (Unranked=0,
1v1 Deathmatch=1, Team Deathmatch=2, 1v1 Random Map=3, Team Random Map=4).
Defaults to 3.
language (str): language for the returned response ('en', 'de', 'el', 'es', 'es-MX',
'fr', 'hi', 'it', 'ja', 'ko', 'ms', 'nl', 'pt', 'ru', 'tr', 'vi', 'zh', 'zh-TW').
Defaults to 'en'.
search (str): To perform the search for a specific player, from their name. Will
return the highest rated player that matches the search.
steam_id (int): To perform the search for a specific player, from their steamID64
(ex: 76561199003184910).
profile_id (int): To perform the search for a specific player, from their profile ID
(ex: 459658).
Raises:
NightBotError: if the not one of 'search', 'steam_id' or 'profile_id' are provided.
Returns:
The text content of the response, as a decoded unicode string, with a quick sentence
of information about the player's last opponent.
"""
if not any((search, steam_id, profile_id)):
logger.error("Missing one of 'search', 'steam_id', 'profile_id'.")
msg = "Either 'search', 'steam_id' or 'profile_id' required, please provide one."
raise NightBotError(msg)
logger.debug("Preparing parameters for civilisations details query")
query_params = {
"game": game,
"leaderboard_id": leaderboard_id,
"language": language,
"search": search,
"steam_id": steam_id,
"profile_id": profile_id,
}
return _get_request_text_response_decoded(
session=self.session,
url=self.CURRENT_CIVS_ENDPOINT,
params=query_params,
timeout=self.timeout,
)
def map(
self,
game: str = "aoe2de",
leaderboard_id: int = 3,
language: str = "en",
search: str | None = None,
steam_id: int | None = None,
profile_id: int | None = None,
) -> str:
"""
Request civilisations from the current or last match. Either 'search', 'steam_id' or
'profile_id' required.
Args:
game (str): The game for which to extract the list of strings. Defaults to 'aoe2de'.
Possibilities are 'aoe2hd' (Age of Empires 2: HD Edition) and 'aoe2de' (Age of
Empires 2: Definitive Edition).
leaderboard_id (int): Leaderboard to extract the data for (Unranked=0,
1v1 Deathmatch=1, Team Deathmatch=2, 1v1 Random Map=3, Team Random Map=4).
Defaults to 3.
language (str): language for the returned response ('en', 'de', 'el', 'es', 'es-MX',
'fr', 'hi', 'it', 'ja', 'ko', 'ms', 'nl', 'pt', 'ru', 'tr', 'vi', 'zh', 'zh-TW').
Defaults to 'en'.
search (str): To perform the search for a specific player, from their name. Will
return the highest rated player that matches the search.
steam_id (int): To perform the search for a specific player, from their steamID64
(ex: 76561199003184910).
profile_id (int): To perform the search for a specific player, from their profile ID
(ex: 459658).
Raises:
NightBotError: if the not one of 'search', 'steam_id' or 'profile_id' are provided.
Returns:
The text content of the response, as a decoded unicode string, with a quick sentence
of information about the player's last opponent.
"""
if not any((search, steam_id, profile_id)):
logger.error("Missing one of 'search', 'steam_id', 'profile_id'.")
msg = "Either 'search', 'steam_id' or 'profile_id' required, please provide one."
raise NightBotError(msg)
logger.debug("Preparing parameters for civilisations details query")
query_params = {
"game": game,
"leaderboard_id": leaderboard_id,
"language": language,
"search": search,
"steam_id": steam_id,
"profile_id": profile_id,
}
return _get_request_text_response_decoded(
session=self.session,
url=self.CURRENT_MAP_ENDPOINT,
params=query_params,
timeout=self.timeout,
)
Class variables
CURRENT_CIVS_ENDPOINT
CURRENT_MAP_ENDPOINT
CURRENT_MATCH_ENDPOINT
NIGHTBOT_BASE_URL
RANK_DETAILS_ENDPOINT
RECENT_OPPONENT_ENDPOINT
Methods
civs
def civs(
self,
game: 'str' = 'aoe2de',
leaderboard_id: 'int' = 3,
language: 'str' = 'en',
search: 'str | None' = None,
steam_id: 'int | None' = None,
profile_id: 'int | None' = None
) -> 'str'
Request civilisations from the current or last match. Either 'search', 'steam_id' or
'profile_id' required.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
| game | str | The game for which to extract the list of strings. Defaults to 'aoe2de'. Possibilities are 'aoe2hd' (Age of Empires 2: HD Edition) and 'aoe2de' (Age of Empires 2: Definitive Edition). |
'aoe2de' |
| leaderboard_id | int | Leaderboard to extract the data for (Unranked=0, 1v1 Deathmatch=1, Team Deathmatch=2, 1v1 Random Map=3, Team Random Map=4). Defaults to 3. |
None |
| language | str | language for the returned response ('en', 'de', 'el', 'es', 'es-MX', 'fr', 'hi', 'it', 'ja', 'ko', 'ms', 'nl', 'pt', 'ru', 'tr', 'vi', 'zh', 'zh-TW'). Defaults to 'en'. |
None |
| search | str | To perform the search for a specific player, from their name. Will return the highest rated player that matches the search. |
None |
| steam_id | int | To perform the search for a specific player, from their steamID64 (ex: 76561199003184910). |
None |
| profile_id | int | To perform the search for a specific player, from their profile ID (ex: 459658). |
None |
Returns:
| Type | Description |
|---|---|
| None | The text content of the response, as a decoded unicode string, with a quick sentence of information about the player's last opponent. |
Raises:
| Type | Description |
|---|---|
| NightBotError | if the not one of 'search', 'steam_id' or 'profile_id' are provided. |
View Source
def civs(
self,
game: str = "aoe2de",
leaderboard_id: int = 3,
language: str = "en",
search: str | None = None,
steam_id: int | None = None,
profile_id: int | None = None,
) -> str:
"""
Request civilisations from the current or last match. Either 'search', 'steam_id' or
'profile_id' required.
Args:
game (str): The game for which to extract the list of strings. Defaults to 'aoe2de'.
Possibilities are 'aoe2hd' (Age of Empires 2: HD Edition) and 'aoe2de' (Age of
Empires 2: Definitive Edition).
leaderboard_id (int): Leaderboard to extract the data for (Unranked=0,
1v1 Deathmatch=1, Team Deathmatch=2, 1v1 Random Map=3, Team Random Map=4).
Defaults to 3.
language (str): language for the returned response ('en', 'de', 'el', 'es', 'es-MX',
'fr', 'hi', 'it', 'ja', 'ko', 'ms', 'nl', 'pt', 'ru', 'tr', 'vi', 'zh', 'zh-TW').
Defaults to 'en'.
search (str): To perform the search for a specific player, from their name. Will
return the highest rated player that matches the search.
steam_id (int): To perform the search for a specific player, from their steamID64
(ex: 76561199003184910).
profile_id (int): To perform the search for a specific player, from their profile ID
(ex: 459658).
Raises:
NightBotError: if the not one of 'search', 'steam_id' or 'profile_id' are provided.
Returns:
The text content of the response, as a decoded unicode string, with a quick sentence
of information about the player's last opponent.
"""
if not any((search, steam_id, profile_id)):
logger.error("Missing one of 'search', 'steam_id', 'profile_id'.")
msg = "Either 'search', 'steam_id' or 'profile_id' required, please provide one."
raise NightBotError(msg)
logger.debug("Preparing parameters for civilisations details query")
query_params = {
"game": game,
"leaderboard_id": leaderboard_id,
"language": language,
"search": search,
"steam_id": steam_id,
"profile_id": profile_id,
}
return _get_request_text_response_decoded(
session=self.session,
url=self.CURRENT_CIVS_ENDPOINT,
params=query_params,
timeout=self.timeout,
)
map
def map(
self,
game: 'str' = 'aoe2de',
leaderboard_id: 'int' = 3,
language: 'str' = 'en',
search: 'str | None' = None,
steam_id: 'int | None' = None,
profile_id: 'int | None' = None
) -> 'str'
Request civilisations from the current or last match. Either 'search', 'steam_id' or
'profile_id' required.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
| game | str | The game for which to extract the list of strings. Defaults to 'aoe2de'. Possibilities are 'aoe2hd' (Age of Empires 2: HD Edition) and 'aoe2de' (Age of Empires 2: Definitive Edition). |
'aoe2de' |
| leaderboard_id | int | Leaderboard to extract the data for (Unranked=0, 1v1 Deathmatch=1, Team Deathmatch=2, 1v1 Random Map=3, Team Random Map=4). Defaults to 3. |
None |
| language | str | language for the returned response ('en', 'de', 'el', 'es', 'es-MX', 'fr', 'hi', 'it', 'ja', 'ko', 'ms', 'nl', 'pt', 'ru', 'tr', 'vi', 'zh', 'zh-TW'). Defaults to 'en'. |
None |
| search | str | To perform the search for a specific player, from their name. Will return the highest rated player that matches the search. |
None |
| steam_id | int | To perform the search for a specific player, from their steamID64 (ex: 76561199003184910). |
None |
| profile_id | int | To perform the search for a specific player, from their profile ID (ex: 459658). |
None |
Returns:
| Type | Description |
|---|---|
| None | The text content of the response, as a decoded unicode string, with a quick sentence of information about the player's last opponent. |
Raises:
| Type | Description |
|---|---|
| NightBotError | if the not one of 'search', 'steam_id' or 'profile_id' are provided. |
View Source
def map(
self,
game: str = "aoe2de",
leaderboard_id: int = 3,
language: str = "en",
search: str | None = None,
steam_id: int | None = None,
profile_id: int | None = None,
) -> str:
"""
Request civilisations from the current or last match. Either 'search', 'steam_id' or
'profile_id' required.
Args:
game (str): The game for which to extract the list of strings. Defaults to 'aoe2de'.
Possibilities are 'aoe2hd' (Age of Empires 2: HD Edition) and 'aoe2de' (Age of
Empires 2: Definitive Edition).
leaderboard_id (int): Leaderboard to extract the data for (Unranked=0,
1v1 Deathmatch=1, Team Deathmatch=2, 1v1 Random Map=3, Team Random Map=4).
Defaults to 3.
language (str): language for the returned response ('en', 'de', 'el', 'es', 'es-MX',
'fr', 'hi', 'it', 'ja', 'ko', 'ms', 'nl', 'pt', 'ru', 'tr', 'vi', 'zh', 'zh-TW').
Defaults to 'en'.
search (str): To perform the search for a specific player, from their name. Will
return the highest rated player that matches the search.
steam_id (int): To perform the search for a specific player, from their steamID64
(ex: 76561199003184910).
profile_id (int): To perform the search for a specific player, from their profile ID
(ex: 459658).
Raises:
NightBotError: if the not one of 'search', 'steam_id' or 'profile_id' are provided.
Returns:
The text content of the response, as a decoded unicode string, with a quick sentence
of information about the player's last opponent.
"""
if not any((search, steam_id, profile_id)):
logger.error("Missing one of 'search', 'steam_id', 'profile_id'.")
msg = "Either 'search', 'steam_id' or 'profile_id' required, please provide one."
raise NightBotError(msg)
logger.debug("Preparing parameters for civilisations details query")
query_params = {
"game": game,
"leaderboard_id": leaderboard_id,
"language": language,
"search": search,
"steam_id": steam_id,
"profile_id": profile_id,
}
return _get_request_text_response_decoded(
session=self.session,
url=self.CURRENT_MAP_ENDPOINT,
params=query_params,
timeout=self.timeout,
)
match
def match(
self,
game: 'str' = 'aoe2de',
leaderboard_id: 'int' = 3,
language: 'str' = 'en',
color: 'str' = 'true',
flag: 'str' = 'true',
search: 'str | None' = None,
steam_id: 'int | None' = None,
profile_id: 'int | None' = None
) -> 'str'
Request details about the current or last match. Either 'search', 'steam_id' or
'profile_id' required.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
| game | str | The game for which to extract the list of strings. Defaults to 'aoe2de'. Possibilities are 'aoe2hd' (Age of Empires 2: HD Edition) and 'aoe2de' (Age of Empires 2: Definitive Edition). |
'aoe2de' |
| leaderboard_id | int | Leaderboard to extract the data for (Unranked=0, 1v1 Deathmatch=1, Team Deathmatch=2, 1v1 Random Map=3, Team Random Map=4). Defaults to 3. |
None |
| language | str | language for the returned response ('en', 'de', 'el', 'es', 'es-MX', 'fr', 'hi', 'it', 'ja', 'ko', 'ms', 'nl', 'pt', 'ru', 'tr', 'vi', 'zh', 'zh-TW'). Defaults to 'en'. |
None |
| color | str | boolean to show player colors. Defaults to 'true'. Needs to be a string for now since requests transforms True boolean to 'True' and the API rejects that. |
'true' |
| flag | str | boolean to show the player flag. Defaults to 'true'. Needs to be a string for now since requests transforms True boolean to 'True' and the API rejects that. |
'true' |
| search | str | To perform the search for a specific player, from their name. Will return the highest rated player that matches the search. |
None |
| steam_id | int | To perform the search for a specific player, from their steamID64 (ex: 76561199003184910). |
None |
| profile_id | int | To perform the search for a specific player, from their profile ID (ex: 459658). |
None |
Returns:
| Type | Description |
|---|---|
| None | The text content of the response, as a decoded unicode string, with a quick sentence of information about the players in the match. |
Raises:
| Type | Description |
|---|---|
| NightBotError | if the not one of 'search', 'steam_id' or 'profile_id' are provided. |
View Source
def match(
self,
game: str = "aoe2de",
leaderboard_id: int = 3,
language: str = "en",
color: str = "true",
flag: str = "true",
search: str | None = None,
steam_id: int | None = None,
profile_id: int | None = None,
) -> str:
"""
Request details about the current or last match. Either 'search', 'steam_id' or
'profile_id' required.
Args:
game (str): The game for which to extract the list of strings. Defaults to 'aoe2de'.
Possibilities are 'aoe2hd' (Age of Empires 2: HD Edition) and 'aoe2de' (Age of
Empires 2: Definitive Edition).
leaderboard_id (int): Leaderboard to extract the data for (Unranked=0,
1v1 Deathmatch=1, Team Deathmatch=2, 1v1 Random Map=3, Team Random Map=4).
Defaults to 3.
language (str): language for the returned response ('en', 'de', 'el', 'es', 'es-MX',
'fr', 'hi', 'it', 'ja', 'ko', 'ms', 'nl', 'pt', 'ru', 'tr', 'vi', 'zh', 'zh-TW').
Defaults to 'en'.
color (str): boolean to show player colors. Defaults to 'true'. Needs to be a string
for now since requests transforms True boolean to 'True' and the API rejects that.
flag (str): boolean to show the player flag. Defaults to 'true'. Needs to be a string
for now since requests transforms True boolean to 'True' and the API rejects that.
search (str): To perform the search for a specific player, from their name. Will
return the highest rated player that matches the search.
steam_id (int): To perform the search for a specific player, from their steamID64
(ex: 76561199003184910).
profile_id (int): To perform the search for a specific player, from their profile ID
(ex: 459658).
Raises:
NightBotError: if the not one of 'search', 'steam_id' or 'profile_id' are provided.
Returns:
The text content of the response, as a decoded unicode string, with a quick sentence
of information about the players in the match.
"""
if not any((search, steam_id, profile_id)):
logger.error("Missing one of 'search', 'steam_id', 'profile_id'.")
msg = "Either 'search', 'steam_id' or 'profile_id' required, please provide one."
raise NightBotError(msg)
logger.debug("Preparing parameters for match details query")
query_params = {
"game": game,
"leaderboard_id": leaderboard_id,
"language": language,
"color": color,
"flag": flag,
"search": search,
"steam_id": steam_id,
"profile_id": profile_id,
}
return _get_request_text_response_decoded(
session=self.session,
url=self.CURRENT_MATCH_ENDPOINT,
params=query_params,
timeout=self.timeout,
)
opponent
def opponent(
self,
game: 'str' = 'aoe2de',
leaderboard_id: 'int' = 3,
language: 'str' = 'en',
flag: 'str' = 'true',
search: 'str | None' = None,
steam_id: 'int | None' = None,
profile_id: 'int | None' = None
) -> 'str'
Request rank details about a player's most recent opponent (1v1 only). Either 'search',
'steam_id' or 'profile_id' required.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
| game | str | The game for which to extract the list of strings. Defaults to 'aoe2de'. Possibilities are 'aoe2hd' (Age of Empires 2: HD Edition) and 'aoe2de' (Age of Empires 2: Definitive Edition). |
'aoe2de' |
| leaderboard_id | int | Leaderboard to extract the data for (Unranked=0, 1v1 Deathmatch=1, Team Deathmatch=2, 1v1 Random Map=3, Team Random Map=4). Defaults to 3. |
None |
| language | str | language for the returned response ('en', 'de', 'el', 'es', 'es-MX', 'fr', 'hi', 'it', 'ja', 'ko', 'ms', 'nl', 'pt', 'ru', 'tr', 'vi', 'zh', 'zh-TW'). Defaults to 'en'. |
None |
| flag | str | boolean to show the player flag. Defaults to 'true'. Needs to be a string for now since requests transforms True boolean to 'True' and the API rejects that. |
'true' |
| search | str | To perform the search for a specific player, from their name. Will return the highest rated player that matches the search. |
None |
| steam_id | int | To perform the search for a specific player, from their steamID64 (ex: 76561199003184910). |
None |
| profile_id | int | To perform the search for a specific player, from their profile ID (ex: 459658). |
None |
Returns:
| Type | Description |
|---|---|
| None | The text content of the response, as a decoded unicode string, with a quick sentence of information about the player's last opponent. |
Raises:
| Type | Description |
|---|---|
| NightBotError | if the not one of 'search', 'steam_id' or 'profile_id' are provided. |
View Source
def opponent(
self,
game: str = "aoe2de",
leaderboard_id: int = 3,
language: str = "en",
flag: str = "true",
search: str | None = None,
steam_id: int | None = None,
profile_id: int | None = None,
) -> str:
"""
Request rank details about a player's most recent opponent (1v1 only). Either 'search',
'steam_id' or 'profile_id' required.
Args:
game (str): The game for which to extract the list of strings. Defaults to 'aoe2de'.
Possibilities are 'aoe2hd' (Age of Empires 2: HD Edition) and 'aoe2de' (Age of
Empires 2: Definitive Edition).
leaderboard_id (int): Leaderboard to extract the data for (Unranked=0,
1v1 Deathmatch=1, Team Deathmatch=2, 1v1 Random Map=3, Team Random Map=4).
Defaults to 3.
language (str): language for the returned response ('en', 'de', 'el', 'es', 'es-MX',
'fr', 'hi', 'it', 'ja', 'ko', 'ms', 'nl', 'pt', 'ru', 'tr', 'vi', 'zh', 'zh-TW').
Defaults to 'en'.
flag (str): boolean to show the player flag. Defaults to 'true'. Needs to be a string
for now since requests transforms True boolean to 'True' and the API rejects that.
search (str): To perform the search for a specific player, from their name. Will
return the highest rated player that matches the search.
steam_id (int): To perform the search for a specific player, from their steamID64
(ex: 76561199003184910).
profile_id (int): To perform the search for a specific player, from their profile ID
(ex: 459658).
Raises:
NightBotError: if the not one of 'search', 'steam_id' or 'profile_id' are provided.
Returns:
The text content of the response, as a decoded unicode string, with a quick sentence
of information about the player's last opponent.
"""
if not any((search, steam_id, profile_id)):
logger.error("Missing one of 'search', 'steam_id', 'profile_id'.")
msg = "Either 'search', 'steam_id' or 'profile_id' required, please provide one."
raise NightBotError(msg)
logger.debug("Preparing parameters for opponent details query")
query_params = {
"game": game,
"leaderboard_id": leaderboard_id,
"language": language,
"flag": flag,
"search": search,
"steam_id": steam_id,
"profile_id": profile_id,
}
return _get_request_text_response_decoded(
session=self.session,
url=self.RECENT_OPPONENT_ENDPOINT,
params=query_params,
timeout=self.timeout,
)
rank
def rank(
self,
game: 'str' = 'aoe2de',
leaderboard_id: 'int' = 3,
language: 'str' = 'en',
flag: 'str' = 'true',
search: 'str | None' = None,
steam_id: 'int | None' = None,
profile_id: 'int | None' = None
) -> 'str'
Request rank details about a player. Either 'search', 'steam_id' or 'profile_id' required.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
| game | str | The game for which to extract the list of strings. Defaults to 'aoe2de'. Possibilities are 'aoe2hd' (Age of Empires 2: HD Edition) and 'aoe2de' (Age of Empires 2: Definitive Edition). |
'aoe2de' |
| leaderboard_id | int | Leaderboard to extract the data for (Unranked=0, 1v1 Deathmatch=1, Team Deathmatch=2, 1v1 Random Map=3, Team Random Map=4). Defaults to 3. |
None |
| language | str | language for the returned response ('en', 'de', 'el', 'es', 'es-MX', 'fr', 'hi', 'it', 'ja', 'ko', 'ms', 'nl', 'pt', 'ru', 'tr', 'vi', 'zh', 'zh-TW'). Defaults to 'en'. |
None |
| flag | str | boolean to show the player flag. Defaults to 'true'. Needs to be a string for now since requests transforms True boolean to 'True' and the API rejects that. |
'true' |
| search | str | To perform the search for a specific player, from their name. Will return the highest rated player that matches the search. |
None |
| steam_id | int | To perform the search for a specific player, from their steamID64 (ex: 76561199003184910). |
None |
| profile_id | int | To perform the search for a specific player, from their profile ID (ex: 459658). |
None |
Returns:
| Type | Description |
|---|---|
| None | The text content of the response, as a decoded unicode string, with a quick sentence of information about the player. |
Raises:
| Type | Description |
|---|---|
| NightBotError | if the not one of 'search', 'steam_id' or 'profile_id' are provided. |
View Source
def rank(
self,
game: str = "aoe2de",
leaderboard_id: int = 3,
language: str = "en",
flag: str = "true",
search: str | None = None,
steam_id: int | None = None,
profile_id: int | None = None,
) -> str:
"""
Request rank details about a player. Either 'search', 'steam_id' or 'profile_id' required.
Args:
game (str): The game for which to extract the list of strings. Defaults to 'aoe2de'.
Possibilities are 'aoe2hd' (Age of Empires 2: HD Edition) and 'aoe2de' (Age of
Empires 2: Definitive Edition).
leaderboard_id (int): Leaderboard to extract the data for (Unranked=0,
1v1 Deathmatch=1, Team Deathmatch=2, 1v1 Random Map=3, Team Random Map=4).
Defaults to 3.
language (str): language for the returned response ('en', 'de', 'el', 'es', 'es-MX',
'fr', 'hi', 'it', 'ja', 'ko', 'ms', 'nl', 'pt', 'ru', 'tr', 'vi', 'zh', 'zh-TW').
Defaults to 'en'.
flag (str): boolean to show the player flag. Defaults to 'true'. Needs to be a string
for now since requests transforms True boolean to 'True' and the API rejects that.
search (str): To perform the search for a specific player, from their name. Will
return the highest rated player that matches the search.
steam_id (int): To perform the search for a specific player, from their steamID64
(ex: 76561199003184910).
profile_id (int): To perform the search for a specific player, from their profile ID
(ex: 459658).
Raises:
NightBotError: if the not one of 'search', 'steam_id' or 'profile_id' are provided.
Returns:
The text content of the response, as a decoded unicode string, with a quick sentence
of information about the player.
"""
if not any((search, steam_id, profile_id)):
logger.error("Missing one of 'search', 'steam_id', 'profile_id'.")
msg = "Either 'search', 'steam_id' or 'profile_id' required, please provide one."
raise NightBotError(msg)
logger.debug("Preparing parameters for rank details query")
query_params = {
"game": game,
"leaderboard_id": leaderboard_id,
"language": language,
"flag": flag,
"search": search,
"steam_id": steam_id,
"profile_id": profile_id,
}
return _get_request_text_response_decoded(
session=self.session,
url=self.RANK_DETAILS_ENDPOINT,
params=query_params,
timeout=self.timeout,
)