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:

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

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 |

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

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 |

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

Whether to treat empty strings as null values.

| Type | Default | Possible values | Required | | --- | --- | --- | --- | | boolean | true | true or false | No |

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 |

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.

Whether to include the title of the game.

| Type | Default | Possible values | Required | | --- | --- | --- | --- | | boolean | true | true or false | No |

Whether to include the product ID of the game.

| Type | Default | Possible values | Required | | --- | --- | --- | --- | | boolean | false | true or false | No |

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

| Type | Default | Possible values | Required | | --- | --- | --- | --- | | boolean | false | true or false | No |

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

| Type | Default | Possible values | Required | | --- | --- | --- | --- | | boolean | false | true or false | No |

Whether to include the game's categories.

| Type | Default | Possible values | Required | | --- | --- | --- | --- | | boolean | false | true or false | No |

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
}

Whether to include the description of the game.

| Type | Default | Possible values | Required | | --- | --- | --- | --- | | boolean | false | true or false | Yes |

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 |

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

Whether to include image URL's for the game.

| Type | Default | Possible values | Required | | --- | --- | --- | --- | | boolean | false | true or false | Yes |

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 |

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

Whether to include the game's release date.

| Type | Default | Possible values | Required | | --- | --- | --- | --- | | boolean | false | true or false | Yes |

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 |

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

Whether to include the game's user rating.

| Type | Default | Possible values | Required | | --- | --- | --- | --- | | boolean | false | true or false | Yes |

Which kind of interval to use for rating aggregation.

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

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 |

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

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 |

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

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 |

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.