Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.
Awesome Lists | Featured Topics | Projects
https://github.com/XboxReplay/xboxlive-api

Simple Xbox Live API wrapper.
https://github.com/XboxReplay/xboxlive-api
nodejs typescript xboxlive
Last synced: 3 months ago
JSON representation
Simple Xbox Live API wrapper.
Host: GitHub
URL: https://github.com/XboxReplay/xboxlive-api
Owner: XboxReplay
License: mit
Created: 2019-01-29T21:48:03.000Z (almost 6 years ago)
Default Branch: master
Last Pushed: 2023-04-30T08:36:15.000Z (over 1 year ago)
Last Synced: 2024-07-20T14:21:24.489Z (4 months ago)
Topics: nodejs, typescript, xboxlive
Language: TypeScript
Homepage: https://www.xboxreplay.net/
Size: 154 KB
Stars: 38
Watchers: 4
Forks: 6
Open Issues: 3
Metadata Files:
- Readme: README.md
Awesome Lists containing this project

jimsghstars - XboxReplay/xboxlive-api - Simple Xbox Live API wrapper. (TypeScript)
README

        # Xbox Live - API

Simple Xbox Live API wrapper.

### Warning

This module **MUST** be used server side only to prevent [CORS](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) issues and credentials leak.

### Installation

```shell

$ npm install @xboxreplay/xboxlive-api

```

### Example usage

```javascript

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:**

```javascript

[

    {

        "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](https://github.com/XboxReplay/xboxlive-auth) module which returns an **userHash** and a **XSTSToken** for a specified account.

### Available methods

**getPlayerXUID** - Returns targeted player's XUID:

```javascript

getPlayerXUID(

    gamertagOrXUID: string;

    authorization: {

        userHash: string;

        XSTSToken: string;

    };

): Promise

```

**getPlayerSettings** - Returns targeted player's settings:

```javascript

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).}

```javascript

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).}

```javascript

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.}

```javascript

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).}

```javascript

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).}

```javascript

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.}

```javascript

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.}

```javascript

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:

```javascript

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

```

### 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.