Title: An Interface to the 'Scryfall' API
Version: 1.0.0
Description: A simple, light, and robust interface between R and the 'Scryfall' card data API https://scryfall.com/docs/api.
License: MIT + file LICENSE
URL: https://curso-r.github.io/scryr/, https://github.com/curso-r/scryr
Imports: dplyr, httr, purrr, tibble
Suggests: covr, httptest, knitr, rmarkdown, testthat (≥ 3.0.0)
VignetteBuilder: knitr
Config/testthat/edition: 3
Config/testthat/parallel: true
Encoding: UTF-8
RoxygenNote: 7.1.2
NeedsCompilation: no
Packaged: 2022-01-27 14:21:11 UTC; clente
Author: Caio Lente ORCID iD [aut, cre], Scryfall [cph], Wizards of the Coast [cph], Curso-R [cph, fnd]
Maintainer: Caio Lente <clente@curso-r.com>
Repository: CRAN
Date/Publication: 2022-01-28 08:20:05 UTC

Autocomplete the name of a card

Description

Returns a string vector of up to 20 full English card names that could be autocompletions of the given name argument.

Usage

autocomplete_name(name, include_extras = FALSE)

Arguments

name

A string with a card's name (or part of it). See details.

include_extras

If TRUE, extra cards (tokens, planes, etc) will be included.

Details

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

Value

A string vector.

References

https://scryfall.com/docs/api/cards/autocomplete

Examples


# Get all related card names
autocomplete_name("falken")

Parse mana costs

Description

Parses the given mana cost argument and returns Scryfall's interpretation.

Usage

parse_cost(cost)

Arguments

cost

The mana string to parse. For more information, see details.

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.

Value

A data frame with 1 row and the following columns:

References

https://scryfall.com/docs/api/card-symbols/parse-mana

Examples


# Parse mana costs
parse_cost("2g2")

Retrieve information about bulk data files

Description

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.

Usage

scry_bulk_files()

scry_bulk_file(name)

Arguments

name

A string with file to be downloaded. Can be any one of ⁠Oracle Cards⁠, ⁠Unique Artwork⁠, ⁠Default Cards⁠, ⁠All Cards⁠ or Rulings. See details.

Details

URLs for files change their timestamp each day, and can be fetched programmatically. The currently available files are the following:

Please note:

Bulk data is only collected once every 12 hours. You can use scry_cards() to retrieve fresh objects instead.

Value

A data frame with 1 or more rows and the following columns:

References

https://scryfall.com/docs/api/bulk-data

Examples


# Get information about bulk data files
scry_bulk_files()

# Download a bulk data file
scry_bulk_file("Rulings")

Retrieve information about cards

Description

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

Usage

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)

Arguments

q

A search query using the same fulltext search system that Scryfall uses. For more information see vignette("syntax").

unique

The strategy for omitting similar cards. The options are:

  • cards: Removes duplicate gameplay objects (cards that share a name and have the same functionality). For example, if your search matches more than one print of Pacifism, only one copy of Pacifism will be returned.

  • art: Returns only one copy of each unique artwork for matching cards. For example, if your search matches more than one print of Pacifism, one card with each different illustration for Pacifism will be returned, but any cards that duplicate artwork already in the results will be omitted.

  • prints: Returns all prints for all cards matched (disables rollup). For example, if your search matches more than one print of Pacifism, all matching prints will be returned.

order

The method to sort returned cards. The options are:

  • name: Sort cards by name, A -> Z.

  • set: Sort cards by their set and collector number: AAA/#1 -> ZZZ/#999.

  • released: Sort cards by their release date: Newest -> Oldest.

  • rarity: Sort cards by their rarity: Common -> Mythic.

  • color: Sort cards by their color and color identity: WUBRG -> multicolor -> colorless.

  • usd: Sort cards by their lowest known U.S. Dollar price: 0.01 -> highest, NA last.

  • tix: Sort cards by their lowest known TIX price: 0.01 -> highest, NA last.

  • eur: Sort cards by their lowest known Euro price: 0.01 -> highest, NA last.

  • cmc: Sort cards by their converted mana cost: 0 -> highest.

  • power: Sort cards by their power: NA -> highest.

  • toughness: Sort cards by their toughness: NA -> highest.

  • edhrec: Sort cards by their EDHREC ranking: lowest -> highest.

  • artist: Sort cards by their front-side artist name: A -> Z.

  • review: Sort cards how podcasts review sets, usually color & CMC, lowest -> highest, with Booster Fun cards at the end.

dir

The direction to sort cards. The options are:

  • auto: Scryfall will automatically choose the most intuitive direction to sort.

  • asc: Sort ascending (the direction of the arrows in the previous argument).

  • desc: Sort descending (flip the direction of the arrows in the previous argument).

include_extras

If TRUE, extra cards (tokens, planes, etc) will be included. Equivalent to adding include:extras to the search query.

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.

page

The results' page number to return. If NULL (the default), all available results will be returned.

id

Unique card identifier. May refer to any supported source.

source

Source to which id refers. Can be any one of scryfall, multiverse, mtgo, arena, tcgplayer or cardmarket.

name

A string with a card's name (or part of it).

mode

Search mode. Can be either fuzzy (name may be part of a card's name, allows misspellings and partial words to be provided too) or exact (name has to match exactly, case insensitive).

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 vignette("languages")

Value

A data frame with 1 or more rows and the following columns:

References

https://scryfall.com/docs/api/cards

Examples


# 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")

Retrieve catalog objects

Description

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.

Usage

scry_catalog(name)

Arguments

name

A string with the name of the catalog to return. Can be one of:

  • card-names: Returns all nontoken English card names in Scryfall's database. Values are updated as soon as a new card is entered for spoiler seasons.

  • artist-names: Returns all canonical artist names in Scryfall's database. This catalog won't include duplicate, misspelled, or funny names for artists. Values are updated as soon as a new card is entered for spoiler seasons.

  • word-bank: Returns all English words, of length 2 or more, that could appear in a card name. Values are drawn from cards currently in Scryfall's database. Values are updated as soon as a new card is entered for spoiler seasons.

  • creature-types: Returns all creature types in Scryfall's database. Values are updated as soon as a new card is entered for spoiler seasons.

  • planeswalker-types: Returns all Planeswalker types in Scryfall's database. Values are updated as soon as a new card is entered for spoiler seasons.

  • land-types: Returns all Land types in Scryfall's database. Values are updated as soon as a new card is entered for spoiler seasons.

  • artifact-types: Returns all artifact types in Scryfall's database. Values are updated as soon as a new card is entered for spoiler seasons.

  • enchantment-types: Returns all enchantment types in Scryfall's database. Values are updated as soon as a new card is entered for spoiler seasons.

  • spell-types: Returns all spell types in Scryfall's database. Values are updated as soon as a new card is entered for spoiler seasons.

  • powers: Returns all possible values for a creature or vehicle's power in Scryfall's database. Values are updated as soon as a new card is entered for spoiler seasons.

  • toughnesses: Returns all possible values for a creature or vehicle's toughness in Scryfall's database. Values are updated as soon as a new card is entered for spoiler seasons.

  • loyalties: Returns all possible values for a Planeswalker's loyalty in Scryfall's database. Values are updated as soon as a new card is entered for spoiler seasons.

  • watermarks: Returns all card watermarks in Scryfall's database. Values are updated as soon as a new card is entered for spoiler seasons.

  • keyword-abilities: Returns all keyword abilities in Scryfall's database. Values are updated as soon as a new card is entered for spoiler seasons.

  • keyword-actions: Returns all keyword actions in Scryfall's database. Values are updated as soon as a new card is entered for spoiler seasons.

  • ability-words: Returns all ability words in Scryfall's database. Values are updated as soon as a new card is entered for spoiler seasons.

Value

A string vector.

References

https://scryfall.com/docs/api/catalogs

Examples


# Get information from a catalog
scry_catalog("keyword-actions")

Retrieve information about rulings

Description

Oracle rulings are Wizards of the Coast's set release notes or Scryfall's notes for a particular card.

Usage

scry_ruling(id, source = "scryfall")

scry_ruling_number(number, set)

Arguments

id

Unique card indentifier. May refer to any supported source.

source

Source to which id refers. Can be any one of scryfall, multiverse, mtgo, or arena.

number

The card's collector number for a set.

set

The three to five-letter set code.

Details

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

Value

A data frame with 1 or more rows and the following columns:

References

https://scryfall.com/docs/api/rulings

Examples


# Get rulings for a card
scry_ruling("913dd06f-ed2f-4128-9c9d-9cd0d8a55425")

Retrieve information about sets

Description

A Set represents a group of related Magic cards. All cards on Scryfall belong to exactly one set.

Usage

scry_sets()

scry_set(id, source = "code")

Arguments

id

Unique set indentifier. May refer to any supported source.

source

Source to which id refers. Can be any one of code (the regular three to five-letter set code), scryfall or tcgplayer. See details.

Details

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.

Value

A data frame with 1 or more rows and the following columns:

References

https://scryfall.com/docs/api/sets

Examples


# Get all sets
scry_sets()

# Get set using an ID
scry_set("vow")

Retrieve information about symbols

Description

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

Usage

scry_symbols()

Value

A data frame with 1 row and the following columns:

References

https://scryfall.com/docs/api/card-symbols

Examples


# Get information about symbols
scry_symbols()