Welcome to Xbox WebAPI’s documentation!

Xbox-WebAPI-EX

Latest Version Code Coverage Build Status Documentation Status

Xbox-WebAPI is a python library to authenticate with Xbox Live via your Microsoft Account and provides Xbox related Web-API.

Authentication via credentials or tokens is supported, Two-Factor-Authentication ( 2FA ) is also possible.

Dependencies

  • Python >= 3.5
  • Libraries: requests, demjson, appdirs, urwid

How to use

Install:

pip install xbox-webapi-ex

Authentication:

# Token save location: If tokenfile is not provided via cmdline, fallback
# of <appdirs.user_data_dir>/tokens.json is used as save-location
#
# Specifically:
# Windows: C:\\Users\\<username>\\AppData\\Local\\OpenXbox\\xbox
# Mac OSX: /Users/<username>/Library/Application Support/xbox/tokens.json
# Linux: /home/<username>/.local/share/xbox
#
# For more information, see: https://pypi.org/project/appdirs and module: xbox.webapi.scripts.constants

xbox-authenticate --tokens tokens.json --email no@live.com --password abc123

# NOTE: If no credentials are provided via cmdline, they are requested from stdin
xbox-authenticate --tokens tokens.json

# If you have a shell compatible with ncurses, you can use the Terminal UI app
xbox-auth-ui --tokens tokens.json

Fallback Authentication:

# In case this authentication flow breaks or you do not trust the code with your credentials..
# Open the following URL in your web-browser and authenticate
https://login.live.com/oauth20_authorize.srf?display=touch&scope=service%3A%3Auser.auth.xboxlive.com%3A%3AMBI_SSL&redirect_uri=https%3A%2F%2Flogin.live.com%2Foauth20_desktop.srf&locale=en&response_type=token&client_id=0000000048093EE3

# Once you finished auth and reached a blank page, copy the redirect url from your browser address-field
# Execute the script with supplied redirect url
xbox-auth-via-browser 'https://login.live.com/oauth20_desktop.srf?...access_token=...&refresh_token=...'

Example: Search Xbox Live via cmdline tool:

# Search Xbox One Catalog
xbox-searchlive --tokens tokens.json "Some game title"

# Search Xbox 360 Catalog
xbox-searchlive --tokens tokens.json -l "Some game title"

API usage:

import sys

from xbox.webapi.api.client import XboxLiveClient
from xbox.webapi.authentication.manager import AuthenticationManager
from xbox.webapi.common.exceptions import AuthenticationException

"""
For doing authentication in code, see xbox/webapi/scripts/authenticate.py
or for OAUTH via web-brower, see xbox/webapi/scripts/browserauth.py
"""

try:
  auth_mgr = AuthenticationManager.from_file('/path_to/tokens.json')
except FileNotFoundError as e:
  print(
    'Failed to load tokens from \'{}\'.\n'
    'ERROR: {}'.format(e.filename, e.strerror)
  )
  sys.exit(-1)

try:
  auth_mgr.authenticate(do_refresh=True)
except AuthenticationException as e:
  print('Authentication failed! Err: %s' % e)
  sys.exit(-1)

xbl_client = XboxLiveClient(auth_mgr.userinfo.userhash, auth_mgr.xsts_token.jwt, auth_mgr.userinfo.xuid)

# Some example API calls

# Get friendslist
friendslist = xbl_client.people.get_friends_own()

# Get presence status (by list of XUID)
presence = xbl_client.presence.get_presence_batch([12344567687845, 453486346235151])

# Get messages
messages = xbl_client.message.get_message_inbox()

# Get profile by GT
profile = xbl_client.profile.get_profile_by_gamertag('SomeGamertag')

Screenshots

Here you can see the Auth TUI (Text user interface):

https://raw.githubusercontent.com/OpenXbox/xbox-webapi-python/master/assets/xbox_auth_tui_main.png https://raw.githubusercontent.com/OpenXbox/xbox-webapi-python/master/assets/xbox_auth_tui_2fa.png

Known issues

  • There are a lot of missing XBL endpoints

Contribute

  • Report bugs/suggest features
  • Add/update docs
  • Add additional xbox live endpoints

Credits

This package uses parts of Cookiecutter and the audreyr/cookiecutter-pypackage project template. The authentication code is based on joealcorn/xbox

Informations on endpoints gathered from:

Disclaimer

Xbox, Xbox One, Smartglass and Xbox Live are trademarks of Microsoft Corporation. Team OpenXbox is in no way endorsed by or affiliated with Microsoft Corporation, or any associated subsidiaries, logos or trademarks.

Authentication Manager - Authenticate with MS / XBL

Two Factor Authentication Support

Custom Exceptions

Special Exception subclasses

exception xbox.webapi.common.exceptions.XboxException

Bases: Exception

Base exception for all Xbox exceptions to subclass

exception xbox.webapi.common.exceptions.AuthenticationException

Bases: xbox.webapi.common.exceptions.XboxException

Raised when logging in fails, likely due to incorrect auth credentials

exception xbox.webapi.common.exceptions.TwoFactorAuthRequired(message, server_data)

Bases: xbox.webapi.common.exceptions.XboxException

__init__(message, server_data)

Raised when 2FA is required

Parameters:
  • message (str) – Exception message
  • server_data (dict) – Server data dict, extracted js object from windows live auth request
exception xbox.webapi.common.exceptions.InvalidRequest(message, response)

Bases: xbox.webapi.common.exceptions.XboxException

__init__(message, response)

Raised when something is wrong with the request

Parameters:
  • message (str) – error message returned by the server
  • response (requests.Response) – Instance of requests.Response
exception xbox.webapi.common.exceptions.NotFoundException

Bases: xbox.webapi.common.exceptions.XboxException

Any exception raised due to a resource being missing will subclass this

Xbox Live Client - HTTP Client wrapper

Xbox Live Client

Basic factory that stores XboxLiveLanguage, User authorization data and available Providers

class xbox.webapi.api.client.XboxLiveClient(userhash, auth_token, xuid, language=<xbox.webapi.api.language.XboxLiveLocale object>)

Bases: object

__init__(userhash, auth_token, xuid, language=<xbox.webapi.api.language.XboxLiveLocale object>)

Provide various Web API from Xbox Live

Parameters:
  • userhash (str) – Userhash obtained by authentication with Xbox Live Server
  • auth_token (str) – Authentication Token (XSTS), obtained by authentication with Xbox Live Server
  • xuid (str/int) – Xbox User Identification of your Xbox Live Account
  • language (str) – Member of XboxLiveLanguage
xuid

Gets the Xbox User ID

Returns:Xbox User ID
Return type:int
language

Gets the active Xbox Live Language

Returns:Active Xbox Live language
Return type:XboxLiveLanguage
session

Wrapper around requests session

Returns:Instance of requests.session - Xbox Live Authorization header is set.
Return type:object

Xbox Live language definitions

Language definitions

class xbox.webapi.api.language.XboxLiveLocale(name, short_id, identifier, locale)

Bases: object

__init__(name, short_id, identifier, locale)

Initialize a new instance of XboxLiveLocale

Parameters:
  • name (str) – Full name describing the language / country
  • short_id (str) – Short Id (e.g. “AT” for Austria)
  • identifier (str) – Identifier (e.g. “de_AT” for Austria)
  • locale (str) – Locale (e.g. “de-AT” for Austria)
class xbox.webapi.api.language.XboxLiveLanguage

Bases: object

Collection of languages compatible with XBL

Argentina = <xbox.webapi.api.language.XboxLiveLocale object>
Australia = <xbox.webapi.api.language.XboxLiveLocale object>
Austria = <xbox.webapi.api.language.XboxLiveLocale object>
Belgium = <xbox.webapi.api.language.XboxLiveLocale object>
Belgium_NL = <xbox.webapi.api.language.XboxLiveLocale object>
Brazil = <xbox.webapi.api.language.XboxLiveLocale object>
Canada = <xbox.webapi.api.language.XboxLiveLocale object>
Canada_FR = <xbox.webapi.api.language.XboxLiveLocale object>
Czech_Republic = <xbox.webapi.api.language.XboxLiveLocale object>
Denmark = <xbox.webapi.api.language.XboxLiveLocale object>
Finland = <xbox.webapi.api.language.XboxLiveLocale object>
France = <xbox.webapi.api.language.XboxLiveLocale object>
Germany = <xbox.webapi.api.language.XboxLiveLocale object>
Greece = <xbox.webapi.api.language.XboxLiveLocale object>
Hong_Kong = <xbox.webapi.api.language.XboxLiveLocale object>
Hungary = <xbox.webapi.api.language.XboxLiveLocale object>
India = <xbox.webapi.api.language.XboxLiveLocale object>
Great_Britain = <xbox.webapi.api.language.XboxLiveLocale object>
Israel = <xbox.webapi.api.language.XboxLiveLocale object>
Italy = <xbox.webapi.api.language.XboxLiveLocale object>
Japan = <xbox.webapi.api.language.XboxLiveLocale object>
Mexico = <xbox.webapi.api.language.XboxLiveLocale object>
Chile = <xbox.webapi.api.language.XboxLiveLocale object>
Colombia = <xbox.webapi.api.language.XboxLiveLocale object>
Netherlands = <xbox.webapi.api.language.XboxLiveLocale object>
New_Zealand = <xbox.webapi.api.language.XboxLiveLocale object>
Norway = <xbox.webapi.api.language.XboxLiveLocale object>
Poland = <xbox.webapi.api.language.XboxLiveLocale object>
Portugal = <xbox.webapi.api.language.XboxLiveLocale object>
Russia = <xbox.webapi.api.language.XboxLiveLocale object>
Saudi_Arabia = <xbox.webapi.api.language.XboxLiveLocale object>
Singapore = <xbox.webapi.api.language.XboxLiveLocale object>
Slovakia = <xbox.webapi.api.language.XboxLiveLocale object>
South_Africa = <xbox.webapi.api.language.XboxLiveLocale object>
Korea = <xbox.webapi.api.language.XboxLiveLocale object>
Spain = <xbox.webapi.api.language.XboxLiveLocale object>
Switzerland = <xbox.webapi.api.language.XboxLiveLocale object>
Switzerland_FR = <xbox.webapi.api.language.XboxLiveLocale object>
United_Arab_Emirates = <xbox.webapi.api.language.XboxLiveLocale object>
United_States = <xbox.webapi.api.language.XboxLiveLocale object>
Ireland = <xbox.webapi.api.language.XboxLiveLocale object>

Xbox Live Providers - API Endpoints

Submodules
EDS - Entertainment Discovery Services

EDS (Entertainment Discovery Services)

Used for searching the Xbox Live Marketplace

class xbox.webapi.api.provider.eds.EDSProvider(client)

Bases: xbox.webapi.api.provider.baseprovider.BaseProvider

EDS_URL = 'https://eds.xboxlive.com'
HEADERS_EDS = {'Accept': 'application/json', 'Cache-Control': 'no-cache', 'Pragma': 'no-cache', 'x-xbl-client-type': 'Companion', 'x-xbl-client-version': '2.0', 'x-xbl-contract-version': '3.2', 'x-xbl-device-type': 'WindowsPhone', 'x-xbl-isautomated-client': 'true'}
SEPERATOR = '.'
get_appchannel_channel_list(lineup_id)

Get AppChannel channel list

Parameters:lineup_id (str) – Lineup ID
Returns:HTTP Response
Return type:requests.Response
get_appchannel_schedule(lineup_id, start_time, end_time, max_items, skip_items)

Get AppChannel schedule / EPG

Parameters:
  • lineup_id (str) – Lineup ID
  • start_time (str) – Start time (format: 2016-07-11T21:50:00.000Z)
  • end_time (str) – End time (format: 2016-07-11T21:50:00.000Z)
  • max_items (int) – Maximum number of items
  • skip_items (int) – Count of items to skip
Returns:

HTTP Response
Return type:

requests.Response
get_browse_query(order_by, desired, **kwargs)

Get a browse query

Parameters:
  • order_by (str/OrderBy) – Fieldname to use for sorting the result
  • desired (str/list) – Desired Media Item Types, members of (MediaItemType)
  • **kwargs – Additional query parameters

Returns:

get_recommendations(desired, **kwargs)

Get recommended content suggestions

Parameters:
  • desired (str/list) – Desired Media Item Types, members of (MediaItemType)
  • **kwargs – Additional query parameters
Returns:

HTTP Response
Return type:

requests.Response

Get related content for a specific Id

Parameters:
  • id (str) – Id of original content to get related content for
  • desired (str/list) – Desired Media Item Types, members of (MediaItemType)
  • **kwargs – Additional query parameters
Returns:

HTTP Response
Return type:

requests.Response
get_fields(desired, **kwargs)

Get Fields

Parameters:
  • desired (str) – Desired
  • **kwargs – Additional query parameters
Returns:

HTTP Response
Return type:

requests.Response
get_details(ids, mediagroup, **kwargs)

Get details for a list of IDs in a specific media group

Parameters:
  • ids (str/list) – List of ids to get details for
  • mediagroup (str) – Member of MediaGroup
  • **kwargs – Additional query parameters
Returns:

HTTP Response
Return type:

requests.Response

Do a crossmedia-group search (search for content for multiple devices)

Parameters:
  • search_query (str) – Query string
  • max_items (int) – Maximum itemcount
  • **kwargs – Additional query parameters
Returns:

HTTP Response
Return type:

requests.Response

Do a singlemedia-group search

Parameters:
  • search_query (str) – Query string
  • max_items (int) – Maximum itemcount
  • media_item_types (str/list) – Desired Media Item Types, members of (MediaItemType)
  • **kwargs – Additional query parameters
Returns:

HTTP Response
Return type:

requests.Response
class xbox.webapi.api.provider.eds.MediaItemType

Bases: xbox.webapi.common.enum.StrEnum

Media Item Type, used as parameter for EDS API

XBOX360_GAME = 'Xbox360Game'
XBOX360_GAME_CONTENT = 'Xbox360GameContent'
XBOX360_GAME_DEMO = 'Xbox360GameDemo'
XBOX_GAME_TRIAL = 'XboxGameTrial'
XBOX_THEME = 'XboxTheme'
XBOX_ORIGINAL_GAME = 'XboxOriginalGame'
XBOX_GAMER_TILE = 'XboxGamerTile'
XBOX_ARCADE_GAME = 'XboxArcadeGame'
XBOX_GAME_CONSUMABLE = 'XboxGameConsumable'
XBOX_GAME_VIDEO = 'XboxGameVideo'
XBOX_GAME_TRAILER = 'XboxGameTrailer'
XBOX_BUNDLE = 'XboxBundle'
XBOX_XNA_GAME = 'XboxXnaCommunityGame'
XBOX_MARKETPLACE = 'XboxMarketplace'
XBOX_APP = 'XboxApp'
XBOXONE_GAME = 'DGame'
XBOXONE_GAME_DEMO = 'DGameDemo'
XBOXONE_CONSUMABLE = 'DConsumable'
XBOXONE_DURABLE = 'DDurable'
XBOXONE_APP = 'DApp'
XBOXONE_ACTIVITY = 'DActivity'
XBOXONE_NATIVE_APP = 'DNativeApp'
METRO_GAME = 'MetroGame'
METRO_GAME_CONTENT = 'MetroGameContent'
METRO_GAME_CONSUMABLE = 'MetroGameConsumable'
AVATAR_ITEM = 'AvatarItem'
MOBILE_GAME = 'MobileGame'
XBOX_MOBILE_PDLC = 'XboxMobilePDLC'
XBOX_MOBILE_CONSUMABLE = 'XboxMobileConsumable'
TV_SHOW = 'TVShow'
TV_EPISODE = 'TVEpisode'
TV_SERIES = 'TVSeries'
TV_SEASON = 'TVSeason'
MUSIC_ALBUM = 'Album'
MUSIC_TRACK = 'Track'
MUSIC_VIDEO = 'MusicVideo'
MUSIC_ARTIST = 'MusicArtist'
WEB_GAME = 'WebGame'
WEB_VIDEO = 'WebVideo'
WEB_VIDEO_COLLECTION = 'WebVideoCollection'
GAME_LAYER = 'GameLayer'
GAME_ACTIVITY = 'GameActivity'
APP_ACTIVITY = 'AppActivity'
VIDEO_LAYER = 'VideoLayer'
VIDEO_ACTIVITY = 'VideoActivity'
SUBSCRIPTION = 'Subscription'
class xbox.webapi.api.provider.eds.MediaGroup

Bases: xbox.webapi.common.enum.StrEnum

Media Group, used as parameter for EDS API

GameType: Xbox360Game, XboxGameTrial, Xbox360GameContent, Xbox360GameDemo, XboxTheme, XboxOriginalGame, XboxGamerTile, XboxArcadeGame, XboxGameConsumable, XboxGameVideo, XboxGameTrailer, XboxBundle, XboxXnaCommunityGame, XboxMarketplace, AvatarItem, MobileGame, XboxMobilePDLC, XboxMobileConsumable, WebGame, MetroGame, MetroGameContent, MetroGameConsumable, DGame, DGameDemo, DConsumable, DDurable

AppType: XboxApp, DApp MovieType: Movie TVType: TVShow (one-off TV shows), TVEpisode, TVSeries, TVSeason MusicType: Album, Track, MusicVideo MusicArtistType: MusicArtist WebVideoType: WebVideo, WebVideoCollection EnhancedContentType: GameLayer, GameActivity, AppActivity, VideoLayer, VideoActivity, DActivity, DNativeApp SubscriptionType: Subscription

GAME_TYPE = 'GameType'
APP_TYPE = 'AppType'
MOVIE_TYPE = 'MovieType'
TV_TYPE = 'TVType'
MUSIC_TYPE = 'MusicType'
MUSIC_ARTIST_TYPE = 'MusicArtistType'
WEB_VIDEO_TYPE = 'WebVideoType'
ENHANCED_CONTENT_TYPE = 'EnhancedContentType'
SUBSCRIPTION_TYPE = 'SubscriptionType'
class xbox.webapi.api.provider.eds.ScheduleDetailsField

Bases: xbox.webapi.common.enum.StrEnum

Schedule Details Field, used as parameter for EDS API

NAME = 'Name'
ID = 'Id'
IMAGES = 'Images'
DESCRIPTION = 'Description'
PARENTAL_RATING = 'ParentalRating'
PARENT_SERIES = 'ParentSeries'
SCHEDULE_INFO = 'ScheduleInformation'
class xbox.webapi.api.provider.eds.Domain

Bases: xbox.webapi.common.enum.StrEnum

Domain, used as parameter for EDS API

XBOX_360 = 'Xbox360'
XBOX_ONE = 'Modern'
class xbox.webapi.api.provider.eds.IdType

Bases: xbox.webapi.common.enum.StrEnum

ID Type, used as parameter for EDS API

CANONICAL = 'Canonical'
XBOX_HEX_TITLE = 'XboxHexTitle'
SCOPED_MEDIA_ID = 'ScopedMediaId'
ZUNE_CATALOG = 'ZuneCatalog'
ZUNE_MEDIA_INSTANCE = 'ZuneMediaInstance'
AMG = 'AMG'
MEDIA_NET = 'MediaNet'
PROVIDER_CONTENT_ID = 'ProviderContentId'
class xbox.webapi.api.provider.eds.ClientType

Bases: xbox.webapi.common.enum.StrEnum

Client Type, used as parameter for EDS API

C13 = 'C13'
COMMERCIAL_SERVICE = 'CommercialService'
COMPANION = 'Companion'
CONSOLE = 'Console'
EDITORIAL = 'Editorial'
FIRST_PARTY_APP = '1stPartyApp'
MO_LIVE = 'MoLive'
WINDOWS_PHONE_7 = 'PhoneROM'
RECOMMENDATION_SERVICE = 'RecommendationService'
SAS = 'SAS'
SDS = 'SDS'
SUBSCRIPTION_SERVICE = 'SubscriptionService'
X8 = 'X8'
X13 = 'X13'
WEBBLEND = 'Webblend'
XBOX_COM = 'XboxCom'
class xbox.webapi.api.provider.eds.DeviceType

Bases: xbox.webapi.common.enum.StrEnum

Device Type, used as parameter for EDS API

XBOX360 = 'Xbox360'
XBOXONE = 'XboxDurango'
XBOX = 'Xbox'
IOS = 'iOS'
IPHONE = 'iPhone'
IPAD = 'iPad'
ANDROID = 'Android'
ANDROID_PHONE = 'AndroidPhone'
ANDROID_SLATE = 'AndroidSlate'
WIN_PC = 'WindowsPC'
WIN_PHONE = 'WindowsPhone'
SERVICE = 'Service'
WEB = 'Web'
class xbox.webapi.api.provider.eds.OrderBy

Bases: xbox.webapi.common.enum.StrEnum

The orderBy parameter determines how the items being returned should be sorted

PLAY_COUNT_DAILY = 'PlayCountDaily'
FREE_AND_PAID_COUNT_DAILY = 'FreeAndPaidCountDaily'
PAID_COUNT_ALL_TIME = 'PaidCountAllTime'
PAID_COUNT_DAILY = 'PaidCountDaily'
DIGITAL_RELEASE_DATE = 'DigitalReleaseDate'
RELEASE_DATE = 'ReleaseDate'
USER_RATINGS = 'UserRatings'
class xbox.webapi.api.provider.eds.SubscriptionLevel

Bases: xbox.webapi.common.enum.StrEnum

The subscriptionLevel parameter determines the type of subscription the user has

GOLD = 'gold'
SILVER = 'silver'
CQS - Stump TV Streaming

CQS

Used for download stump (TV Streaming) data (RemoteTVInput ServiceChannel on Smartglass)

class xbox.webapi.api.provider.cqs.CQSProvider(client)

Bases: xbox.webapi.api.provider.baseprovider.BaseProvider

CQS_URL = 'https://cqs.xboxlive.com'
HEADERS_CQS = {'Accept': 'application/json', 'Cache-Control': 'no-cache', 'Pragma': 'no-cache', 'x-xbl-client-type': 'Companion', 'x-xbl-client-version': '2.0', 'x-xbl-contract-version': '1.b', 'x-xbl-device-type': 'WindowsPhone', 'x-xbl-isautomated-client': 'true'}
get_channel_list(locale_info, headend_id)

Get stump channel list

Parameters:
  • locale_info (str) – Locale string (format: “en-US”)
  • headend_id (str) – Headend id
Returns:

HTTP Response
Return type:

requests.Response
get_schedule(locale_info, headend_id, start_date, duration_minutes, channel_skip, channel_count)

Get stump epg data

Parameters:
  • locale_info (str) – Locale string (format: “en-US”)
  • headend_id (str) – Headend id
  • start_date (str) – Start date (format: 2016-07-11T21:50:00.000Z)
  • duration_minutes (int) – Schedule duration to download
  • channel_skip (int) – Count of channels to skip
  • channel_count (int) – Count of channels to get data for
Returns:

HTTP Response
Return type:

requests.Response
class xbox.webapi.api.provider.cqs.VesperType

Bases: xbox.webapi.common.enum.StrEnum

An enumeration.

MOBILE_LINEUP = 'vesper_mobile_lineup'
MOBILE_SCHEDULE = 'vesper_mobile_schedule'
EPLists - Manage Xbox Live Pins

EPLists - Mainly used for XBL Pins

class xbox.webapi.api.provider.lists.ListsProvider(client)

Bases: xbox.webapi.api.provider.baseprovider.BaseProvider

LISTS_URL = 'https://eplists.xboxlive.com'
HEADERS_LISTS = {'Content-Type': 'application/json', 'x-xbl-contract-version': '2'}
SEPERATOR = '.'
remove_items(xuid, params, listname='XBLPins')

Remove items from specific list, defaults to “XBLPins”

Parameters:
  • xuid (str/int) – Xbox User Id
  • listname (str) – Name of list to edit
Returns:

HTTP Response
Return type:

requests.Response
get_items(xuid, params, listname='XBLPins')

Get items from specific list, defaults to “XBLPins”

Parameters:
  • xuid (str/int) – Xbox User Id
  • listname (str) – Name of list to edit
Returns:

HTTP Response
Return type:

requests.Response
insert_items(xuid, params, listname='XBLPins')

Insert items to specific list, defaults to “XBLPins”

Parameters:
  • xuid (str/int) – Xbox User Id
  • listname (str) – Name of list to edit
Returns:

HTTP Response
Return type:

requests.Response
update_items(xuid, params, listname='XBLPins')

Update items in specific list, defaults to “XBLPins”

Parameters:
  • xuid (str/int) – Xbox User Id
  • listname (str) – Name of list to edit
Returns:

HTTP Response
Return type:

requests.Response
Profile - Get Userprofile information

Profile

Get Userprofiles by XUID or Gamertag

class xbox.webapi.api.provider.profile.ProfileProvider(client)

Bases: xbox.webapi.api.provider.baseprovider.BaseProvider

PROFILE_URL = 'https://profile.xboxlive.com'
HEADERS_PROFILE = {'x-xbl-contract-version': '2'}
SEPARATOR = ','
get_profiles(xuid_list)

Get profile info for list of xuids

Parameters:xuid_list (list) – List of xuids
Returns:HTTP Response
Return type:requests.Response
get_profile_by_xuid(target_xuid)

Get Userprofile by xuid

Parameters:target_xuid (int) – XUID to get profile for
Returns:HTTP Response
Return type:requests.Response
get_profile_by_gamertag(gamertag)

Get Userprofile by gamertag

Parameters:gamertag (str) – Gamertag to get profile for
Returns:HTTP Response
Return type:requests.Response
class xbox.webapi.api.provider.profile.ProfileSettings

Bases: object

Profile settings, used as parameter for Profile API

GAME_DISPLAY_NAME = 'GameDisplayName'
APP_DISPLAY_NAME = 'AppDisplayName'
APP_DISPLAYPIC_RAW = 'AppDisplayPicRaw'
GAME_DISPLAYPIC_RAW = 'GameDisplayPicRaw'
PUBLIC_GAMERPIC = 'PublicGamerpic'
SHOW_USER_AS_AVATAR = 'ShowUserAsAvatar'
GAMERSCORE = 'Gamerscore'
GAMERTAG = 'Gamertag'
ACCOUNT_TIER = 'AccountTier'
TENURE_LEVEL = 'TenureLevel'
XBOX_ONE_REP = 'XboxOneRep'
PREFERRED_COLOR = 'PreferredColor'
LOCATION = 'Location'
BIOGRAPHY = 'Bio'
WATERMARKS = 'Watermarks'
REAL_NAME = 'RealName'
REAL_NAME_OVERRIDE = 'RealNameOverride'
Achievements - Get info about gameprogress

Achievements

Get Xbox 360 and Xbox One Achievement data

class xbox.webapi.api.provider.achievements.AchievementsProvider(client)

Bases: xbox.webapi.api.provider.baseprovider.BaseProvider

ACHIEVEMENTS_URL = 'https://achievements.xboxlive.com'
HEADERS_GAME_360_PROGRESS = {'x-xbl-contract-version': '1'}
HEADERS_GAME_PROGRESS = {'x-xbl-contract-version': '2'}
get_achievements_detail_item(xuid, service_config_id, achievement_id)

Get achievement detail for specific item

Parameters:
  • xuid (str) – Xbox User Id
  • service_config_id (str) – Service Config Id
  • achievement_id (str) – Achievement Id
Returns:

HTTP Response
Return type:

requests.Response
get_achievements_xbox360_all(xuid, title_id)

Get all achievements for specific X360 title Id

Parameters:
  • xuid (str) – Xbox User Id
  • title_id (str) – Xbox 360 Title Id
Returns:

HTTP Response
Return type:

requests.Response
get_achievements_xbox360_earned(xuid, title_id)

Get earned achievements for specific X360 title id

Parameters:
  • xuid (str) – Xbox User Id
  • title_id (str) – Xbox 360 Title Id
Returns:

HTTP Response
Return type:

requests.Response
get_achievements_xbox360_recent_progress_and_info(xuid)

Get recent achievement progress and information

Parameters:xuid (str) – Xbox User Id
Returns:HTTP Response
Return type:requests.Response
get_achievements_xboxone_gameprogress(xuid, title_id)

Get gameprogress for Xbox One title

Parameters:
  • xuid (str) – Xbox User Id
  • title_id (str) – Xbox One Title Id
Returns:

HTTP Response
Return type:

requests.Response
get_achievements_xboxone_recent_progress_and_info(xuid)

Get recent achievement progress and information

Parameters:xuid (str) – Xbox User Id
Returns:HTTP Response
Return type:requests.Response
Usersearch - Search users / gamertags

Usersearch - Search for gamertags / userprofiles

class xbox.webapi.api.provider.usersearch.UserSearchProvider(client)

Bases: xbox.webapi.api.provider.baseprovider.BaseProvider

USERSEARCH_URL = 'https://usersearch.xboxlive.com'

Get userprofiles for search query

Parameters:query (str) – Search query
Returns:HTTP Response
Return type:requests.Response
Gameclips - Own, from Community, by XUID

Gameclips - Get gameclip info

class xbox.webapi.api.provider.gameclips.GameclipProvider(client)

Bases: xbox.webapi.api.provider.baseprovider.BaseProvider

GAMECLIPS_METADATA_URL = 'https://gameclipsmetadata.xboxlive.com'
HEADERS_GAMECLIPS_METADATA = {'x-xbl-contract-version': '1'}
get_recent_community_clips_by_title_id(title_id)

Get recent community clips by Title Id

Parameters:title_id (str) – Title Id to get clips for
Returns:HTTP Response
Return type:requests.Response
get_recent_own_clips(title_id=None, skip_items=0, max_items=25)

Get own recent clips, optionally filter for title Id

Parameters:
  • title_id (int) – Title ID to filter
  • skip_items (int) – Item count to skip
  • max_items (int) – Maximum item count to load
Returns:

HTTP Response
Return type:

requests.Response
get_recent_clips_by_xuid(xuid, title_id=None, skip_items=0, max_items=25)

Get clips by XUID, optionally filter for title Id

Parameters:
  • xuid (str) – XUID of user to get clips from
  • title_id (str) – Optional title id filter
  • skip_items (int) – Item count to skip
  • max_items (int) – Maximum item count to load
Returns:

HTTP Response
Return type:

requests.Response
get_saved_community_clips_by_title_id(title_id)

Get saved community clips by Title Id

Parameters:title_id (str) – Title Id to get screenshots for
Returns:HTTP Response
Return type:requests.Response
get_saved_own_clips(title_id=None, skip_items=0, max_items=25)

Get own saved clips, optionally filter for title Id an

Parameters:
  • title_id (int) – Optional Title ID to filter
  • skip_items (int) – Item count to skip
  • max_items (int) – Maximum item count to load
Returns:

HTTP Response
Return type:

requests.Response
get_saved_clips_by_xuid(xuid, title_id=None, skip_items=0, max_items=25)

Get saved clips by XUID, optionally filter for title Id

Parameters:
  • xuid (str) – XUID of user to get screenshots from
  • title_id (str) – Optional title id filter
  • skip_items (int) – Item count to skip
  • max_items (int) – Maximum item count to load
Returns:

HTTP Response
Return type:

requests.Response
People - Get friendlist info

People - Access friendlist from own profiles and others

class xbox.webapi.api.provider.people.PeopleProvider(client)

Bases: xbox.webapi.api.provider.baseprovider.BaseProvider

SOCIAL_URL = 'https://social.xboxlive.com'
HEADERS_SOCIAL = {'x-xbl-contract-version': '1'}
get_friends_own()

Get friendlist of own profile

Returns:HTTP Response
Return type:requests.Response
get_friends_summary_own()

Get friendlist summary of own profile

Returns:HTTP Response
Return type:requests.Response
get_friends_summary_by_xuid(xuid)

Get friendlist summary of user by xuid

Parameters:xuid (str) – XUID to request summary from
Returns:HTTP Response
Return type:requests.Response
get_friends_by_xuid(xuid)

Get friendlist of user by xuid

Parameters:xuid (str) – XUID to request summary from
Returns:HTTP Response
Return type:requests.Response
get_friends_summary_by_gamertag(gamertag)

Get friendlist summary of user by xuid

Parameters:gamertag (str) – XUID to request friendlist from
Returns:HTTP Response
Return type:requests.Response
get_friends_own_batch(xuids)

Get friends metadata by providing a list of XUIDs

Parameters:xuids (list) – List of XUIDs
Returns:HTTP Response
Return type:requests.Response
Presence - Get online status of friends

Presence - Get online status of friends

class xbox.webapi.api.provider.presence.PresenceLevel

Bases: object

USER = 'user'
DEVICE = 'device'
TITLE = 'title'
ALL = 'all'
class xbox.webapi.api.provider.presence.PresenceProvider(client)

Bases: xbox.webapi.api.provider.baseprovider.BaseProvider

PRESENCE_URL = 'https://userpresence.xboxlive.com'
HEADERS_PRESENCE = {'Accept': 'application/json', 'x-xbl-contract-version': '3'}
get_presence(xuid, presence_level='user')

Get presence for an xuid

Parameters:
  • xuid (str) – Xbox User Id
  • presence_level (str) – Filter level
Returns:

HTTP Response
Return type:

requests.Response
get_presence_batch(xuids, online_only=False, presence_level='user')

Get presence for list of xuids

Parameters:
  • xuids (str) – List of XUIDs
  • online_only (bool) – Only get online profiles
  • presence_level (str) – Filter level
Returns:

HTTP Response
Return type:

requests.Response
get_presence_own(presence_level='all')

Get presence of own profile

Parameters:presence_level (str) – Filter level
Returns:HTTP Response
Return type:requests.Response
Message - Read and send messages

Message - Read and send messages

class xbox.webapi.api.provider.message.MessageProvider(client)

Bases: xbox.webapi.api.provider.baseprovider.BaseProvider

MSG_URL = 'https://msg.xboxlive.com'
HEADERS_MESSAGE = {'x-xbl-contract-version': '1'}
get_message_inbox(skip_items=0, max_items=100)

Get messages

Parameters:
  • skip_items (int) – Item count to skip
  • max_items (int) – Maximum item count to load
Returns:

HTTP Response
Return type:

requests.Response
get_message(message_id)

Get detailed message info

Parameters:message_id (str) – Message Id
Returns:HTTP Response
Return type:requests.Response
delete_message(message_id)

Delete message

NOTE: Returns HTTP Status Code 204 on success

Parameters:message_id (str) – Message Id
Returns:HTTP Response
Return type:requests.Response
send_message(message_text, gamertags=None, xuids=None)

Send message to a list of gamertags

Only one of each recipient types can be supplied, either gamertags or xuids

Parameters:gamertags (list) – List of gamertags
Returns:HTTP Response
Return type:requests.Response
Userstats - Get game statistics

Userstats - Get game statistics

class xbox.webapi.api.provider.userstats.UserStatsProvider(client)

Bases: xbox.webapi.api.provider.baseprovider.BaseProvider

USERSTATS_URL = 'https://userstats.xboxlive.com'
HEADERS_USERSTATS = {'x-xbl-contract-version': '2'}
HEADERS_USERSTATS_WITH_METADATA = {'x-xbl-contract-version': '3'}
SEPERATOR = ','
get_stats(xuid, service_config_id, stats_fields=None)

Get userstats

Parameters:
  • xuid (str) – Xbox User Id
  • service_config_id (str) – Service Config Id of Game (scid)
  • stats_fields (list) – List of stats fields to acquire
Returns:

HTTP Response
Return type:

requests.Response
get_stats_with_metadata(xuid, service_config_id, stats_fields=None)

Get userstats including metadata for each stat (if available)

Parameters:
  • xuid (str) – Xbox User Id
  • service_config_id (str) – Service Config Id of Game (scid)
  • stats_fields (list) – List of stats fields to acquire
Returns:

HTTP Response
Return type:

requests.Response
get_stats_batch(xuids, title_id, stats_fields=None)

Get userstats in batch mode

Parameters:
  • xuids (list) – List of XUIDs to get stats for
  • title_id (int) – Game Title Id
  • stats_fields (list) – List of stats fields to acquire
Returns:

HTTP Response
Return type:

requests.Response
get_stats_batch_by_scid(xuids, service_config_id, stats_fields=None)

Get userstats in batch mode, via scid

Parameters:
  • xuids (list) – List of XUIDs to get stats for
  • service_config_id (int) – Service Config Id of Game (scid)
  • stats_fields (list) – List of stats fields to acquire
Returns:

HTTP Response
Return type:

requests.Response
class xbox.webapi.api.provider.userstats.GeneralStatsField

Bases: object

MINUTES_PLAYED = 'MinutesPlayed'
Screenshots - Get screenshot info

Screenshots - Get screenshot info

class xbox.webapi.api.provider.screenshots.ScreenshotsProvider(client)

Bases: xbox.webapi.api.provider.baseprovider.BaseProvider

SCREENSHOTS_METADATA_URL = 'https://screenshotsmetadata.xboxlive.com'
HEADERS_SCREENSHOTS_METADATA = {'x-xbl-contract-version': '5'}
get_recent_community_screenshots_by_title_id(title_id)

Get recent community screenshots by Title Id

Parameters:title_id (str) – Title Id to get screenshots for
Returns:HTTP Response
Return type:requests.Response
get_recent_own_screenshots(title_id=None, skip_items=0, max_items=25)

Get own recent screenshots, optionally filter for title Id

Parameters:
  • title_id (int) – Title ID to filter
  • skip_items (int) – Item count to skip
  • max_items (int) – Maximum item count to load
Returns:

HTTP Response
Return type:

requests.Response
get_recent_screenshots_by_xuid(xuid, title_id=None, skip_items=0, max_items=25)

Get recent screenshots by XUID, optionally filter for title Id

Parameters:
  • xuid (str) – XUID of user to get screenshots from
  • title_id (str) – Optional title id filter
  • skip_items (int) – Item count to skip
  • max_items (int) – Maximum item count to load
Returns:

HTTP Response
Return type:

requests.Response
get_saved_community_screenshots_by_title_id(title_id)

Get saved community screenshots by Title Id

Parameters:title_id (str) – Title Id to get screenshots for
Returns:HTTP Response
Return type:requests.Response
get_saved_own_screenshots(title_id=None, skip_items=0, max_items=25)

Get own saved screenshots, optionally filter for title Id an

Parameters:
  • title_id (int) – Optional Title ID to filter
  • skip_items (int) – Item count to skip
  • max_items (int) – Maximum item count to load
Returns:

HTTP Response
Return type:

requests.Response
get_saved_screenshots_by_xuid(xuid, title_id=None, skip_items=0, max_items=25)

Get saved screenshots by XUID, optionally filter for title Id

Parameters:
  • xuid (str) – XUID of user to get screenshots from
  • title_id (str) – Optional title id filter
  • skip_items (int) – Item count to skip
  • max_items (int) – Maximum item count to load
Returns:

HTTP Response
Return type:

requests.Response
Titlehub - Get Title history and info

Titlehub - Get Title history and info

class xbox.webapi.api.provider.titlehub.TitleFields

Bases: object

ACHIEVEMENT = 'achievement'
IMAGE = 'image'
FRIENDS_WHO_PLAYED = 'friendswhoplayed'
SERVICE_CONFIG_ID = 'SCID'
DETAIL = 'detail'
ALTERNATE_TITLE_ID = 'alternateTitleId'
class xbox.webapi.api.provider.titlehub.TitlehubProvider(client)

Bases: xbox.webapi.api.provider.baseprovider.BaseProvider

TITLEHUB_URL = 'https://titlehub.xboxlive.com'
HEADERS_TITLEHUB = {'Accept-Language': 'overwrite in __init__', 'x-xbl-client-name': 'XboxApp', 'x-xbl-client-type': 'UWA', 'x-xbl-client-version': '39.39.22001.0', 'x-xbl-contract-version': '2'}
SEPARATOR = ','
__init__(client)

Initialize Baseclass, set ‘Accept-Language’ header from client instance

Parameters:client (XboxLiveClient) – Instance of client
get_title_history(xuid, fields=None, max_items=5)

Get recently played titles

Parameters:
  • xuid (int/str) – Xuid
  • fields (list) – Members of TitleFields
  • max_items (int) – Maximum items
Returns:

HTTP Response
Return type:

requests.Response
get_title_info(title_id, fields=None)

Get info for specific title

Parameters:
Returns:

HTTP Response
Return type:

requests.Response
get_titles_batch(pfns, fields=None)

Get Title info via PFN ids

Parameters:
  • pfns (list) – PFN Id strings (e.g. ‘Microsoft.XboxApp_8wekyb3d8bbwe’)
  • fields (list) – Members of TitleFields
Returns:

HTTP Response
Return type:

requests.Response
Module contents

Indices and tables