Title: | An Interface to the 'Scryfall' API |
---|---|
Description: | A simple, light, and robust interface between R and the 'Scryfall' card data API <https://scryfall.com/docs/api>. |
Authors: | Caio Lente [aut, cre] , Scryfall [cph], Wizards of the Coast [cph], Curso-R [cph, fnd] |
Maintainer: | Caio Lente <[email protected]> |
License: | MIT + file LICENSE |
Version: | 1.0.0.9000 |
Built: | 2024-11-01 03:09:04 UTC |
Source: | https://github.com/curso-r/scryr |
Returns a string vector of up to 20 full English card names that could be
autocompletions of the given name
argument.
autocomplete_name(name, include_extras = FALSE)
autocomplete_name(name, include_extras = FALSE)
name |
A string with a card's name (or part of it). See details. |
include_extras |
If |
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 name
is less than 2 characters long, or if no names match, the vector
will contain 0 elements (instead of returning any errors).
A string vector.
https://scryfall.com/docs/api/cards/autocomplete
# Get all related card names autocomplete_name("falken")
# Get all related card names autocomplete_name("falken")
Parses the given mana cost
argument and returns Scryfall's interpretation.
parse_cost(cost)
parse_cost(cost)
cost |
The mana string to parse. For more information, see details. |
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 return an error describing the problem.
A data frame with 1 row and the following columns:
cost
[chr]: The normalized cost, with correctly-ordered and wrapped
mana symbols.
colors
[list]: The colors of the given cost.
cmc
[dbl]: The converted mana cost. If you submit Un-set mana symbols,
this decimal could include fractional parts.
colorless
[lgl]: Whether the cost is colorless.
monocolored
[lgl]: Whether if the cost is monocolored.
multicolored
[lgl]: Whether if the cost is multicolored.
https://scryfall.com/docs/api/card-symbols/parse-mana
# Parse mana costs parse_cost("2g2")
# Parse mana costs parse_cost("2g2")
Scryfall provides daily exports of our card data in bulk files. Each of these
files is represented as a bulk_data
object via the API. See details.
scry_bulk_files() scry_bulk_file(name)
scry_bulk_files() scry_bulk_file(name)
name |
A string with file to be downloaded. Can be any one of
|
URLs for files change their timestamp each day, and can be fetched programmatically. The currently available files are the following:
Oracle Cards: A JSON file containing one Scryfall card for each Oracle ID on Scryfall. The chosen sets for the cards are an attempt to return the most up-to-date recognizable version of the card.
Unique Artwork: A JSON file of Scryfall cards that together contain all unique artworks. The chosen cards promote the best image scans.
Default Cards: A JSON file containing every card on Scryfall in English or the printed language if the card is only available in one language.
All Cards: A JSON file containing every card on Scryfall in every language.
Rulings: A JSON file containing all Rulings on Scryfall. Each ruling refers
to cards via an oracle_id
.
Please note:
Cards in bulk data include price information, but prices should be considered dangerously stale after 24 hours. Only use bulk price information to track trends or provide a general estimate of card value. Prices are not updated frequently enough to power a storefront or sales system. You consume price information at your own risk.
Updates to gameplay data (such as card names, Oracle text, mana costs, etc) are much less frequent. If you only need gameplay information, downloading card data once per week or right after set releases would most likely be sufficient.
Every card type in every product is included, including planar cards, schemes, Vanguard cards, tokens, emblems, and funny cards.
Bulk data is only collected once every 12 hours. You can use scry_cards()
to retrieve fresh objects instead.
A data frame with 1 or more rows and the following columns:
id
[chr]: A unique ID for this bulk item.
name
[chr]: A human-readable name for this file. See details.
type
[chr]: A computer-readable string for the kind of bulk item.
updated_at
[dttm]: The time when this file was last updated.
uri
[chr]: The Scryfall API URI for this file.
description
[chr]: A human-readable description for this file.
compressed_size
[int]: The size of this file in integer bytes.
download_uri
[chr]: The URI that hosts this bulk file for fetching.
content_type
[chr]: The MIME type of this file.
content_encoding
[chr]: The Content-Encoding encoding that will be used
to transmit this file when you download it.
https://scryfall.com/docs/api/bulk-data
# Get information about bulk data files scry_bulk_files() # Download a bulk data file scry_bulk_file("Rulings")
# Get information about bulk data files scry_bulk_files() # Download a bulk data file scry_bulk_file("Rulings")
Cards represent individual Magic: The Gathering playing cards that players could obtain and add to their collection (with a few minor exceptions).
Cards are the API's most complex object. You are encouraged to thoroughly
read this document and also vignette("layouts")
.
scry_cards( q, unique = "cards", order = "name", dir = "auto", include_extras = FALSE, include_multilingual = FALSE, include_variations = FALSE, page = NULL ) scry_card(id, source = "scryfall") scry_card_name(name, mode = c("fuzzy", "exact"), set = NULL) scry_card_number(number, set, lang = "en") scry_card_random(q = NULL)
scry_cards( q, unique = "cards", order = "name", dir = "auto", include_extras = FALSE, include_multilingual = FALSE, include_variations = FALSE, page = NULL ) scry_card(id, source = "scryfall") scry_card_name(name, mode = c("fuzzy", "exact"), set = NULL) scry_card_number(number, set, lang = "en") scry_card_random(q = NULL)
q |
A search query using the same fulltext search system that Scryfall
uses. For more information see |
unique |
The strategy for omitting similar cards. The options are:
|
order |
The method to sort returned cards. The options are:
|
dir |
The direction to sort cards. The options are:
|
include_extras |
If |
include_multilingual |
If |
include_variations |
If |
page |
The results' page number to return. If |
id |
Unique card identifier. May refer to any supported |
source |
Source to which |
name |
A string with a card's name (or part of it). |
mode |
Search mode. Can be either |
set |
The three to five-letter set code. |
number |
The card's collector number for a set. |
lang |
The 2-3 character language code. For more information, see
|
A data frame with 1 or more rows and the following columns:
id
[chr]: A unique ID for this card in Scryfall's database.
name
[chr]: The name of this card. If this card has multiple faces,
this column will contain both names separated by ␣//␣
.
set
[chr]: This card's set code.
lang
[chr]: A language code for this printing. For more information,
see vignette("languages")
colors
[list]: This card's colors, if the overall card has colors
defined by the rules. Otherwise the colors will be on the card_faces
column, see below.
color_identity
[list]: This card's color identity.
color_indicator
[list]: The colors in this card's color indicator, if
any. A NULL
value for this column indicates the card does not have one.
mana_cost
[chr]: The mana cost for this card. This value will be any
empty string ""
if the cost is absent. Remember that per the game rules,
a missing mana cost and a mana cost of {0}
are different values.
Multi-faced cards will report this value in card_faces
, see below.
cmc
[dbl]: The card's converted mana cost. Note that some funny cards
have fractional mana costs.
oracle_text
[chr]: The Oracle text for this card, if any.
power
[chr]: This card's power, if any. Note that some cards have
powers that are not numeric, such as *
.
toughness
[chr]: This card's toughness, if any. Note that some cards
have toughnesses that are not numeric, such as *
.
type_line
[chr]: The type line of this card.
edhrec_rank
[int]: This card's overall rank/popularity on EDHREC. Not
all cards are ranked.
hand_modifier
[chr]: This card's hand modifier, if it is Vanguard card.
This value will contain a delta, such as -1
.
keywords
[list]: A vector of keywords that this card uses, such as
Flying
and Cumulative upkeep
.
layout
[chr]: A code for this card's layout. For more information see
vignette("layouts")
legalities
[list]: A data frame describing the legality of this card
across play formats. Possible legalities are legal
, not_legal
,
restricted
, and banned
.
life_modifier
[chr]: This card's life modifier, if it is Vanguard card.
This value will contain a delta, such as +2
.
loyalty
[chr]: This loyalty if any. Note that some cards have loyalties
that are not numeric, such as X
.
oversized
[lgl]: Whether this card is oversized.
produced_mana
[list]: Colors of mana that this card could produce.
reserved
[lgl]: Whether this card is on the Reserved List.
oracle_id
[chr]: A unique ID for this card's oracle identity. This
value is consistent across reprinted card editions, and unique among
different cards with the same name (tokens, Unstable variants, etc).
arena_id
[int]: This card's Arena ID, if any. A large percentage of
cards are not available on Arena and do not have this ID.
mtgo_id
, mtgo_foil_id
[int]: This card's Magic Online ID (also known
as the Catalog ID), if any. A large percentage of cards are not available
on Magic Online and do not have this ID.
multiverse_ids
[list]: This card's multiverse IDs on Gatherer, if any,
as a vector of integers. Note that Scryfall includes many promo cards,
tokens, and other esoteric objects that do not have these identifiers.
tcgplayer_id
, tcgplayer_etched_id
[int]: This card's ID on
TCGplayer's API, also known as the
productId
.
cardmarket_id
[int]: This card's ID on Cardmarket's API, also known as
the idProduct
.
uri
[chr]: A link to this card on Scryfall's API.
scryfall_uri
[chr]: A link to this card's permapage on Scryfall's
rulings_uri
[chr]: A link to this card's rulings list on Scryfall's
API. For more information see scry_ruling()
prints_search_uri
[chr]: A link to where you can begin paginating all
re/prints for this card on Scryfall's API.
website.
all_parts
[list]: If this card is closely related to other cards, this
column will be a data frame with the following columns:
id
[chr]: An unique ID for this card in Scryfall's database.
object
[chr]: A content type for this object, always related_card
.
component
[chr]: A column explaining what role this card plays in
this relationship, one of token
, meld_part
, meld_result
, or
combo_piece
.
name
[chr]: The name of this particular related card.
type_line
[chr]: The type line of this card.
uri
[chr]: A URI where you can retrieve a full object describing this
card on Scryfall's API.
card_faces
[list]: A data frame of card faces (if this card is
multifaced) with the following columns. For more information see
vignette("layouts")
.
name
[chr]: The name of this particular face.
colors
[list]: This face's colors, if the game defines colors for the
individual face of this card.
color_indicator
[list]: The colors in this face's color indicator, if
any.
mana_cost
[chr]: The mana cost for this face. This value will be any
empty string ""
if the cost is absent. Remember that per the game
rules, a missing mana cost and a mana cost of {0}
are different values.
cmc
[dbl]: The mana value of this particular face, if the card is
reversible.
oracle_text
[chr]: The Oracle text for this face, if any.
power
[chr]: This face's power, if any. Note that some cards have
powers that are not numeric, such as *
.
toughness
[chr]: This face's toughness, if any.
type_line
[chr]: The type line of this particular face, if the card
is reversible.
layout
[chr]: The layout of this card face, if the card is
reversible.
loyalty
[chr]: This face's loyalty, if any.
oracle_id
[chr]: The Oracle ID of this particular face, if the card
is reversible.
artist
[chr]: The name of the illustrator of this card face. Newly
spoiled cards may not have this column yet.
artist_id
[chr]: This faces's illustrator's unique identifier.
flavor_name
[chr]: The just-for-fun name printed on the card (such as
for Godzilla series cards).
flavor_text
[chr]: The flavor text printed on this face, if any.
illustration_id
[chr]: A unique identifier for the card face artwork
that remains consistent across reprints. Newly spoiled cards may not have
this column yet.
image_uris
[list]: A data frame providing URIs to imagery for this
face, if this is a double-sided card. If this card is not double-sided,
then the image_uris
column will be part of the parent object instead.
printed_name
[chr]: The localized name printed on this face, if any.
printed_text
[chr]: The localized text printed on this face, if any.
printed_type_line
[chr]: The localized type line printed on this
face, if any.
watermark
[chr]: The watermark on this particularly card face, if
any.
artist
[chr]: The name of the illustrator of this card. Newly spoiled
cards may not have this column yet.
booster
[lgl]: Whether this card is found in boosters.
border_color
[chr]: This card's border color: black
, white
,
borderless
, silver
, or gold
.
card_back_id
[chr]: The Scryfall ID for the card back design present on
this card.
collector_number
[chr]: This card's collector number. Note that
collector numbers can contain non-numeric characters, such as letters or
stars.
content_warning
[lgl]: TRUE
if you should consider avoiding use of
this print downstream.
digital
[lgl]: Whether this card was only released in a video game.
finishes
[list]: A vector of computer-readable flags that indicate if
this card can come in foil
, nonfoil
, etched
, or glossy
finishes.
flavor_name
[chr]: The just-for-fun name printed on the card (such as
for Godzilla series cards).
flavor_text
[chr]: The flavor text, if any.
frame_effects
[list]: This card's frame effects, if any. For more
information see vignette("frames")
.
frame
[chr]: This card's frame layout. For more information see
vignette("frames")
.
full_art
[lgl]: Whether this card's artwork is larger than normal.
games
[list]: A vector of games that this card print is available in,
paper
, arena
, and/or mtgo
.
highres_image
[lgl]: Whether this card's imagery is high resolution.
illustration_id
[chr]: A unique identifier for the card artwork that
remains consistent across reprints. Newly spoiled cards may not have this
column yet.
image_status
[chr]: A computer-readable indicator for the state of this
card's image, one of missing
, placeholder
, lowres
, or highres_scan
.
image_uris
[list]: A data frame listing available imagery for this
card. For more information see vignette("imagery")
.
preview
[list]: A data frame providing information about this card's
preview.
prices
[list]: A data frame containing daily price information for this
card, including usd
, usd_foil
, usd_etched
, eur
, and tix
prices,
as strings.
printed_name
[chr]: The localized name printed on this card, if any.
printed_text
[chr]: The localized text printed on this card, if any.
printed_type_line
[chr]: The localized type line printed on this card,
if any.
promo
[lgl]: Whether this card is a promotional print.
promo_types
[list]: A vector of strings describing what categories of
promo cards this card falls into.
purchase_uris
[list]: A data frame providing URIs to this card's
listing on major marketplaces.
rarity
[chr]: This card's rarity. One of common
, uncommon
, rare
,
special
, mythic
, or bonus
.
related_uris
[list]: A data frame providing URIs to this card's listing
on other Magic: The Gathering online resources.
released_at
[date]: The date this card was first released.
reprint
[lgl]: Whether this card is a reprint.
scryfall_set_uri
[chr]: A link to this card's set on Scryfall's
website.
set_name
[chr]: This card's full set name.
set_search_uri
[chr]: A link to where you can begin paginating this
card's set on the Scryfall API.
set_type
[chr]: The type of set this printing is in.
set_uri
[chr]: A link to this card's set on Scryfall's API. For more
information see ?scry_sets()
.
set_id
[chr]: This card's set Scryfall ID.
story_spotlight
[lgl]: Whether this card is a Story Spotlight.
textless
[lgl]: Whether the card is printed without text.
variation
[lgl]: Whether this card is a variation of another printing.
variation_of
[chr]: The printing ID of the printing this card is a
variation of.
security_stamp
[chr]: The security stamp on this card, if any. One of
oval
, triangle
, acorn
, or arena
.
watermark
[chr]: This card's watermark, if any.
https://scryfall.com/docs/api/cards
# Get all legendary vampires scry_cards("t:vampire t:legend") # Get card using an ID scry_card("913dd06f-ed2f-4128-9c9d-9cd0d8a55425") # Get card using a name scry_card_name("Anje Falkenrath") # Get card using a collector number and a set scry_card_number(37, "c19") # Just get a random legendary vampires scry_card_random("t:vampire t:legend")
# Get all legendary vampires scry_cards("t:vampire t:legend") # Get card using an ID scry_card("913dd06f-ed2f-4128-9c9d-9cd0d8a55425") # Get card using a name scry_card_name("Anje Falkenrath") # Get card using a collector number and a set scry_card_number(37, "c19") # Just get a random legendary vampires scry_card_random("t:vampire t:legend")
Scryfall has multiple catalog datapoints (words, card values, etc). They are provided by the API as aids for building other Magic software and understanding possible values for a column.
scry_catalog(name)
scry_catalog(name)
name |
A string with the name of the catalog to return. Can be one of:
|
A string vector.
https://scryfall.com/docs/api/catalogs
# Get information from a catalog scry_catalog("keyword-actions")
# Get information from a catalog scry_catalog("keyword-actions")
Oracle rulings are Wizards of the Coast's set release notes or Scryfall's notes for a particular card.
scry_ruling(id, source = "scryfall") scry_ruling_number(number, set)
scry_ruling(id, source = "scryfall") scry_ruling_number(number, set)
id |
Unique card indentifier. May refer to any supported |
source |
Source to which |
number |
The card's collector number for a set. |
set |
The three to five-letter set code. |
Rulings with a scryfall
source have been added by the Scryfall team, either
to provide additional context for the card, or explain how the card works in
an unofficial format (such as Duel Commander).
A data frame with 1 or more rows and the following columns:
oracle_id
[chr]: Unique identifier on the Oracle database.
source
[chr]: A computer-readable string indicating which company
produced this ruling, either wotc
or scryfall
. See details.
published_at
[date]: The date when the ruling or note was published.
comment
[chr]: The text of the ruling.
https://scryfall.com/docs/api/rulings
# Get rulings for a card scry_ruling("913dd06f-ed2f-4128-9c9d-9cd0d8a55425")
# Get rulings for a card scry_ruling("913dd06f-ed2f-4128-9c9d-9cd0d8a55425")
A Set represents a group of related Magic cards. All cards on Scryfall belong to exactly one set.
scry_sets() scry_set(id, source = "code")
scry_sets() scry_set(id, source = "code")
id |
Unique set indentifier. May refer to any supported |
source |
Source to which |
Due to Magic's long and complicated history, Scryfall includes many
un-official sets as a way to group promotional or outlier cards together.
Such sets will likely have a code that begins with p
or t
, such as pcel
or tori
. Official sets always have a three-letter set code, such as zen
.
A data frame with 1 or more rows and the following columns:
id
[chr]: A unique ID for this set on Scryfall that will not change.
code
[chr]: The unique three to five-letter code for this set. See
details.
name
[chr]: The English name of the set.
mtgo_code
[chr]: The unique code for this set on MTGO, which may differ
from the regular code.
arena_code
[chr]: The unique code for this set on MTG Arena, which may
differ from the regular code.
tcgplayer_id
[int]: This set’s ID on TCGplayer’s API, also known as the
groupId
.
uri
[chr]: A link to this set on Scryfall’s API.
scryfall_uri
[chr]: A link to this set’s permapage on Scryfall’s
search_uri
[chr]: A Scryfall API URI that you can request to begin
paginating over the cards in this set.
released_at
[date]: The date the set was released or the first card was
printed in the set (in GMT-8 Pacific time).
set_type
[chr]: Scryfall provides an overall categorization for each
Set in the set_type
property. The options are:
core
: A yearly Magic core set (Tenth Edition, etc).
expansion
: A rotational expansion set in a block (Zendikar, etc).
masters
: A reprint set that contains no new cards (Modern Masters,
etc).
masterpiece
: Masterpiece Series premium foil cards.
arsenal
: A Commander-oriented gift set.
from_the_vault
: From the Vault gift sets.
spellbook
: Spellbook series gift sets.
premium_deck
: Premium Deck Series decks.
duel_deck
: Duel Decks.
draft_innovation
: Special draft sets, like Conspiracy and Battlebond.
treasure_chest
: Magic Online treasure chest prize sets.
commander
: Commander preconstructed decks.
planechase
: Planechase sets.
archenemy
: Archenemy sets.
vanguard
: Vanguard card sets.
funny
: A funny un-set or set with funny promos (Unglued, Happy.
Holidays, etc).
starter
: A starter/introductory set (Portal, etc).
box
: A gift box set.
promo
: A set that contains purely promotional cards.
token
: A set made up of tokens and emblems..
memorabilia
: A set made up of gold-bordered, oversize, or trophy cards.
that are not legal.
card_count
[int]: The number of cards in this set.
parent_set_code
[chr]: The set code for the parent set, if any. promo
and token
sets often have a parent set.
printed_size
[int]: The denominator for the set’s printed collector
numbers.
digital
[lgl]: Whether this set was only released in a video game.
nonfoil_only
[lgl]: Whether this set contains only nonfoil cards.
foil_only
[lgl]: Whether this set contains only foil cards.
block_code
[chr]: The block code for this set, if any.
block
[chr]: The block or group name code for this set, if any.
icon_svg_uri
[chr]: A URI to an SVG file for this set’s icon on
Scryfall’s CDN. Hotlinking this image isn’t recommended, because it may
change slightly over time. You should download it and use it locally for
your particular user interface needs.
https://scryfall.com/docs/api/sets
# Get all sets scry_sets() # Get set using an ID scry_set("vow")
# Get all sets scry_sets() # Get set using an ID scry_set("vow")
An illustrated symbol may appear in card's mana cost or Oracle text. Symbols are based on the notation used in the Comprehensive Rules.
For more information about how the Scryfall API represents mana and costs,
see vignette("colors")
.
scry_symbols()
scry_symbols()
A data frame with 1 row and the following columns:
symbol
[chr]: The plaintext symbol. Often surrounded with curly braces.
Note that not all symbols are ASCII text (for example, the infinity
symbol).
colors
[list]: A vector of colors that this symbol represents.
cmc
[dbl]: A decimal number representing this symbol’s converted mana
cost. Note that mana symbols from funny sets can have fractional converted
mana costs.
loose_variant
[chr]: An alternate version of this symbol, if it is
possible to write it without curly braces.
english
[chr]: An English snippet that describes this symbol.
Appropriate for use in alt text or other accessible communication formats.
gatherer_alternates
[list]: A vector of plaintext versions of this
symbol that Gatherer uses on old cards to describe original printed text.
For example: {W}
has <"oW", "ooW">
as alternates.
transposable
[lgl]: Whether it is possible to write this symbol
"backwards". For example, the official symbol {U/P}
is sometimes written
as {P/U}
or {P\U}
in informal settings.
represents_mana
[lgl]: Whether this is a mana symbol.
appears_in_mana_costs
[lgl]: Whether this symbol appears in a mana cost
on any Magic card. For example {20}
has this column set to FALSE
because {20}
only appears in Oracle text, not mana costs.
funny
[lgl]: Whether this symbol is only used on funny cards or
Un-cards.
svg_uri
[chr]: A URI to an SVG image of this symbol on Scryfall’s CDNs.
https://scryfall.com/docs/api/card-symbols
# Get information about symbols scry_symbols()
# Get information about symbols scry_symbols()