Game Pass API

Get a list of all games currently available on Xbox Game Pass (Console, PC or EA Play) in any region, with their properties formatted just the way you need - from just the game names all the way to live store prices at the moment of the request.

Table of contents

• Installation
• Usage
• Output
• Configuration
• Examples
• Feedback
• Disclaimer

Installation

Run it on demand without installing anything (requires Node.js 22.13 or newer):

npx game-pass-api

Or install it globally to get a persistent game-pass-api command:

npm install -g game-pass-api

Usage

The tool is driven by a config.json in your current directory. The quickest way to create one is the interactive wizard:

game-pass-api init

It asks a few questions (markets, language, platforms, and which properties to include) and writes a config.json, then offers to run it right away. Running game-pass-api with no arguments and no config.json present starts this wizard automatically.

You can also write the config.json by hand - see Configuration - and then run the tool:

game-pass-api

By default it reads ./config.json; pass --config <path> to point at a different file. Run game-pass-api --help to see every command, or game-pass-api run --help for the full list of flags.

You can also run without a config.json at all, building the configuration entirely from flags:

game-pass-api --markets US,DE --platforms console,pc --properties productTitle,productId --format productTitle

Any option you omit uses its default. Add --save-config to also write the assembled configuration to a config.json (or --save-config <path>) so you can reuse or edit it later. Nested options such as images, pricing and user ratings are only available through a config.json or the wizard.

Command-line flags

Flag	Config key	Description
-c, --config <path>	-	Path to a config.json. Defaults to ./config.json.
--from <dir>	-	Re-format previously-saved completeGameProperties_*.json files in <dir> instead of fetching (needs an earlier run with keepCompleteProperties).
-o, --out <dir>	outputDirectory	Directory to write output files to. Default output.
--markets <codes>	markets	Comma-separated market codes to fetch, e.g. US,DE. Enables flag-driven mode.
--platforms <list>	platformsToFetch	Comma-separated platforms: console,pc,eaPlay.
--language <code>	language	Language/locale for game properties, e.g. en-us.
--format <format>	outputFormat	Output format: array, productTitle, productId or 0-indexed.
--properties <list>	includedProperties	Comma-separated properties to include: productTitle,productId,developerName,publisherName,categories,storePage.
--keep-complete	keepCompleteProperties	Also keep the complete, unfiltered API response per platform and market.
--no-treat-empty-as-null	treatEmptyStringsAsNull	Keep empty strings instead of converting them to null.
--save-config [path]	-	Also write the assembled configuration to a file for reuse. Default config.json.

Nested options (image types, pricing, user ratings, descriptions, release dates) are only available through a config.json or the wizard. The init command takes -o, --output <path> to choose where the wizard writes the configuration file (default config.json).

Configuration files are validated against a JSON schema (config.schema.json, shipped with the package). Add "$schema": "config.schema.json" to your config.json, with a copy of the schema next to it, and your editor will flag mistakes as you type.

Unsure where to start? Take a look at the examples and work from there.

Output

The results are written to an output/ folder in your current directory (change it with the outputDirectory config field or -o, --out <dir>), with one file per platform and market (for example output/formattedGameProperties_console_US.json). When keepCompleteProperties is enabled, the full unfiltered API response is written alongside it (for example output/completeGameProperties_console_US.json).

Those complete files can be re-formatted without fetching again: game-pass-api run --from <dir> (for example --from output) reads the saved completeGameProperties_*.json files for your configured markets and platforms and re-applies the current outputFormat and includedProperties. Use it to re-slice a saved snapshot into a different shape offline, without hitting the API.

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 property under includedProperties is not present in the configuration file, it is left out of the output; any other optional property falls back to the default listed in its table below.

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

outputDirectory

The directory to write the output files to, relative to the current directory. Can also be set on the command line with -o, --out <dir>.

Type	Default	Possible values	Required
string	"output"	Any directory path	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": "useNull"
}

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.