Skip to content

Userstats provider

Userstats - Get game statistics

pythonxbox.api.provider.userstats.UserStatsProvider(client)

Bases: RateLimitedProvider

Source code in src/pythonxbox/api/provider/ratelimitedprovider.py 
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
def __init__(self, client: "XboxLiveClient") -> None:
    """
    Initialize Baseclass

    Args:
        client (:class:`XboxLiveClient`): Instance of XboxLiveClient
    """
    super().__init__(client)

    # Check that RATE_LIMITS set defined in the child class
    if hasattr(self, "RATE_LIMITS"):
        # Note: we cannot check (type(self.RATE_LIMITS) == dict) as the type hints have already defined it as such
        if "burst" and "sustain" in self.RATE_LIMITS:
            # We have the required keys, attempt to parse.
            # (type-checking for the values is performed in __parse_rate_limit_key)
            self.__handle_rate_limit_setup()
        else:
            raise XboxException(
                "RATE_LIMITS object missing required keys 'burst', 'sustain'"
            )
    else:
        raise XboxException(
            "RateLimitedProvider as parent class but RATE_LIMITS not set!"
        )

USERSTATS_URL = 'https://userstats.xboxlive.com' class-attribute instance-attribute

HEADERS_USERSTATS = {'x-xbl-contract-version': '2'} class-attribute instance-attribute

HEADERS_USERSTATS_WITH_METADATA = {'x-xbl-contract-version': '3'} class-attribute instance-attribute

SEPERATOR = ',' class-attribute instance-attribute

RATE_LIMITS = {'burst': 100, 'sustain': 300} class-attribute instance-attribute

get_stats(xuid, service_config_id, stats_fields=None, **kwargs) async

Get userstats

Parameters:

Name Type Description Default
xuid str

Xbox User Id

 required
service_config_id str

Service Config Id of Game (scid)

 required
stats_fields list[GeneralStatsField] | None

List of stats fields to acquire

 None

Returns:

Type Description
UserStatsResponse

class:UserStatsResponse: User Stats Response
Source code in src/pythonxbox/api/provider/userstats/__init__.py 
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
async def get_stats(
    self,
    xuid: str,
    service_config_id: str,
    stats_fields: list[GeneralStatsField] | None = None,
    **kwargs,
) -> UserStatsResponse:
    """
    Get userstats

    Args:
        xuid: Xbox User Id
        service_config_id: Service Config Id of Game (scid)
        stats_fields: List of stats fields to acquire

    Returns:
        :class:`UserStatsResponse`: User Stats Response
    """
    if not stats_fields:
        stats_fields = [GeneralStatsField.MINUTES_PLAYED]
    stats = self.SEPERATOR.join(stats_fields)

    url = f"{self.USERSTATS_URL}/users/xuid({xuid})/scids/{service_config_id}/stats/{stats}"
    resp = await self.client.session.get(
        url,
        headers=self.HEADERS_USERSTATS,
        rate_limits=self.rate_limit_read,
        **kwargs,
    )
    resp.raise_for_status()
    return UserStatsResponse.model_validate_json(resp.text)

get_stats_with_metadata(xuid, service_config_id, stats_fields=None, **kwargs) async

Get userstats including metadata for each stat (if available)

Parameters:

Name Type Description Default
xuid str

Xbox User Id

 required
service_config_id str

Service Config Id of Game (scid)

 required
stats_fields list[GeneralStatsField] | None

List of stats fields to acquire

 None

Returns:

Type Description
UserStatsResponse

class:UserStatsResponse: User Stats Response
Source code in src/pythonxbox/api/provider/userstats/__init__.py 
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
async def get_stats_with_metadata(
    self,
    xuid: str,
    service_config_id: str,
    stats_fields: list[GeneralStatsField] | None = None,
    **kwargs,
) -> UserStatsResponse:
    """
    Get userstats including metadata for each stat (if available)

    Args:
        xuid: Xbox User Id
        service_config_id: Service Config Id of Game (scid)
        stats_fields: List of stats fields to acquire

    Returns:
        :class:`UserStatsResponse`: User Stats Response
    """
    if not stats_fields:
        stats_fields = [GeneralStatsField.MINUTES_PLAYED]
    stats = self.SEPERATOR.join(stats_fields)

    url = f"{self.USERSTATS_URL}/users/xuid({xuid})/scids/{service_config_id}/stats/{stats}"
    params = {"include": "valuemetadata"}
    resp = await self.client.session.get(
        url,
        params=params,
        headers=self.HEADERS_USERSTATS_WITH_METADATA,
        rate_limits=self.rate_limit_read,
        **kwargs,
    )
    resp.raise_for_status()
    return UserStatsResponse.model_validate_json(resp.text)

get_stats_batch(xuids, title_id, stats_fields=None, **kwargs) async

Get userstats in batch mode

Parameters:

Name Type Description Default
xuids list[str]

List of XUIDs to get stats for

 required
title_id str

Game Title Id

 required
stats_fields list[GeneralStatsField] | None

List of stats fields to acquire

 None

Returns:

Type Description
UserStatsResponse

class:UserStatsResponse: User Stats Response
Source code in src/pythonxbox/api/provider/userstats/__init__.py 
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
async def get_stats_batch(
    self,
    xuids: list[str],
    title_id: str,
    stats_fields: list[GeneralStatsField] | None = None,
    **kwargs,
) -> UserStatsResponse:
    """
    Get userstats in batch mode

    Args:
        xuids: List of XUIDs to get stats for
        title_id: Game Title Id
        stats_fields: List of stats fields to acquire

    Returns:
        :class:`UserStatsResponse`: User Stats Response
    """
    if not stats_fields:
        stats_fields = [GeneralStatsField.MINUTES_PLAYED]

    url = self.USERSTATS_URL + "/batch"
    post_data = {
        "arrangebyfield": "xuid",
        "groups": [{"name": "Hero", "titleId": title_id}],
        "stats": [{"name": stat, "titleId": title_id} for stat in stats_fields],
        "xuids": xuids,
    }
    resp = await self.client.session.post(
        url,
        json=post_data,
        headers=self.HEADERS_USERSTATS,
        rate_limits=self.rate_limit_read,
        **kwargs,
    )
    resp.raise_for_status()
    return UserStatsResponse.model_validate_json(resp.text)

get_stats_batch_by_scid(xuids, service_config_id, stats_fields=None, **kwargs) async

Get userstats in batch mode, via scid

Parameters:

Name Type Description Default
xuids list[str]

List of XUIDs to get stats for

 required
service_config_id str

Service Config Id of Game (scid)

 required
stats_fields list[GeneralStatsField] | None

List of stats fields to acquire

 None

Returns:

Type Description
UserStatsResponse

class:UserStatsResponse: User Stats Response
Source code in src/pythonxbox/api/provider/userstats/__init__.py 
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
async def get_stats_batch_by_scid(
    self,
    xuids: list[str],
    service_config_id: str,
    stats_fields: list[GeneralStatsField] | None = None,
    **kwargs,
) -> UserStatsResponse:
    """
    Get userstats in batch mode, via scid

    Args:
        xuids: List of XUIDs to get stats for
        service_config_id: Service Config Id of Game (scid)
        stats_fields: List of stats fields to acquire

    Returns:
        :class:`UserStatsResponse`: User Stats Response
    """
    if not stats_fields:
        stats_fields = [GeneralStatsField.MINUTES_PLAYED]

    url = self.USERSTATS_URL + "/batch"

    post_data = {
        "arrangebyfield": "xuid",
        "groups": [{"name": "Hero", "scid": service_config_id}],
        "stats": [
            {"name": stat, "scid": service_config_id} for stat in stats_fields
        ],
        "xuids": xuids,
    }
    resp = await self.client.session.post(
        url,
        json=post_data,
        headers=self.HEADERS_USERSTATS,
        rate_limits=self.rate_limit_read,
        **kwargs,
    )
    resp.raise_for_status()
    return UserStatsResponse.model_validate_json(resp.text)