API #
Hey, welcome to this super awesome API. It has one endpoint! Here is an example request:
curl https://whatsinstandard.com/api/v6/standard.json
This will return something like:
{
"deprecated": false,
"sets": [
{
"name": "Kaladesh",
"codename": "Lock",
"code": "KLD",
"symbol": {
"common": "http://gatherer.wizards.com/Handlers/Image.ashx?type=symbol&size=large&rarity=C&set=KLD",
"uncommon": "http://gatherer.wizards.com/Handlers/Image.ashx?type=symbol&size=large&rarity=U&set=KLD",
"rare": "http://gatherer.wizards.com/Handlers/Image.ashx?type=symbol&size=large&rarity=R&set=KLD",
"mythicRare": "http://gatherer.wizards.com/Handlers/Image.ashx?type=symbol&size=large&rarity=M&set=KLD"
},
"enterDate": {
"exact": "2016-09-30T00:00:00.000"
},
"exitDate": {
"exact": "2018-10-05T00:00:00.000",
"rough": "Q4 2018"
}
},
...
],
"bans": [
{
"cardName": "Rampaging Ferocidon",
"cardImageUrl": "https://img.scryfall.com/cards/large/en/xln/154.jpg?1527429722",
"setCode": "XLN",
"reason": "Banned for being too effective a shutdown against counters to aggressive red (filling the board with small creatures and gaining life).",
"announcementUrl": "https://magic.wizards.com/en/articles/archive/news/january-15-2018-banned-and-restricted-announcement-2018-01-15"
},
...
]
}
But you can just visit it yourself to see everything. You'll get some JSON containing an array of Magic sets and banned cards.
Documentation #
The API specification is written in JSON Schema, which is a way of saying programmatically what the structure of the API is. You can view the user-friendly documentation generated by the schema using this link:
View documentation #
You can also view or download the raw JSON Schema to help you validate your code or generate structures in your language of choice automatically.
Notes #
The sets array contains a superset of all sets in Standard -- it may contain some sets
that have dropped and some sets that have not yet released. It is your responsibility to
filter these sets out by comparing each set's enter_date and exit_date to the
current date.
Here's a JavaScript function that does just that:
const standardSets = (callback) => {
fetch("https://whatsinstandard.com/api/v6/standard.json").then((response) =>
response.json().then((body) => {
callback(
body.sets.filter((set) => {
return (
(Date.parse(set.enterDate.exact) || Infinity) <= Date.now() &&
(Date.parse(set.exitDate.exact) || Infinity) > Date.now()
);
})
);
})
);
};
The bans array is in order of ban, from oldest ban to newest. Again, it contains a
superset of all bans in Standard -- it may contain some bans that belong to sets that
have dropped. Filter these bans out by correlating each ban's setCode to a code from
a set included in the sets array, filtered to exclude non-Standard sets:
const bannedCards = (callback) => {
fetch("https://whatsinstandard.com/api/v6/standard.json").then((response) =>
response.json().then((body) => {
callback(
body.bans.filter((ban) => {
return body.sets
.filter((set) => {
return (
(Date.parse(set.enterDate.exact) || Infinity) <= Date.now() &&
(Date.parse(set.exitDate.exact) || Infinity) > Date.now()
);
})
.map((set) => set.code)
.includes(ban.setCode);
})
);
})
);
};
Automatic deprecation alerts #
When using the API, you should always check the root object's boolean field
deprecated, which will flip on if that API version becomes deprecated. Configure your
program to notify you if this field is ever true so you aren't caught off guard if the
version you use is deprecated then eventually killed.
API v1 through v4 are past deprecation and no longer available.
Changelog #
Version 6 #
- All properties that used
snake_casenow usecamelCase. enterDate,roughEnterDate,exitDate, androughExitDatehave been simplified toenterDateandexitDate, each an object withroughandexactproperties.(enter|exit)Date.roughcan now hold either a month or a quarter.codecan now be null.namecan now be null.- Added
codenameproperty. - Set symbols are once again available in the API.
- The
blockproperty has been removed.
Midversion nonbreaking changes #
- 2023-02-19: The description for the
date.exactfield in the schema definition (manifested assets[].enterDate.exactandsets[].exitDate.exact) has updated from promising RFC 3339 to promising ISO 8601. No behavior has changed; this only brings the field's description in line with its behavior. See #255.
Version 5 #
- The root element in the response is now an object, not an array. The root object's
setsfield is the array. - Added a new
deprecatedfield to the root object. This field will befalseuntil v6 of the API is introduced, which will flip it totrue. - The API base path has changed from
whatsinstandard.com/api/\dtowhatsinstandard.com/api/v\dto be more consistent with the rest of the internet. - Like upcoming sets in v4, sets that have rotated out of Standard can now be included
in the sets array. There is no guarantee about the number of these sets included
(though it will generally be single-digit). You should filter on
enter_dateandexit_dateif you care only about the sets currently in Standard. enter_datecan now be null to allow for upcoming sets whose release dates are not known.blockcan now be null to allow for new blockless sets.
Midversion nonbreaking changes #
- 2018-04-28:
enter_dateandexit_dateno longer include timezone (see #75). The dates are still ISO 8601 compatible and are now intended to be parsed in the local timezone. - 2019-02-28: Documentation for
codenow correctly states it matches/[A-Z0-9]{3}/. It previously incorrectly stated that it matched/[A-Z]{3}/. No behavior has changed, only documentation. - 2019-02-28: Banned cards are now included in API.
Version 4 #
- Upcoming sets are once again included in the sets array. To use only released sets or
only unreleased sets, filter on
enter_date. blockcan no longer benull, as no more core sets will enter Standard.- The
symbolfield has been removed to decrease maintenance work. If you'd like still like to fetch set images, you can instead use thecodefield to construct an image URL likehttp://gatherer.wizards.com/Handlers/Image.ashx?type=symbol&set=<code>&size=large&rarity=C. rough_exit_dateregex has changed from/(early\/mid|late) 20\d\d/to/Q\d 20\d\d/for simplicity.
Version 3 #
Valid rough_exit_date regex has changed from /(early|late) 20\d\d/ to
/(early\/mid|late) 20\d\d/ to account for the new Standard rotation style. Old API
versions will continue to match their respective regexes, but with potentially less
accuracy. See Wizards's article on the change for details.
Version 2 #
Upcoming unreleased sets are no longer included in the sets array.
Contributing #
If you're making changes to the API, note that the api/v*/*.json files are generated
programmatically by api/v*/generate.js scripts. The scripts read the unstable
api/internal.json file in this directory and output version-stable JSON.
In other words: api/internal.json is the database, api/v*/generate.js is the view,
and api/v*/*.json is the generated output.
Run
npm install
to regenerate the endpoints.