Skip to content

Get all games currently available for Xbox Game Pass on any platform, with their features and properties formatted just the way you need.

License

Notifications You must be signed in to change notification settings

NikkelM/Game-Pass-API

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

68 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Game Pass API

Game Pass API banner

This project provides a quick and easy way to get a list of all games currently available on Xbox Game Pass on a given platform (Console, PC or through EA Play) in a given region.

Using the configuration file, the type and format of many properties can be customized, from simply getting the game's names all the way to fetching store prices at the moment of the request.

Take a look at the section below to learn how to use the configuration file, or take a look at the examples and work from there.

Setup

Run npm install to install the required dependencies first.

Following this, create a config.json file in the root directory of the project and fill it with your desired configuration.

Usage

After providing the config.json configuration file, you can run the script using

node index.js

You will find the resulting data in the created output folder.

Unsure how it works? Take a look at the examples for some inspiration.

Configuration

Schema validation

The project provides an extensive JSON validation schema for the required configuration file, which offers guidance on the possible properties that can be extracted from the API, as well as options for formatting the resulting data.

Are you missing a property? Feel free to open an issue and I will see what I can do. Alternatively, fork the repository and open a Pull Request.

The schema can be found in the config.schema.json file and used within your config.json by adding the following property:

"$schema": "config.schema.json"

NOTE: The script will test your provided config.json against this schema, so make sure your configuration is valid.

Properties

The following is a list of all configuration items, their defaults in the config.default.json and the values you can assign to them.

If a given property is not present in the configuration file, it will automatically be assumed to have a value of false (or equivalent, depending on the property type), and not be included in the output.

Top-level properties

Required properties:

markets

The two letter market codes for which to fetch games. The script will run once for each market code.

Type Default Possible values Required
array ["US"] US, DZ, AR, AU, AT, BH, BD, BE, BR, BG, CA, CL, CN, CO, CR, HR, CY, CZ, DK, EG, EE, FI, FR, DE, GR, GT, HK, HU, IS, IN, ID, IQ, IE, IL, IT, JP, JO, KZ, KE, KW, LV, LB, LI, LT, LU, MY, MT, MR, MX, MA, NL, NZ, NG, NO, OM, PK, PE, PH, PL, PT, QA, RO, RU, SA, RS, SG, SK, SI, ZA, KR, ES, SE, CH, TW, TH, TT, TN, TR, UA, AE, GB, VN, YE, LY, LK, UY, VE, AF, AX, AL, AS, AO, AI, AQ, AG, AM, AW, BO, BQ, BA, BW, BV, IO, BN, BF, BI, KH, CM, CV, KY, CF, TD, TL, DJ, DM, DO, EC, SV, GQ, ER, ET, FK, FO, FJ, GF, PF, TF, GA, GM, GE, GH, GI, GL, GD, GP, GU, GG, GN, GW, GY, HT, HM, HN, AZ, BS, BB, BY, BZ, BJ, BM, BT, KM, CG, CD, CK, CX, CC, CI, CW, JM, SJ, JE, KI, KG, LA, LS, LR, MO, MK, MG, MW, IM, MH, MQ, MU, YT, FM, MD, MN, MS, MZ, MM, NA, NR, NP, MV, ML, NC, NI, NE, NU, NF, PW, PS, PA, PG, PY, RE, RW, BL, MF, WS, ST, SN, MP, PN, SX, SB, SO, SC, SL, GS, SH, KN, LC, PM, VC, TJ, TZ, TG, TK, TO, TM, TC, TV, UM, UG, VI, VG, WF, EH, ZM, ZW, UZ, VU, SR, SZ, AD, MC, SM, ME, VA, NEUTRAL Yes, at least one market code.
language

The language to use when fetching game properties. Properties such as the game description will be in this language.

This does not impact the tool's language.

Type Default Possible values Required
string "en-us" es-ar, pt-br, en-ca, fr-ca, es-cl, es-co, es-mx, en-us, nl-be, fr-be, cs-cz, da-dk, de-de, es-es, fr-fr, en-ie, it-it, hu-hu, nl-nl, nb-no, de-at, pl-pl, pt-pt, de-ch, sk-sk, fr-ch, fi-fi, sv-se, en-gb, el-gr, ru-ru, en-au, en-hk, en-in, id-id, en-my, en-nz, en-ph, en-sg, vi-vn, th-th, ko-kr, zh-cn, zh-tw, ja-jp, zh-hk, en-za, tr-tr, he-il, ar-ae, ar-sa Yes
platformsToFetch

Which platforms to fetch games for, any of console, pc and eaPlay.

Type Default Possible values Required
array ["console", "pc", "eaPlay"] console, pc, eaPlay Yes, at least one platform.
outputFormat

What kind of format the top-level JSON output should have.

Type Default Possible values Required
string "array" array: The resulting data structure is an array. Each entry is a dictionary holding the properties of a separate game.
productTitle: The resulting data structure is a dictionary. The games' titles are used as keys.
productId: The resulting data structure is a dictionary. The games' product IDs are used as keys.
0-indexed: The resulting data structure is a dictionary. 0-indexed integers are used as keys.
Yes
includedProperties

The properties that should be contained in the filtered version of the API response.

Type Default Possible values Required
object See subsection below See subsection below Yes, and at least one sub-property enabled

Optional properties (defaults will be applied):

treatEmptyStringsAsNull

Whether to treat empty strings as null values.

Type Default Possible values Required
boolean true true or false No
keepCompleteProperties

Whether to keep the original, complete list of properties for the fetched games. Will be saved in a separate file per platform and market.

Type Default Possible values Required
boolean false true or false No

includedProperties

If any of these properties are omitted, they will not be included in the output. The Default column indicates the default applied when using the config.default.json file.

productTitle

Whether to include the title of the game.

Type Default Possible values Required
boolean true true or false No
productId

Whether to include the product ID of the game.

Type Default Possible values Required
boolean false true or false No
developerName

Whether to include the name of the game's developer.

Type Default Possible values Required
boolean false true or false No
publisherName

Whether to include the name of the game's publisher.

Type Default Possible values Required
boolean false true or false No
categories

Whether to include the game's categories.

Type Default Possible values Required
boolean false true or false No
productDescription

Whether to include the description of the game.

Type Default Possible values Required
object See item below See sections below No
"productDescription": {
	"enabled": false,
	"preferShort": false
}

Possible values

enabled

Whether to include the description of the game.

Type Default Possible values Required
boolean false true or false Yes

preferShort

Whether to prefer the short description of the game over the long description, if one exists.

Type Default Possible values Required
boolean false true or false No
images

Whether to include image URL's for the game.

Type Default Possible values Required
object See item below See sections below No
"images": {
	"enabled": false,
	"imageTypes": {
		"TitledHeroArt": -1,
		"SuperHeroArt": -1,
		"Logo": -1,
		"Poster": -1,
		"Screenshot": -1,
		"BoxArt": -1,
		"Hero": -1,
		"BrandedKeyArt": -1,
		"FeaturePromotionalSquareArt": -1
	}
}

Possible values

enabled

Whether to include image URL's for the game.

Type Default Possible values Required
boolean false true or false Yes

imageTypes

What kinds of images should be included in the output, and a maximum of how many of each type should be chosen.

Type Default Possible values Required
object See item below Any number of image type combinations with values from -1 upwards. A value of -1 indicates no limit. A value of 0 is equal to omitting the item. Yes, at least one imageType.
"imageTypes": {
	"TitledHeroArt": -1,
	"SuperHeroArt": -1,
	"Logo": -1,
	"Poster": -1,
	"Screenshot": -1,
	"BoxArt": -1,
	"Hero": -1,
	"BrandedKeyArt": -1,
	"FeaturePromotionalSquareArt": -1
}

Description of the various image types:

Image type Description Aspect Ratio Example
Screenshot In-game screenshots. 16:9 Link
TitledHeroArt Banner featuring the game's name. 16:9 Link
Poster Banner featuring the game's name in portrait mode, such as for smartphones. 2:3 Link
SuperHeroArt Artwork without text. 16:9 Link
Hero Artwork without text. 2:1 Link
BoxArt Banner featuring the game's logo and name in a square "box" format. 1:1 Link
BrandedKeyArt Banner featuring the game's name with an "XBOX" logo on top. 73:100 Link
FeaturePromotionalSquareArt Banner featuring the game's logo (without name) in a square "box" format. 1:1 Link
Logo Small, square game logo, to be used e.g. as a game library icon. 1:1 Link
releaseDate

Whether to include the game's release date.

Type Default Possible values Required
object See item below See sections below No
"releaseDate": {
	"enabled": false,
	"format": "date"
}

Possible Values

enabled

Whether to include the game's release date.

Type Default Possible values Required
boolean false true or false Yes

format

How to format the date string. Either the full dateTime (YYYY-MM-DDTHH:mm:ss.sssssssZ) or just the date (YYYY-MM-DD).

Type Default Possible values Required
string "date" "date" or "dateTime" Yes
userRating

Whether to include the game's user rating.

Type Default Possible values Required
object See item below See sections below No
"userRating": {
	"enabled": false,
	"aggregationInterval": "AllTime",
	"format": "percentage"
}

Possible Values

enabled

Whether to include the game's user rating.

Type Default Possible values Required
boolean false true or false Yes

aggregationInterval

Which kind of interval to use for rating aggregation.

Type Default Possible values Required
string "AllTime" "AllTime", "30Days", "7Days" Yes

format

How to format the rating. Either as the original x-out-of-5 stars value (0.0 - 5.0) or as a percentage (0.0 - 1.0).

Type Default Possible values Required
string "percentage" "stars" or "percentage" Yes
pricing

Whether to include the game's price information. The currency that is used is dependent on the chosen market.

Type Default Possible values Required
object See item below See sections below No
"pricing": {
	"enabled": false,
	"priceTypes": [
		"ListPrice",
		"MSRP",
		"WholesalePrice"
	],
	"missingPricePolicy": "useZero"
}

Possible Values

enabled

Whether to include the game's price information. The currency that is used is dependent on the chosen market.

Type Default Possible values Required
boolean false true or false Yes

priceTypes

Which kinds of prices to include. Choose from ListPrice, MSRP and WholesalePrice (i.e. with discounts applied).

Type Default Possible values Required
array ["ListPrice", "MSRP", "WholesalePrice"] Any combination of:
"ListPrice": The current listing price in the store.
"MSRP": The manufacturer's suggested retail price.
"WholesalePrice": The wholesale price, i.e. the ListPrice after sales have been applied.
Yes, at least one priceType.

missingPricePolicy

What to do if a price is missing. Either useZero, useNull or useEmptyString.

Type Default Possible values Required
string "useNull" "useZero", "useNull" or "useEmptyString" Yes
storePage

Whether to include the game's store page URL. Note that this is not guaranteed to always result in a working URL, as it needs to be inferred and is not available through the API.

Type Default Possible values Required
boolean false true or false No

Feedback

If you have any question, feedback or feature requests, feel free to open an issue.

Disclaimer

This unofficial project is not affiliated with Microsoft or Xbox in any way. The data provided when using this project is obtained from the public Xbox catalog API and is not guaranteed to be accurate or up-to-date.

About

Get all games currently available for Xbox Game Pass on any platform, with their features and properties formatted just the way you need.

Topics

Resources

License

Stars

Watchers

Forks