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.jsYou 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 |
```json
"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 |
```json
"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`. |
```json
"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](https://store-images.s-microsoft.com/image/apps.4677.68326442227858632.03782b23-7f26-4a8e-ba87-177bdf2c3c90.4344f692-1744-4c18-8024-270fd320f63c) |
| TitledHeroArt | Banner featuring the game's name. | 16:9 | [Link](https://store-images.s-microsoft.com/image/apps.12688.68326442227858632.03782b23-7f26-4a8e-ba87-177bdf2c3c90.ef4d4f2f-1865-4fa7-8ec7-8b914cd4dcc0) |
| Poster | Banner featuring the game's name in portrait mode, such as for smartphones. | 2:3 | [Link](https://store-images.s-microsoft.com/image/apps.64810.68326442227858632.03782b23-7f26-4a8e-ba87-177bdf2c3c90.fdefe49f-270c-44e5-b660-6d7764b37f0f) |
| SuperHeroArt | Artwork without text. | 16:9 | [Link](https://store-images.s-microsoft.com/image/apps.62159.68326442227858632.03782b23-7f26-4a8e-ba87-177bdf2c3c90.1405eb3a-6314-4e44-a822-7660d70a6ec5) |
| Hero | Artwork without text. | 2:1 | [Link](https://store-images.s-microsoft.com/image/apps.28129.13672427983916579.274b1ffd-9cde-4bef-9a3e-6f37073d5ed0.5eb8b4f3-3575-4d13-b0a4-b60d6c64f392) |
| BoxArt | Banner featuring the game's logo and name in a square \"box\" format. | 1:1 | [Link](https://store-images.s-microsoft.com/image/apps.4794.68326442227858632.03782b23-7f26-4a8e-ba87-177bdf2c3c90.b156af1e-9796-48af-8d11-3461727280ea) |
| BrandedKeyArt | Banner featuring the game's name with an \"XBOX\" logo on top. | 73:100 | [Link](https://store-images.s-microsoft.com/image/apps.27624.68326442227858632.21f49c7b-79d7-4647-b847-ecc7a34a7901.1aa31c66-2a52-45d6-8fed-badfb9f25ac6) |
| FeaturePromotionalSquareArt | Banner featuring the game's logo (without name) in a square \"box\" format. | 1:1 | [Link](https://store-images.s-microsoft.com/image/apps.29819.68326442227858632.03782b23-7f26-4a8e-ba87-177bdf2c3c90.322d4aa6-0a23-4565-a64f-743f0620a96e) |
| Logo | Small, square game logo, to be used e.g. as a game library icon. | 1:1 | [Link](https://store-images.s-microsoft.com/image/apps.65119.13664397958929388.0e87ac81-8aa3-41f0-82dc-61a295fc5fe3.44bf032a-b113-4179-aa1b-f557dbcd3b19) |
releaseDate
Whether to include the game's release date.
| Type | Default | Possible values | Required |
| --- | --- | --- | --- |
| `object` | See item below | See sections below | No |
```json
"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 |
```json
"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 |
```json
"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.