Xbox Live - API
Simple Xbox Live API wrapper.
Warning
This module MUST be used server side only to prevent CORS issues and credentials leak.
Installation
$ npm install @xboxreplay/xboxlive-apiExample usage
import XboxLiveAPI from '@xboxreplay/xboxlive-api';
XboxLiveAPI.getPlayerSettings('Zeny IC', {
userHash: 'YOUR_OWN_USER_HASH',
XSTSToken: 'YOUR_OWN_XSTS_TOKEN'
}, ['UniqueModernGamertag', 'GameDisplayPicRaw', 'Gamerscore', 'Location'])
.then(console.info)
.catch(console.error);Sample response:
[
{
"id": "UniqueModernGamertag",
"value": "Zeny IC"
},
{
"id": "GameDisplayPicRaw",
"value": "http://images-eds.xboxlive.com/image?url=wHwbXKif8cus8csoZ03RWwcxuUQ9WVT6xh5XaeeZD02wEfGZeuD.XMoGFVYkwHDq4Ch7pcu9E3UwDqy.fzrTaviUvY1c8gvrWRzLTqFKUVap_Nvh0.Em2IsAWtHcMFeVpY2boMYiy03w887.tSGAT62Na2z3k33eMWnP12mY2x0-&format=png"
}
{
"id": "Gamerscore",
"value": "5610"
},
{
"id": "Location",
"value": "Paris, France"
}
]How to generate a Xbox Live authorization?
The fastest way to generate a valid authorization is to use our XboxLive-Auth module which returns an userHash and a XSTSToken for a specified account.
Available methods
getPlayerXUID - Returns targeted player's XUID:
getPlayerXUID(
gamertagOrXUID: string;
authorization: {
userHash: string;
XSTSToken: string;
};
): Promise<string>getPlayerSettings - Returns targeted player's settings:
getPlayerSettings(
gamertagOrXUID: string;
authorization: {
userHash: string;
XSTSToken: string;
};
settings?: [
| 'GameDisplayPicRaw'
| 'Gamerscore'
| 'Gamertag'
| 'AccountTier'
| 'XboxOneRep'
| 'PreferredColor'
| 'RealName'
| 'Bio'
| 'Location'
| 'ModernGamertag'
| 'ModernGamertagSuffix'
| 'UniqueModernGamertag'
| 'RealNameOverride'
| 'TenureLevel'
| 'Watermarks'
| 'IsQuarantined'
| 'DisplayedLinkedAccounts'
];
): Promise<{
id: | 'GameDisplayPicRaw'
| 'Gamerscore'
| 'Gamertag'
| 'AccountTier'
| 'XboxOneRep'
| 'PreferredColor'
| 'RealName'
| 'Bio'
| 'Location'
| 'ModernGamertag'
| 'ModernGamertagSuffix'
| 'UniqueModernGamertag'
| 'RealNameOverride'
| 'TenureLevel'
| 'Watermarks'
| 'IsQuarantined'
| 'DisplayedLinkedAccounts';
value: string;
}[]>getPlayerScreenshots - Returns targeted player's screenshots:
Warning: Recent games (since mid-2019) will not be returned, please use getPlayerScreenshotsFromActivityHistory instead (if required).
getPlayerScreenshots(
gamertagOrXUID: string;
authorization: {
userHash: string;
XSTSToken: string;
};
qs: {
maxItems?: number; // Default: 25
continuationToken?: string
};
): Promise<{
screenshots: {
screenshotId: string;
resolutionHeight: number;
resolutionWidth: number;
state: string;
datePublished: string;
dateTaken: string;
lastModified: string;
userCaption: string;
type: 'UserGenerated' | 'AutoGenerated';
scid: string;
titleId: number;
rating: number;
ratingCount: number;
views: number;
titleData: string;
systemProperties: string;
savedByUser: boolean;
achievementId: string;
greatestMomentId: string | null;
thumbnails: {
uri: string;
fileSize: 0;
thumbnailType: 'Small' | 'Large';
}[];
screenshotUris: {
uri: string;
fileSize: number;
uriType: 'Download';
expiration: string;
}[];
xuid: string;
screenshotName: string;
titleName: string;
screenshotLocale: string;
screenshotContentAttributes: string;
deviceType: string;
}[];
pagingInfo: {
continuationToken: string | null
};
}>getPlayerScreenshotsFromMediaHub - Returns targeted player's screenshots:
Warning: Recent games (since mid-2019) will not be returned, please use getPlayerScreenshotsFromActivityHistory instead (if required).
getPlayerScreenshotsFromMediaHub(
gamertagOrXUID: string;
authorization: {
userHash: string;
XSTSToken: string;
};
payload: {
max?: number; // Default: 100
skip?: number; // Default: 0
query?: string; // Example: titleId eq 175227487 and contentId eq 773a413e-5a95-48c2-98c4-5c919f67cfee
continuationToken?: string;
};
): Promise<{
continuationToken?: string;
values: {
captureDate: string;
contentId: string;
contentLocators: Array<
| { fileSize: number; locatorType: 'Download'; uri: string }
| { locatorType: 'Thumbnail_Small'; uri: string }
| { locatorType: 'Thumbnail_Large'; uri: string }
| { fileSize: number; locatorType: 'Download_HDR'; uri: string }
>;
CreationType: 'UserGenerated' | 'AutoGenerated';
localId: string;
ownerXuid: number;
resolutionHeight: number;
resolutionWidth: number;
sandboxId: 'RETAIL';
sharedTo: any[];
titleId: number;
titleName: string;
dateUploaded: string;
uploadLanguage: string;
uploadRegion: string;
uploadTitleId: number;
uploadDeviceType: string;
commentCount: number;
likeCount: number;
shareCount: number;
viewCount: number;
contentState: string;
enforcementState: string;
safetyThreshold: string;
sessions: any[];
tournaments: any[];
}[];
}>getPlayerScreenshotsFromActivityHistory - Returns targeted player's screenshots from its activity history:
Warning: Returned items count may not respect the specified numItems parameter.
getPlayerScreenshotsFromActivityHistory(
gamertagOrXUID: string;
authorization: {
userHash: string;
XSTSToken: string;
};
qs: {
numItems?: number;
contToken?: string;
pollingToken?: string;
startDate?: string;
};
): Promise<{
numItems: number;
activityItems: {
screenshotId: string;
screenshotThumbnail: string;
screenshotScid: string;
screenshotName: string;
screenshotUri: string;
viewCount: number;
gameMediaContentLocators: [
{
Expiration: string;
FileSize: number;
LocatorType: 'Download';
Uri: string;
},
{
Expiration: string;
FileSize: number;
LocatorType: 'Thumbnail_Small';
Uri: string;
},
{
Expiration: string;
FileSize: number;
LocatorType: 'Thumbnail_Large';
Uri: string;
}
];
contentImageUri: string;
contentTitle: string;
platform: string;
titleId: string;
uploadTitleId: string;
activity: {
screenshotThumbLarge: null;
screenshotThumbSmall: null;
screenshotType: null;
savedByUser: boolean;
screenshotScid: string;
screenshotId: string;
numShares: number;
numLikes: number;
numComments: number;
ugcCaption: string | null;
authorType: string;
activityItemType: 'Screenshot';
userXuid: string;
date: string;
contentType: 'Game';
titleId: string;
platform: string;
sandboxid: string;
userKey: string | null;
scid: string;
};
userImageUriMd: string;
userImageUriXs: string;
description: string;
date: string;
hasUgc: boolean;
activityItemType: 'Screenshot';
contentType: 'Game';
shortDescription: string;
itemText: string;
itemImage: string;
shareRoot: string;
feedItemId: string;
itemRoot: string;
hasLiked: boolean;
authorInfo: {
name: string;
secondName: string;
imageUrl: string;
authorType: string;
id: string;
};
gamertag: string;
realName: string;
displayName: string;
userImageUri: string;
userXuid: string;
}[];
pollingToken: string;
pollingIntervalSeconds: string | null;
contToken: string;
}>getPlayerGameClips - Returns targeted player's clips:
Warning: Recent games (since mid-2019) will not be returned, please use getPlayerGameClipsFromActivityHistory instead (if required).
getPlayerGameClips(
gamertagOrXUID: string;
authorization: {
userHash: string,
XSTSToken: string
},
qs: {
maxItems?: number = 25
continuationToken?: string
}
): Promise<{
gameClips: {
gameClipId: string;
state: string;
datePublished: string;
dateRecorded: string;
lastModified: string;
userCaption: string;
type: 'UserGenerated' | 'AutoGenerated';
durationInSeconds: number;
scid: string;
titleId: number;
rating: number;
ratingCount: number;
views: number;
titleData: string;
systemProperties: string;
savedByUser: boolean;
achievementId: string;
greatestMomentId: string | null;
thumbnails: {
uri: string;
fileSize: 0;
thumbnailType: 'Small' | 'Large';
}[];
gameClipUris: {
uri: string;
fileSize: number;
uriType: 'Download';
expiration: string;
}[];
xuid: string;
clipName: string;
titleName: string;
gameClipLocale: string;
clipContentAttributes: string;
deviceType: string;
commentCount: number;
likeCount: number;
shareCount: number;
partialViews: number;
}[];
pagingInfo: {
continuationToken: string | null
};
}>getPlayerGameClipsFromMediaHub - Returns targeted player's clips:
Warning: Recent games (since mid-2019) will not be returned, please use getPlayerGameClipsFromActivityHistory instead (if required).
getPlayerGameClipsFromMediaHub(
gamertagOrXUID: string;
authorization: {
userHash: string;
XSTSToken: string;
};
payload: {
max?: number; // Default: 100
skip?: number; // Default: 0
query?: string; // Example: titleId eq 175227487 and contentId eq 773a413e-5a95-48c2-98c4-5c919f67cfee
continuationToken?: string;
};
): Promise<{
continuationToken?: string;
values: {
contentId: string;
contentLocators: Array<
| {
expiration: string;
fileSize: number;
locatorType: 'Download';
uri: string;
}
| { locatorType: 'Thumbnail_Small'; uri: string }
| { locatorType: 'Thumbnail_Large'; uri: string }
>;
contentSegments: Array<{
segmentId: number;
creationType: 'UserGenerated' | 'AutoGenerated';
creatorChannelId: string | null;
creatorXuid: number;
recordDate: string;
durationInSeconds: number;
offset: number;
secondaryTitleId: string | null;
titleId: number;
}>;
creationType: 'UserGenerated' | 'AutoGenerated';
durationInSeconds: number;
frameRate: number;
greatestMomentId: string;
localId: string;
ownerXuid: number;
resolutionHeight: number;
resolutionWidth: number;
sandboxId: 'RETAIL';
sharedTo: any[];
titleData: string;
titleId: number;
titleName: string;
uploadDate: string;
uploadLanguage: string;
uploadRegion: string;
uploadTitleId: number;
uploadDeviceType: string;
userCaption: string;
commentCount: number;
likeCount: number;
shareCount: number;
viewCount: number;
contentState: string;
enforcementState: string;
safetyThreshold: string;
sessions: any[];
tournaments: any[];
}[];
}>getPlayerGameClipsFromActivityHistory - Returns targeted player's clips from its activity history:
Warning: Returned items count may not respect the specified numItems parameter.
getPlayerGameClipsFromActivityHistory(
gamertagOrXUID: string;
authorization: {
userHash: string;
XSTSToken: string;
};
qs: {
numItems?: number;
contToken?: string;
pollingToken?: string;
startDate?: string;
};
): Promise<{
numItems: number;
activityItems: {
clipId: string;
clipThumbnail: string;
downloadUri: string;
clipName: string;
clipCaption: string;
clipScid: string;
dateRecorded: string;
viewCount: number;
gameMediaContentLocators: [
{
Expiration: string;
FileSize: number;
LocatorType: 'Download';
Uri: string;
},
{
Expiration: string;
FileSize: number;
LocatorType: 'Thumbnail_Small';
Uri: string;
},
{
Expiration: string;
FileSize: number;
LocatorType: 'Thumbnail_Large';
Uri: string;
}
];
contentImageUri: string;
contentTitle: string;
platform: string;
titleId: string;
uploadTitleId: string;
activity: {
dateRecorded: string;
numShares: number;
numLikes: number;
numComments: number;
ugcCaption: string | null;
authorType: string;
clipId: string;
clipName: string | null;
activityItemType: 'GameDVR';
clipScid: string;
userXuid: string;
clipImage: string | null;
clipType: string | null;
clipCaption: string | null;
savedByUser: boolean;
date: string;
sharedSourceUser: number;
contentType: 'Game';
titleId: string;
platform: string;
sandboxid: string;
userKey: string | null;
scid: string;
};
userImageUriMd: string;
userImageUriXs: string;
description: string;
date: string;
hasUgc: boolean;
activityItemType: 'GameDVR';
contentType: 'Game';
shortDescription: string;
itemText: string;
itemImage: string;
shareRoot: string;
feedItemId: string;
itemRoot: string;
hasLiked: boolean;
authorInfo: {
name: string;
secondName: string;
imageUrl: string;
authorType: string;
id: string;
};
gamertag: string;
realName: string;
displayName: string;
userImageUri: string;
userXuid: string;
}[];
pollingToken: string;
pollingIntervalSeconds: string | null;
contToken: string;
}>getPlayerActivityHistory - Returns targeted player's activity history:
Warning: Returned items count may not respect the specified numItems parameter.
getPlayerActivityHistory(
gamertagOrXUID: string;
authorization: {
userHash: string;
XSTSToken: string;
};
qs?: {
numItems?: number;
contToken?: string;
pollingToken?: string;
activityTypes?: 'GameDVR' | 'Screenshot' | 'Achievement' | 'Played';
excludeTypes?: 'GameDVR' | 'Screenshot' | 'Achievement' | 'Played';
contentTypes?: 'Game' | 'App';
startDate?: string;
includeSelf?: boolean;
};
): Promise<{
numItems: number;
activityItems: any[];
pollingToken: string;
pollingIntervalSeconds: string | null;
contToken: string;
}>call - Generic method to call the API with a custom configuration:
call(
config: {
url: string;
method: GET | PUT | POST | PATCH | DELETE,
... // Please refer to https://github.com/axios/axios#request-config for further information
};
authorization: {
userHash: string;
XSTSToken: string;
};
XBLContractVersion?: number; // Default: 2
): Promise<any>Should I use XUIDs instead of Gamertags?
Some of exposed methods resolve player's XUID thanks to the specified gamertag which requires an additional request to be made internally (getPlayerXUID). If a valid XUID is used instead (during pagination for instance), this may speed up your request.
Where can I find additional Xbox Live API URIs?
Please refer to https://docs.microsoft.com/en-us/windows/uwp/xbox-live/xbox-live-rest/uri/atoc-xboxlivews-reference-uris.