API Reference
EDHREC
Scryfall
Scryfall is a search engine for magic cards. It provides a REST-like API for ingesting our card data programatically. The API exposes information available on the regular site in easy-to-consume formats.
Feature |
Support |
---|---|
Cards |
✅ |
Sets |
✅ |
Rulings |
✅ |
Card Symbols |
✅ |
Bulk Data |
✅ (fully async) |
Card Migrations |
✅ |
Application |
❌ |
Scryfall Client
- class mightstone.services.scryfall.Scryfall(transport: Optional[BaseTransport] = None)
Scryfall API client
- autocomplete(q: str, include_extras=False) Catalog
Sync version of
autocomplete_async()
, same behavior but wrapped byasync_to_sync()
.
- async autocomplete_async(q: str, include_extras=False) Catalog
Returns a Catalog object containing up to 20 full English card names that could be autocompletions of the given string parameter.
This method is designed for creating assistive UI elements that allow users to free-type card names. The names are sorted with the nearest match first, highly favoring results that begin with your given string.
Spaces, punctuation, and capitalization are ignored.
If q is less than 2 characters long, or if no names match, the Catalog will contain 0 items (instead of returning any errors).
- Parameters:
q – The string to autocomplete.
include_extras – If true, extra cards (tokens, planes, vanguards, etc) will be included.
- Returns:
A scryfall Card instance async generator
- base_url: str = 'https://api.scryfall.com'
Base url of the service (must be a root path such as https://example.com)
- card(id: str, type: CardIdentifierPath = CardIdentifierPath.SCRYFALL) Card
Sync version of
card_async()
, same behavior but wrapped byasync_to_sync()
.
- async card_async(id: str, type: CardIdentifierPath = CardIdentifierPath.SCRYFALL) Card
Returns a single card with a given ID, or by its code set / collector number
- Depending on the type value, one of the following endpoint will be reached:
/cards/:id
/cards/tcgplayer/:id
/cards/multiverse/:id
/cards/mtgo/:id
/cards/arena/:id
/cards/cardmarket/:id
/cards/:code/:number
- Parameters:
id – The requested Card identifier string, for code-number, please use / as separator (dmu/123)
type – The card identifier, please refer to CardIdentifierPath enum
type – Type of id researched
- Returns:
A scryfall Card instance
- catalog(type: CatalogType) Catalog
Sync version of
catalog_async()
, same behavior but wrapped byasync_to_sync()
.
- async catalog_async(type: CatalogType) Catalog
A Catalog object contains an array of Magic datapoints (words, card values, etc). Catalog objects are provided by the API as aids for building other Magic software and understanding possible values for a field on Card objects.
- Parameters:
type – See CatalogType for more informations
- Returns:
A Catalog instance
- collection(identifiers: List[Union[IdentifierId, IdentifierName, IdentifierNameSet, IdentifierMtgId, IdentifierOracleId, IdentifierMultiverseId, IdentifierCollectorNumberSet, IdentifierIllustrationId]]) AsyncGenerator[Card, None]
Sync version of
collection_async()
, same behavior but wrapped byasync_to_sync()
.
- async collection_async(identifiers: List[Union[IdentifierId, IdentifierName, IdentifierNameSet, IdentifierMtgId, IdentifierOracleId, IdentifierMultiverseId, IdentifierCollectorNumberSet, IdentifierIllustrationId]]) AsyncGenerator[Card, None]
Accepts a JSON array of card identifiers, and returns a List object with the collection of requested cards. A maximum of 75 card references may be submitted per request.
- Parameters:
identifiers – Each submitted card identifier must be a JSON object with one or more of the keys id, mtgo_id, multiverse_id, oracle_id, illustration_id, name, set, and collector_number
- Returns:
A scryfall Card instance async generator
- get_bulk_data(bulk_type: str) AsyncGenerator[Card, None]
Sync version of
get_bulk_data_async()
, same behavior but wrapped byasync_to_sync()
.
- async get_bulk_data_async(bulk_type: str) AsyncGenerator[Card, None]
Access the bulk cards This script uses ijson and should stream data on the fly
See https://scryfall.com/docs/api/bulk-data for more informations
- Parameters:
bulk_type – A string describing the bulk export name
- Returns:
An async iterator of
Card
- get_bulk_tags(tag_type: BulkTagType) AsyncGenerator[Tag, None]
Sync version of
get_bulk_tags_async()
, same behavior but wrapped byasync_to_sync()
.
- async get_bulk_tags_async(tag_type: BulkTagType) AsyncGenerator[Tag, None]
Access the private tag repository
This is an alpha feature, and could be removed later.
- Parameters:
tag_type – The tag type either oracle or illustration
- Returns:
A scryfall Tag instance async generator
- migration(id: str) Migration
Sync version of
migration_async()
, same behavior but wrapped byasync_to_sync()
.
- async migration_async(id: str) Migration
Returns a single Card Migration with the given :id
- Returns:
A Migration instance
- migrations(limit: int = None) AsyncGenerator[Migration, None]
Sync version of
migrations_async()
, same behavior but wrapped byasync_to_sync()
.
- async migrations_async(limit: Optional[int] = None) AsyncGenerator[Migration, None]
For the vast majority of Scryfall’s database, Magic card entries are additive. We add new and upcoming cards as we learn about them and obtain images.
In rare instances, Scryfall may discover that a card in our database does not really exist, or it has been deleted from a digital game permanently. In these situations, we provide endpoints to help you reconcile downstream data you may have synced or imported from Scryfall.
Each migration has a provided migration_strategy:
merge You should update your records to replace the given old Scryfall ID with the new ID. The old ID is being discarded, and an existing record should be used to replace all instances of it.
delete The given UUID is being discarded, and no replacement data is being provided. This likely means the old records are fully invalid. This migration exists to provide evidence that cards were removed from Scryfall’s database.
- Parameters:
limit – The number of item to return, please note that Mightstone wraps Scryfall pagination and streams the results
- Returns:
A Migration instance async generator
- named(q: str, set: str = None, exact=True) Card
Sync version of
named_async()
, same behavior but wrapped byasync_to_sync()
.
- async named_async(q: str, set: Optional[str] = None, exact=True) Card
Returns a Card based on a name search string. This method is designed for building chatbots, forum bots, and other services that need card details quickly.
If exact mode is on, a card with that exact name is returned. Otherwise, an Exception is raised because no card matches. If exact mode is off and a card name matches that string, then that card is returned. If not, a fuzzy search is executed for your card name. The server allows misspellings and partial words to be provided. For example: jac bele will match Jace Beleren. When fuzzy searching, a card is returned if the server is confident that you unambiguously identified a unique name with your string. Otherwise, an exception will be raised describing the problem: either more than 1 one card matched your search, or zero cards matched.
Card names are case-insensitive and punctuation is optional (you can drop apostrophes and periods etc). For example: fIReBALL is the same as Fireball and smugglers copter is the same as Smuggler’s Copter.
- Parameters:
q – The searched card name
exact – Run a strict text research instead of a fuzzy search
set – You may also provide a set code in the set parameter, in which case the name search and the returned card print will be limited to the specified set.
- Returns:
A scryfall Card instance
- parse_mana(cost: str) ManaCost
Sync version of
parse_mana_async()
, same behavior but wrapped byasync_to_sync()
.
- async parse_mana_async(cost: str) ManaCost
Parses the given mana cost parameter and returns Scryfall’s interpretation.
The server understands most community shorthand for mana costs (such as 2WW for {2}{W}{W}). Symbols can also be out of order, lowercase, or have multiple colorless costs (such as 2{g}2 for {4}{G}).
If part of the string could not be understood, the server will raise an Error object describing the problem.
- Parameters:
cost – A mana cost string
- Returns:
A ManaCost instance
- random(q: str = None) Card
Sync version of
random_async()
, same behavior but wrapped byasync_to_sync()
.
- async random_async(q: Optional[str] = None) Card
Returns a single random Card object.
This method will use: - /cards/random
- Parameters:
q – The optional parameter q supports the same fulltext search system that the main site uses. Providing q will filter the pool of cards before returning a random entry.
- Returns:
A scryfall Card instance
- rulings(id: str, type: RulingIdentifierPath = RulingIdentifierPath.SCRYFALL, limit: int = None) AsyncGenerator[Ruling, None]
Sync version of
rulings_async()
, same behavior but wrapped byasync_to_sync()
.
- async rulings_async(id: str, type: RulingIdentifierPath = RulingIdentifierPath.SCRYFALL, limit: Optional[int] = None) AsyncGenerator[Ruling, None]
Returns a single card with the given ID.
- Depending on the type value, one of the following endpoint will be reached:
/cards/:id/rulings
/cards/multiverse/:id/rulings
/cards/mtgo/:id/rulings
/cards/arena/:id/rulings
- Parameters:
id – The requested Card identifier string. In the case of card-number, use set/number (separated by a slash, for instance dmu/123)
type – The card identifier, please refer to RulingIdentifierPath enum
- Returns:
A scryfall Ruling instance async generator
- search(q: str, unique: UniqueStrategy = UniqueStrategy.CARDS, order: SortStrategy = SortStrategy.NAME, dir: DirectionStrategy = DirectionStrategy.AUTO, include_extras=False, include_multilingual=False, include_variations=False, limit: int = 100) AsyncGenerator[Card, None]
Sync version of
search_async()
, same behavior but wrapped byasync_to_sync()
.
- async search_async(q: str, unique: UniqueStrategy = UniqueStrategy.CARDS, order: SortStrategy = SortStrategy.NAME, dir: DirectionStrategy = DirectionStrategy.AUTO, include_extras=False, include_multilingual=False, include_variations=False, limit: int = 100) AsyncGenerator[Card, None]
Returns a List object containing Cards found using a fulltext search string. This string supports the same fulltext search system that the main site uses.
- Parameters:
unique – The strategy for omitting similar cards.
order – The method to sort returned cards.
dir – The direction to sort cards.
include_extras – If true, extra cards (tokens, planes, etc) will be included. Equivalent to adding include:extras to the fulltext search.
include_multilingual – If true, cards in every language supported by Scryfall will be included.
include_variations – If true, rare care variants will be included, like the Hairy Runesword.
q – A fulltext search query.
limit – The number of item to return, please note that Mightstone wraps Scryfall pagination and streams the results
- Returns:
A scryfall Card instance async generator
- set(limit: int = None) AsyncGenerator[Set, None]
Sync version of
sets_async()
, same behavior but wrapped byasync_to_sync()
.
- async set_async(id_or_code: Optional[str] = None) Set
Returns a Set with the given set code.
- Parameters:
id_or_code – The code can be either the code or the mtgo_code or the scryfall UUID for the set.
- Returns:
A Set instance
- sets(limit: int = None) AsyncGenerator[Set, None]
Sync version of
sets_async()
, same behavior but wrapped byasync_to_sync()
.
- async sets_async(limit: Optional[int] = None) AsyncGenerator[Set, None]
Returns a List object of all Sets on Scryfall.
- Parameters:
limit – The number of item to return, please note that Mightstone wraps Scryfall pagination and streams the results
- Returns:
A Set instance async generator
Models
|
An enumeration. |
|
|
Rulings represent Oracle rulings, Wizards of the Coast set release notes, or Scryfall notes for a particular card. |
|
A Set object represents a group of related Magic cards. All Card objects on Scryfall |
|
A Card Symbol object represents an illustrated symbol that may appear in card’s mana cost or Oracle text. |
|
MTGJSON
MTGJSON is an open-source project that catalogs all Magic: The Gathering data in portable formats. Using an aggregation process we fetch information between multiple resources and approved partners, and combine all that data in to various downloadable formats.
Feature |
Support |
---|---|
JSON data |
✅ |
Compressed JSON data |
✅ (except zip) |
SQLite data |
❌ |
CSV data |
❌ |
GraphQL API |
❌ |
MtgJson Client
- class mightstone.services.mtgjson.MtgJson(compression: Optional[MtgJsonCompression] = None, version: int = 5, *args, **kwargs)
MTGJSON client
Supports compression and will get gzip versions by default.
- all_identifiers() AsyncGenerator[Card, None]
Sync version of
all_identifiers_async()
, same behavior but wrapped byasync_to_sync()
.
- async all_identifiers_async() AsyncGenerator[Card, None]
all Card (Set) cards organized by card UUID.
- Returns:
An async iterator of Card object (either CardToken, or CardSet)
- all_prices() AsyncGenerator[CardPrices, None]
Sync version of
all_prices_async()
, same behavior but wrapped byasync_to_sync()
.
- async all_prices_async() AsyncGenerator[CardPrices, None]
all prices of cards in various formats.
- Returns:
An async iterator of CardPrices
- all_printings() AsyncGenerator[Set, None]
Sync version of
all_printings_async()
, same behavior but wrapped byasync_to_sync()
.
- async all_printings_async() AsyncGenerator[Set, None]
all Card (Set) cards, including all printings and variations, categorized by set.
- Returns:
An async iterator of CardSet
- atomic_cards() AsyncGenerator[CardAtomic, None]
Sync version of
atomic_cards_async()
, same behavior but wrapped byasync_to_sync()
.
- async atomic_cards_async() AsyncGenerator[CardAtomic, None]
every Card (Atomic) card.
- Returns:
An async iterator of
CardAtomic
- base_url: str = 'https://mtgjson.com'
Base url of the service (must be a root path such as https://example.com)
- card_types() CardTypes
Sync version of
card_types_async()
, same behavior but wrapped byasync_to_sync()
.
- async card_types_async() CardTypes
every card type of any type of card.
- Returns:
A
CardTypes
object
- compiled_list() List[str]
Sync version of
compiled_list_async()
, same behavior but wrapped byasync_to_sync()
.
- async compiled_list_async() List[str]
all individual outputs from MTGJSON, such as AllPrintings, CardTypes, etc.
- Returns:
A list of string
- deck(file_name: str) Deck
Sync version of
deck_async()
, same behavior but wrapped byasync_to_sync()
.
- async deck_async(file_name: str) Deck
Recovers a deck data
- Parameters:
file_name – the deck file_name
- Returns:
A
Deck
object
- deck_list() AsyncGenerator[DeckList, None]
Sync version of
deck_list_async()
, same behavior but wrapped byasync_to_sync()
.
- async deck_list_async() AsyncGenerator[DeckList, None]
all individual Deck data.
- Returns:
An async iterator of DeckList
- enum_values() dict
Sync version of
enum_values_async()
, same behavior but wrapped byasync_to_sync()
.
- async enum_values_async() dict
All known property values for various Data Models.
- Returns:
a
dict
object
- keywords() Keywords
Sync version of
keywords_async()
, same behavior but wrapped byasync_to_sync()
.
- async keywords_async() Keywords
a list of possible all keywords used on all cards.
- Returns:
A
Keywords
object
- legacy() AsyncGenerator[Set, None]
Sync version of
legacy_async()
, same behavior but wrapped byasync_to_sync()
.
- async legacy_async() AsyncGenerator[Set, None]
all Card (Set) cards organized by Set, restricted to sets legal in the Legacy format.
- Returns:
An async iterator of
Set
- legacy_atomic() AsyncGenerator[CardAtomic, None]
Sync version of
legacy_atomic_async()
, same behavior but wrapped byasync_to_sync()
.
- async legacy_atomic_async() AsyncGenerator[CardAtomic, None]
all Card (Set) cards organized by Set, restricted to sets legal in the Legacy format.
- Returns:
An async iterator of
CardAtomic
- async meta_async() Meta
the metadata object with ISO 8601 dates for latest build and SemVer specifications of the MTGJSON release.
- Returns:
A Meta object
- modern() AsyncGenerator[Set, None]
Sync version of
modern_async()
, same behavior but wrapped byasync_to_sync()
.
- async modern_async() AsyncGenerator[Set, None]
all Card (Set) cards organized by Set, restricted to sets legal in the Modern format.
- Returns:
An async iterator of
Set
- modern_atomic() AsyncGenerator[CardAtomic, None]
Sync version of
modern_atomic_async()
, same behavior but wrapped byasync_to_sync()
.
- async modern_atomic_async() AsyncGenerator[CardAtomic, None]
all Card (Atomic) cards, restricted to cards legal in the Modern format.
- Returns:
An async iterator of
CardAtomic
- pauper_atomic() AsyncGenerator[CardAtomic, None]
Sync version of
pauper_atomic_async()
, same behavior but wrapped byasync_to_sync()
.
- async pauper_atomic_async() AsyncGenerator[CardAtomic, None]
all Card (Atomic) cards, restricted to cards legal in the Pauper format.
- Returns:
An async iterator of
CardAtomic
- pioneer() AsyncGenerator[Set, None]
Sync version of
pioneer_async()
, same behavior but wrapped byasync_to_sync()
.
- async pioneer_async() AsyncGenerator[Set, None]
all Card (Set) cards organized by Set, restricted to cards legal in the Pioneer format.
- Returns:
An async iterator of
Set
- pioneer_atomic() AsyncGenerator[CardAtomic, None]
Sync version of
pioneer_atomic_async()
, same behavior but wrapped byasync_to_sync()
.
- async pioneer_atomic_async() AsyncGenerator[CardAtomic, None]
all Card (Atomic) cards, restricted to cards legal in the Pioneer format.
- Returns:
An async iterator of
CardAtomic
- async set_async(code: str) SetList
Get a Set data
- Parameters:
code – The set identifier, such as “IKO” for “Ikoria, lair of the monsters”
- Returns:
The set representation
- set_list() AsyncGenerator[SetList, None]
Sync version of
set_list_async()
, same behavior but wrapped byasync_to_sync()
.
- async set_list_async() AsyncGenerator[SetList, None]
a list of meta data for all Set data.
- Returns:
An async iterator of
SetList
- standard() AsyncGenerator[Set, None]
Sync version of
standard_async()
, same behavior but wrapped byasync_to_sync()
.
- async standard_async() AsyncGenerator[Set, None]
all Card (Set) cards organized by Set, restricted to cards legal in the Standard format.
- Returns:
An async iterator of
Set
- standard_atomic() AsyncGenerator[CardAtomic, None]
Sync version of
standard_atomic_async()
, same behavior but wrapped byasync_to_sync()
.
- async standard_atomic_async() AsyncGenerator[CardAtomic, None]
all Card (Atomic) cards, restricted to cards legal in the Standard format.
- Returns:
An async iterator of
CardAtomic
- tcg_player_skus() AsyncGenerator[TcgPlayerSKUs, None]
Sync version of
tcg_player_skus_async()
, same behavior but wrapped byasync_to_sync()
.
- async tcg_player_skus_async() AsyncGenerator[TcgPlayerSKUs, None]
TCGplayer SKU information based on card UUIDs.
- Returns:
an async iterator of
TcgPlayerSKUs
- vintage() AsyncGenerator[Set, None]
Sync version of
vintage_async()
, same behavior but wrapped byasync_to_sync()
.
- async vintage_async() AsyncGenerator[Set, None]
all Card (Set) cards organized by Set, restricted to sets legal in the Vintage format.
- Returns:
An async iterator of
Set
- vintage_atomic() AsyncGenerator[CardAtomic, None]
Sync version of
vintage_atomic_async()
, same behavior but wrapped byasync_to_sync()
.
- async vintage_atomic_async() AsyncGenerator[CardAtomic, None]
all Card (Atomic) cards, restricted to sets legal in the Vintage format.
- Returns:
An async iterator of
CardAtomic
Models
A card either a Card from a set, or a token |
|
The Set List Data Model describes a metadata-like properties and values for an individual Set. |
|
The Deck Data Model describes a complete deck reference. |
|
The Deck List Data Model describes a metadata-like model for a Deck. |
|
The Card Types Data Model describes card types that a card may have. |
Card Conjurer
Card Conjurer is a card editor service that provides a unique file format to describe a card image. Each card is described in a JSON file that extends a template. Template may vary from MTG copycat to brand new card frame.
Feature |
Support |
---|---|
Template |
✅ (read-only) |
Card |
✅ (read-only) |
Card Generation |
🟠 Working for the most part, but inline symbols are not supported |
CardConjurer Client
- class mightstone.services.cardconjurer.CardConjurer(default_font=None, **kwargs)
Card Conjurer client
- base_url: str
Base url of the service (must be a root path such as https://example.com)
- card(url_or_path) Card
Sync version of
card_async()
, same behavior but wrapped byasync_to_sync()
.
- async card_async(url_or_path) Card
Open a
Card
, local or through HTTP- Parameters:
url_or_path – A path or an url
- Returns:
Card
instance
- render(card: Card, output=None) Image
Sync version of
render_async()
, same behavior but wrapped byasync_to_sync()
.
- async render_async(card: Card, output=None) Image
Render a card object into a PIL Image
- Parameters:
card – Card model from Card Conjurer
output – A path or a file like object for writing
- Returns:
A PIL Image object
Models
A Card as described in Card Conjurer JSON |
|
A Template as described in Card Conjurer JSON |
|
A layer composed of an image (One of the 3 possible layer types) |
|
A layer composed of a text (One of the 3 possible layer types) |
|
A layer composed of a list of other layers (One of the 3 possible layer types) |
Wizards Of The Coast
RuleExplorer Client
- class mightstone.services.wotc.RuleExplorer(transport: Optional[BaseTransport] = None)
- base_url: str = 'https://media.wizards.com'
Base url of the service (must be a root path such as https://example.com)
- explore(after: date, before: date = None, concurrency=3) List[str]
Sync version of
explore_async()
, same behavior but wrapped byasync_to_sync()
.
- async explore_async(after: date, before: Optional[date] = None, concurrency=3) List[str]
Explore the wizards of the coast website to find any rule between two timestamp.
Wizards don’t support an historic index of previous rules, this method tries to compensate by providing a brute force attempt to pull magic rule history. This method will brute force every possible rule using the current format:
https://media.wizards.com/YYYY/downloads/MagicComp%20Rules%20{YYYY}{MM}{DD}.txt
- Parameters:
after – The min date to scan
before – The max date to scan (defaults to today)
concurrency – The max number of concurrent HTTP requests
- Returns:
A list of existing rules url
- latest() str
Sync version of
latest_async()
, same behavior but wrapped byasync_to_sync()
.
- async latest_async() str
Resolves wizard latest published ruleset
- Returns:
The url of the latest ruleset to date
- open(path: str = None) ComprehensiveRules
Sync version of
open_async()
, same behavior but wrapped byasync_to_sync()
.
- async open_async(path: Optional[str] = None) ComprehensiveRules
Open a local or remote comprehensive rule document, if no path is provided then the latest rules from Wizards of the Coast website is pulled.
- Parameters:
path – A local path, or an URL to the rule document
- Returns:
A
ComprehensiveRules
instance