Game Pass API

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
BranedKeyArt	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

Related projects

If you would like to know the Steam App ID's for the games you own on Steam, Epic Games or GOG, you can use the Steam App ID Finder to do just that.

You can then use the Notion Steam API Integration to automatically add information about those games to your Notion database.

Alternatively, you can use the JSON to Notion tool to directly create a new page in your Notion database for each game extracted using the Game Pass API - this tool works with any kind of JSON file!

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.