scryfall

package module
v0.9.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Apr 8, 2025 License: MIT Imports: 12 Imported by: 19

README

go-scryfall

Go PkgGoDev Coverage Status Go Report Card

go-scryfall

go-scryfall is a Golang client library for accessing the Scryfall API.

The Scryfall logo is copyrighted by Scryfall, LLC. go-scryfall is not created by, affiliated with, or supported by Scryfall.

go-scryfall art was provided by @jouste the fierce drawbarian!

Example

package main

import (
	"context"
	"log"

	scryfall "github.com/BlueMonday/go-scryfall"
)

func main() {
	ctx := context.Background()
	client, err := scryfall.NewClient()
	if err != nil {
		log.Fatal(err)
	}

	sco := scryfall.SearchCardsOptions{
		Unique:        scryfall.UniqueModePrints,
		Order:         scryfall.OrderSet,
		Dir:           scryfall.DirDesc,
		IncludeExtras: true,
	}
	result, err := client.SearchCards(ctx, "storm cro", sco)
	if err != nil {
		log.Fatal(err)
	}

	log.Printf("%s", result.Cards[0].Colors)
}

Rate Limiting

go-scryfall will rate limit requests to Scryfall's API. The default limit is 10 requests per second as recommended in the REST API documentation.

To disable rate limiting use the WithLimiter option with a nil limiter when constructing the client.

package main

import (
	"log"

	scryfall "github.com/BlueMonday/go-scryfall"
)

func main() {
	client, err := scryfall.NewClient(scryfall.WithLimiter(nil))
	if err != nil {
		log.Fatal(err)
	}
}

Documentation

Index

Examples

Constants

View Source 
const (
	Version = "0.9.1"
)

Variables

View Source 
var ErrMultipleSecrets = errors.New("multiple secrets configured")

ErrMultipleSecrets is returned if both the grant and client secret are set when creating a new Scryfall client.

Functions

This section is empty.

Types

type Account 

type Account struct {
	ID           string `json:"id"`
	Username     string `json:"username"`
	DisplayName  string `json:"display_name"`
	Twitter      string `json:"twitter"`
	FullFeatured bool   `json:"full_featured"`
	Verified     bool   `json:"verified"`
}

Account represents a Scryfall account.

type Application 

type Application struct {
	ClientID     string `json:"client_id"`
	Name         string `json:"name"`
	HomepageURI  string `json:"homepage_uri"`
	ContactURI   string `json:"contact_uri"`
	ContactEmail string `json:"contact_email"`
}

Application represents a Scryfall application.

type BulkData 

type BulkData struct {
	// ID is a unique ID for this bulk item.
	ID string `json:"id"`

	// Type is a computer-readable string for the kind of bulk item.
	Type string `json:"type"`

	// UpdatedAt is the time when this file was last updated.
	UpdatedAt Timestamp `json:"updated_at"`

	// Name is a human-readable name for this file.
	Name string `json:"name"`

	// URI is a link to this bulk object on Scryfall's API.
	URI string `json:"uri"`

	// Description is a human-readable name for this file.
	Description string `json:"description"`

	// CompressedSize is the compressed size of this file in integer bytes.
	CompressedSize int `json:"compressed_size"`

	// DownloadURI is the URL that hosts this bulk file.
	DownloadURI string `json:"download_uri"`

	// ContentType is the MIME type of this file.
	ContentType string `json:"content_type"`

	// ContentEncoding is the Content-Encoding encoding that will be used
	// to transmit this file when you download it.
	ContentEncoding string `json:"content_encoding"`
}

BulkData is a Scryfall bulk data item.

type Card 

type Card struct {
	// ArenaID is this card's Arena ID, if any. A large percentage of cards
	// are not available on Arena and do not have this ID.
	ArenaID *int `json:"arena_id,omitempty"`

	// ID is a unique ID for this card in Scryfall's database.
	ID string `json:"id"`

	// Lang is the language code for this printing.
	Lang Lang `json:"lang"`

	// OracleID is 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).
	OracleID string `json:"oracle_id"`

	// MultiverseIDs is this card's multiverse IDs on Gatherer, if any, as
	// an array of integers. Note that Scryfall includes many promo cards,
	// tokens, and other esoteric objects that do not have these identifiers.
	MultiverseIDs []int `json:"multiverse_ids"`

	// MTGOID is 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.
	MTGOID *int `json:"mtgo_id,omitempty"`

	// MTGOFoilID is this card's foil 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.
	MTGOFoilID *int `json:"mtgo_foil_id,omitempty"`

	// URI is a link to this card object on Scryfall's API.
	URI string `json:"uri"`

	// ScryfallURI is a link to this card's permapage on Scryfall's website.
	ScryfallURI string `json:"scryfall_uri"`

	// TCGPlayerID is this card's ID on TCGplayer's API, also known as the productId.
	TCGPlayerID *int `json:"tcgplayer_id,omitempty"`

	// TCGPlayerEtchedID is this card's ID on TCGplayer's API, for its etched version if that version is a separate product.
	TCGPlayerEtchedID *int `json:"tcgplayer_etched_id,omitempty"`

	// CardMarketID is this card's ID on Cardmarket's API, also known as the idProduct.
	CardMarketID *int `json:"Integer,omitempty"`

	// PrintsSearchURI is a link to where you can begin paginating all
	// re/prints for this card on Scryfall's API.
	PrintsSearchURI string `json:"prints_search_uri"`

	// RulingsURI is a link to this card's rulings on Scryfall's API.
	RulingsURI string `json:"rulings_uri"`

	// Name is the name of this card. If this card has multiple faces, this
	// field will contain both names separated by ␣//␣.
	Name string `json:"name"`

	// PrintedName is the printed name of this card.
	// This will only be set if the card is not in English.
	// If this card has multiple faces, this field will not be set.
	PrintedName *string `json:"printed_name"`

	// Layout is a computer-readable designation for this card's
	// layout. See the layout article.
	Layout Layout `json:"layout"`

	// CMC is the card's converted mana cost. Note that some funny cards
	// have fractional mana costs.
	CMC float64 `json:"cmc"`

	// TypeLine is the type line of this card.
	TypeLine string `json:"type_line"`

	// PrintedTypeLine is the type line of this card, as writted on the card.
	// This will only be set if the card is not in English.
	PrintedTypeLine *string `json:"printed_type_line"`

	// OracleText is the Oracle text for this card, if any.
	OracleText string `json:"oracle_text"`

	// PrintedText is the printed text for this card, if any.
	// This will only be set if the card is not in English.
	PrintedText *string `json:"printed_text"`

	// ManaCost is 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.
	ManaCost string `json:"mana_cost"`

	// Power is this card's power, if any. Note that some cards have powers
	// that are not numeric, such as *.
	Power *string `json:"power"`

	// Toughness is this card's toughness, if any. Note that some cards
	// have toughnesses that are not numeric, such as *.
	Toughness *string `json:"toughness"`

	// Loyalty is this loyalty if any. Note that some cards have loyalties
	// that are not numeric, such as X.
	Loyalty *string `json:"loyalty"`

	// Defense is the face's defense, if any.
	Defense *string `json:"defense"`

	// LifeModifier is this card's life modifier, if it is Vanguard
	// card. This value will contain a delta, such as +2.
	LifeModifier *string `json:"life_modifier"`

	// HandModifier is this card's hand modifier, if it is Vanguard
	// card. This value will contain a delta, such as -1.
	HandModifier *string `json:"hand_modifier"`

	// Colors is this card's colors.
	Colors []Color `json:"colors"`

	// ColorIndicator is the colors in this card's color indicator, if
	// any. A nil value for this field indicates the card does not have one.
	ColorIndicator []Color `json:"color_indicator"`

	// ColorIdentity is this card's color identity.
	ColorIdentity []Color `json:"color_identity"`

	// AllParts is a list of closely related cards, if any.
	AllParts []RelatedCard `json:"all_parts"`

	// CardFaces is An array of card Face objects, if this card is
	// multifaced.
	CardFaces []CardFace `json:"card_faces"`

	// Legalities is an object describing the legality of this card.
	Legalities Legalities `json:"legalities"`

	// Reserved is true if this card is on the Reserved List.
	Reserved bool `json:"reserved"`

	// Foil is true if this printing exists in a foil version.
	//
	// Deprecated: switch to finishes.
	// https://scryfall.com/blog/upcoming-api-changes-for-etched-foils-and-glossy-cards-223
	Foil bool `json:"foil"`

	// NonFoil is true if this printing exists in a nonfoil version.
	//
	// Deprecated: switch to finishes.
	// https://scryfall.com/blog/upcoming-api-changes-for-etched-foils-and-glossy-cards-223
	NonFoil bool `json:"nonfoil"`

	// Oversized is true if this card is oversized.
	Oversized bool `json:"oversized"`

	// Promo is true if this card is a promotional print.
	Promo bool `json:"promo"`

	// EDHRECRank is this card's overall rank/popularity on EDHREC. Not all
	// cards are ranked.
	EDHRECRank *int `json:"edhrec_rank"`

	// Set is this card's set code.
	Set string `json:"set"`

	// SetName is this card's full set name.
	SetName string `json:"set_name"`

	// CollectorNumber is this card's collector number. Note that collector
	// numbers can contain non-numeric characters, such as letters or ★.
	CollectorNumber string `json:"collector_number"`

	// SetURI is a link to this card's set on Scryfall's API.
	SetURI string `json:"set_uri"`

	// SetSearchURI is a link to where you can begin paginating this card's
	// set on the Scryfall API.
	SetSearchURI string `json:"set_search_uri"`

	// ScryfallSetURI is a link to this card's set on Scryfall's website.
	ScryfallSetURI string `json:"scryfall_set_uri"`

	// ImageURIs is an object listing available imagery for this card.
	ImageURIs *ImageURIs `json:"image_uris"`

	// Prices contains daily price information for this card, including
	// usd, usd_foil, eur, and tix prices.
	Prices Prices `json:"prices"`

	// HighresImage is true if this card's imagery is high resolution.
	HighresImage bool `json:"highres_image"`

	// Reprint is true if this card is a reprint.
	Reprint bool `json:"reprint"`

	// Digital is true if this is a digital card on Magic Online.
	Digital bool `json:"digital"`

	// Rarity is this card's rarity. One of common, uncommon, rare, or
	// mythic.
	Rarity string `json:"rarity"`

	// FlavorText is the flavor text, if any.
	FlavorText *string `json:"flavor_text"`

	// Artist is the name of the illustrator of this card. Newly spoiled
	// cards may not have this field yet.
	Artist *string `json:"artist"`

	// IllustrationID is a unique identifier for the card artwork that
	// remains consistent across reprints. Newly spoiled cards may not have
	// this field yet.
	IllustrationID *string `json:"illustration_id"`

	// Frame is this card's frame layout.
	Frame Frame `json:"frame"`

	// FrameEffects is this card's frame effects, if any.
	FrameEffects []FrameEffect `json:"frame_effects"`

	// FullArt is true if this card's artwork is larger than normal.
	FullArt bool `json:"full_art"`

	// Watermark is this card's watermark, if any.
	Watermark *string `json:"watermark"`

	// Preview contains information about who previewed/spoiled this card.
	Preview Preview `json:"preview"`

	// PromoTypes is an array of promo types for this card, if any.
	PromoTypes []string `json:"promo_types,omitempty"`

	// BorderColor is this card's border color: black, borderless, gold,
	// silver, or white.
	BorderColor string `json:"border_color"`

	// StorySpotlightNumber is this card's story spotlight number, if any.
	StorySpotlightNumber *int `json:"story_spotlight_number"`

	// StorySpotlightURI is a URL to this cards's story article, if any.
	StorySpotlightURI *string `json:"story_spotlight_uri"`

	// RelatedURIs contains links related to a card.
	RelatedURIs RelatedURIs `json:"related_uris"`

	// ReleasedAt is the date this card was first released.
	ReleasedAt Date `json:"released_at"`

	// PurchaseURIs contains links to the card on online card stores.
	PurchaseURIs PurchaseURIs `json:"purchase_uris"`

	// Keywords is an array of keywords that this card uses, such as 'Flying' and 'Cumulative upkeep'.
	Keywords []string `json:"keywords"`

	// ProducedMana are colors of mana that this card could produce.
	ProducedMana []Color `json:"produced_mana"`

	// Booster is whether this card is found in boosters.
	Booster bool `json:"booster"`

	// Finishes is an array of computer-readable flags that indicate if this card can come in foil, nonfoil, etched, or glossy finishes.
	Finishes []Finish `json:"finishes"`

	// ImageStatus is a computer-readable indicator for the state of this card's image.
	ImageStatus *ImageStatus `json:"image_status"`

	// AttractionLights are the Unfinity attractions lights on this card, if any.
	AttractionLights []int `json:"attraction_lights,omitempty"`

	// ContentWarning is whether you should consider avoiding use of this
	// print downstream.
	ContentWarning *bool `json:"content_warning,omitempty"`

	// FlavorName is the just-for-fun name printed on the card (such as for
	// Godzilla series cards).
	FlavorName *string `json:"flavor_name,omitempty"`
}

Card represents individual Magic: The Gathering cards that players could obtain and add to their collection (with a few minor exceptions).

type CardFace 

type CardFace struct {
	// Name is the name of this particular face.
	Name string `json:"name"`

	// PrintedName is the printed name of this particular face.
	// This will only be set if the card is not in English.
	PrintedName *string `json:"printed_name"`

	// TypeLine is the type line of this particular face.
	TypeLine string `json:"type_line"`

	// PrintedTypeLine is the printed type line of this particular face.
	// This will only be set if the card is not in English.
	PrintedTypeLine *string `json:"printed_type_line"`

	// OracleText is the Oracle text for this face, if any.
	OracleText *string `json:"oracle_text"`

	// PrintedText is the printed text for this face, if any.
	// This will only be set if the card is not in English.
	PrintedText *string `json:"printed_text"`

	// ManaCost is 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.
	ManaCost string `json:"mana_cost"`

	// Colors is this face's colors.
	Colors []Color `json:"colors"`

	// ColorIndicator is the colors in this face's color indicator, if any.
	ColorIndicator []Color `json:"color_indicator"`

	// Power is this face's power, if any. Note that some cards have powers
	// that are not numeric, such as *.
	Power *string `json:"power"`

	// Toughness is this face's toughness, if any.
	Toughness *string `json:"toughness"`

	// Layout is the layout of this card face, if the card is reversible.
	Layout *Layout `json:"layout"`

	// Loyalty is this face's loyalty, if any.
	Loyalty *string `json:"loyalty"`

	// OracleID is the Oracle ID of this particular face, if the card is
	// reversible.
	OracleID *string `json:"oracle_id,omitempty"`

	// Defense is the face's defense, if the game defines colors for the
	// individual face of this card.
	Defense *string `json:"defense"`

	// FlavorText is the flavor text printed on this face, if any.
	FlavorText *string `json:"flavor_text"`

	// IllustrationID is a unique identifier for the card face artwork that
	// remains consistent across reprints. Newly spoiled cards may not have
	// this field yet.
	IllustrationID *string `json:"illustration_id"`

	// ImageURIs is an object 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 property will be part of the parent object instead.
	ImageURIs ImageURIs `json:"image_uris"`
}

CardFace is a face of a multifaced card.

type CardIdentifier 

type CardIdentifier struct {
	// Name identifies a card with the specified Scryfall ID.
	ID string `json:"id,omitempty"`

	// MTGOID identifies a card with the specified MTGO ID or MTGO foil ID.
	MTGOID int `json:"mtgo_id,omitempty"`

	// MultiverseID identifies a card with the specified value among its
	// multiverse IDs.
	MultiverseID int `json:"multiverse_id,omitempty"`

	// Name identifies the newest edition of a card with the specified
	// name.
	Name string `json:"name,omitempty"`

	// Set identifies a card with the specified set.
	Set string `json:"set,omitempty"`

	// CollectorNumber identifies a card with the specified collector
	// number.
	CollectorNumber string `json:"collector_number,omitempty"`
}

CardIdentifier identifies a card.

The following combinations are valid identifier schemas:

  • ID
  • MTGOID
  • MultiverseID
  • Name
  • Name and Set
  • Set and CollectorNumber

type CardListResponse 

type CardListResponse struct {
	// Cards is a list of the requested cards.
	Cards []Card `json:"data"`

	// HasMore is true if this List is paginated and there is a page beyond
	// the current page.
	HasMore bool `json:"has_more"`

	// NextPage contains a full API URI to next page if there is a page
	// beyond the current page.
	NextPage *string `json:"next_page"`

	// TotalCards contains the total number of cards found across all
	// pages.
	TotalCards int `json:"total_cards"`

	// Warnings is a list of human-readable warnings issued when generating
	// this list, as strings. Warnings are non-fatal issues that the API
	// discovered with your input. In general, they indicate that the List
	// will not contain the all of the information you requested. You should
	// fix the warnings and re-submit your request.
	Warnings []string `json:"warnings"`
}

CardListResponse represents a requested sequence of card objects. CardListResponse objects may be paginated, and also include information about issues raised when generating the list.

type CardSymbol 

type CardSymbol struct {
	// Object is the content type for this object, always card_symbol.
	Object string `json:"object"`

	// Symbol is the plaintext symbol. Often surrounded with curly braces
	// {}. Note that not all symbols are ASCII text (for example, {∞}).
	Symbol string `json:"symbol"`

	// LooseVariant is an alternate version of this symbol, if it is
	// possible to write it without curly braces.
	LooseVariant *string `json:"loose_variant"`

	// English is an English snippet that describes this
	// symbol. Appropriate for use in alt text or other accessible
	// communication formats.
	English string `json:"english"`

	// Transposable is true if 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. Note that the Scryfall API never writes symbols backwards in
	// other responses. This field is provided for informational purposes.
	Transposable bool `json:"transposable"`

	// RepresentsMana is true if this is a mana symbol.
	RepresentsMana bool `json:"represents_mana"`

	// CMC is a decimal number representing this symbol's converted mana
	// cost. Note that mana symbols from funny sets can have fractional
	// converted mana costs.
	//
	// Deprecated: Use ManaValue instead.
	CMC float64 `json:"cmc"`

	// ManaValue is a decimal number representing this symbol’s mana value
	// (also knowns as the converted mana cost). Note that mana symbols
	// from funny sets can have fractional mana values.
	ManaValue *float64 `json:"mana_value"`

	// AppearsInManaCosts is true if this symbol appears in a mana cost on
	// any Magic card. For example {20} has this field set to false because
	// {20} only appears in Oracle text, not mana costs.
	AppearsInManaCosts bool `json:"appears_in_mana_costs"`

	// Funny is true if this symbol is only used on funny cards or Un-cards.
	Funny bool `json:"funny"`

	// Color is an array of colors that this symbol represents.
	Colors []Color `json:"colors"`

	// Hybrid is true if the symbol is a hybrid mana symbol. Note that
	// monocolor Phyrexian symbols aren’t considered hybrid.
	Hybrid bool `json:"hybrid"`

	// Phyrexian is true if the symbol is a Phyrexian mana symbol, i.e. it
	// can be paid with 2 life.
	Phyrexian bool `json:"phyrexian"`

	// GathererAlternates is an array 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.
	GathererAlternates []string `json:"gatherer_alternates"`

	// SVGURI is a URI to an SVG image of this symbol on Scryfall’s CDNs.
	SVGURI *string `json:"svg_uri"`
}

CardSymbol represents an illustrated symbol that 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 the colors and costs overview: https://scryfall.com/docs/api/colors.

type Catalog 

type Catalog struct {
	// URI is a link to the current catalog on Scryfall's API.
	URI string `json:"uri"`

	// TotalValues is the number of items in the data array.
	TotalValues int `json:"total_values"`

	// Data is an array of datapoints, as strings.
	Data []string `json:"data"`
}

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

type Client 

type Client struct {
	// contains filtered or unexported fields
}

Client is a Scryfall API client.

func NewClient 

func NewClient(options ...ClientOption) (*Client, error)

NewClient returns a new Scryfall API client.

func (*Client) AutocompleteCard 

func (c *Client) AutocompleteCard(ctx context.Context, s string) ([]string, error)

AutocompleteCard returns a slice containing up to 20 full English card names that could be autocompletions of the given string parameter.

func (*Client) GetAbilityWordsCatalog added in v0.8.0 

func (c *Client) GetAbilityWordsCatalog(ctx context.Context) (Catalog, error)

GetAbilityWordsCatalog returns a Catalog of all ability words in Scryfall's database. Values are updated as soon as a new card is entered for spoiler seasons.

func (*Client) GetAccount 

func (c *Client) GetAccount(ctx context.Context) (Account, error)

GetAccount returns an object describing the currently authenticated Scryfall account.

Requires an OAuth grant with OAuthScopeRead or higher.

func (*Client) GetApplication 

func (c *Client) GetApplication(ctx context.Context) (Application, error)

GetApplication returns an object describing the currently authenticated application.

Requires application authentication.

func (*Client) GetArtifactTypesCatalog 

func (c *Client) GetArtifactTypesCatalog(ctx context.Context) (Catalog, error)

GetArtifactTypesCatalog returns a Catalog of all artifact types in Scryfall's database. Values are updated as soon as a new card is entered for spoiler seasons.

func (*Client) GetArtistNamesCatalog 

func (c *Client) GetArtistNamesCatalog(ctx context.Context) (Catalog, error)

GetArtistNamesCatalog returns a list of 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.

func (*Client) GetBattleTypesCatalog added in v0.8.0 

func (c *Client) GetBattleTypesCatalog(ctx context.Context) (Catalog, error)

GetBattleTypesCatalog returns a Catalog of all battle types in Scryfall's database. Values are updated as soon as a new card is entered for spoiler seasons.

func (*Client) GetBulkDataByID added in v0.7.0 

func (c *Client) GetBulkDataByID(ctx context.Context, id string) (BulkData, error)

GetBulkDataByID gets a bulk data item by ID.

func (*Client) GetBulkDataByType added in v0.7.0 

func (c *Client) GetBulkDataByType(ctx context.Context, typ string) (BulkData, error)

GetBulkDataByType gets a bulk data item by type.

func (*Client) GetCard 

func (c *Client) GetCard(ctx context.Context, id string) (Card, error)

GetCard returns a single card with the given Scryfall ID.

func (*Client) GetCardByArenaID 

func (c *Client) GetCardByArenaID(ctx context.Context, arenaID int) (Card, error)

GetCardByArenaID returns a single card with the given Magic: The Gathering Arena ID.

func (*Client) GetCardByMTGOID 

func (c *Client) GetCardByMTGOID(ctx context.Context, mtgoID int) (Card, error)

GetCardByMTGOID returns a single card with the given MTGO ID (also known as the Catalog ID). The ID can either be the card's MTGO ID or its MTGO foil ID.

func (*Client) GetCardByMultiverseID 

func (c *Client) GetCardByMultiverseID(ctx context.Context, multiverseID int) (Card, error)

GetCardByMultiverseID returns a single card with the given Multiverse ID. If the card has multiple multiverse IDs, GetCardByMultiverseID can find either of them.

func (*Client) GetCardByName 

func (c *Client) GetCardByName(ctx context.Context, name string, exact bool, opts GetCardByNameOptions) (Card, error)

GetCardByName returns a Card based on a name search string. This method is designed for building chat bots, forum bots, and other services that need card details quickly.

If the exact parameter is set to true, a card with that exact name is returned. Otherwise, an error is returned because no card matches.

If the exact parameter is set to false 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 bel 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, you will receive an error describing the problem: either more than 1 one card matched your search, or zero cards matched.

For both exact and fuzzy, 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

func (*Client) GetCardBySetCodeAndCollectorNumber 

func (c *Client) GetCardBySetCodeAndCollectorNumber(ctx context.Context, setCode string, collectorNumber string) (Card, error)

GetCardBySetCodeAndCollectorNumber returns a single card with the given set code and collector number.

func (*Client) GetCardBySetCodeAndCollectorNumberInLang 

func (c *Client) GetCardBySetCodeAndCollectorNumberInLang(ctx context.Context, setCode string, collectorNumber string, lang Lang) (Card, error)

GetCardBySetCodeAndCollectorNumberInLang returns a single card with the given set code and collector number in the provided language.

func (*Client) GetCardByTCGPlayerID 

func (c *Client) GetCardByTCGPlayerID(ctx context.Context, tcgPlayerID int) (Card, error)

GetCardByTCGPlayerID returns a single card with the given TCGPlayer ID, also known as the productId on TCGPlayer's API.

func (*Client) GetCardNamesCatalog 

func (c *Client) GetCardNamesCatalog(ctx context.Context) (Catalog, error)

GetCardNamesCatalog returns a list of all nontoken English card names in Scryfall's database. Values are updated as soon as a new card is entered for spoiler seasons.

func (*Client) GetCardTypesCatalog added in v0.8.0 

func (c *Client) GetCardTypesCatalog(ctx context.Context) (Catalog, error)

GetCardTypesCatalog returns a Catalog of all Magic card types in Scryfall's database. Values are updated as soon as a new card is entered for spoiler seasons.

func (*Client) GetCardsByIdentifiers 

func (c *Client) GetCardsByIdentifiers(ctx context.Context, identifiers []CardIdentifier) (GetCardsByIdentifiersResponse, error)

GetCardsByIdentifiers accepts a list of card identifiers and returns the collection of requested cards. A maximum of 75 card references may be submitted per request.

func (*Client) GetCreatureTypesCatalog 

func (c *Client) GetCreatureTypesCatalog(ctx context.Context) (Catalog, error)

GetCreatureTypesCatalog returns a Catalog of all creature types in Scryfall's database. Values are updated as soon as a new card is entered for spoiler seasons.

func (*Client) GetEnchantmentTypesCatalog 

func (c *Client) GetEnchantmentTypesCatalog(ctx context.Context) (Catalog, error)

GetEnchantmentTypesCatalog returns a Catalog of all enchantment types in Scryfall's database. Values are updated as soon as a new card is entered for spoiler seasons.

func (*Client) GetFlavorWordsCatalog added in v0.8.0 

func (c *Client) GetFlavorWordsCatalog(ctx context.Context) (Catalog, error)

GetFlavorWordsCatalog returns a Catalog of all flavor words in Scryfall's database. Values are updated as soon as a new card is entered for spoiler seasons.

func (*Client) GetKeywordAbilitiesCatalog added in v0.8.0 

func (c *Client) GetKeywordAbilitiesCatalog(ctx context.Context) (Catalog, error)

GetKeywordAbilitiesCatalog returns a Catalog of all keyword abilities in Scryfall's database. Values are updated as soon as a new card is entered for spoiler seasons.

func (*Client) GetKeywordActionsCatalog added in v0.8.0 

func (c *Client) GetKeywordActionsCatalog(ctx context.Context) (Catalog, error)

GetKeywordActionsCatalog returns a Catalog of all keyword actions in Scryfall's database. Values are updated as soon as a new card is entered for spoiler seasons.

func (*Client) GetLandTypesCatalog 

func (c *Client) GetLandTypesCatalog(ctx context.Context) (Catalog, error)

GetLandTypesCatalog returns a Catalog of all Land types in Scryfall's database. Values are updated as soon as a new card is entered for spoiler seasons.

func (*Client) GetLoyaltiesCatalog 

func (c *Client) GetLoyaltiesCatalog(ctx context.Context) (Catalog, error)

GetLoyaltiesCatalog returns a Catalog of 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.

func (*Client) GetPlaneswalkerTypesCatalog 

func (c *Client) GetPlaneswalkerTypesCatalog(ctx context.Context) (Catalog, error)

GetPlaneswalkerTypesCatalog returns a Catalog of all Planeswalker types in Scryfall's database. Values are updated as soon as a new card is entered for spoiler seasons.

func (*Client) GetPowersCatalog 

func (c *Client) GetPowersCatalog(ctx context.Context) (Catalog, error)

GetPowersCatalog returns a Catalog of 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.

func (*Client) GetRandomCard 

func (c *Client) GetRandomCard(ctx context.Context) (Card, error)

GetRandomCard returns a random card.

func (*Client) GetRulings 

func (c *Client) GetRulings(ctx context.Context, id string) ([]Ruling, error)

GetRulings returns the rulings for a card with the given Scryfall ID.

func (*Client) GetRulingsByArenaID 

func (c *Client) GetRulingsByArenaID(ctx context.Context, arenaID int) ([]Ruling, error)

GetRulingsByArenaID returns rulings for a card with the given Magic: The Gathering Arena ID.

func (*Client) GetRulingsByMTGOID 

func (c *Client) GetRulingsByMTGOID(ctx context.Context, mtgoID int) ([]Ruling, error)

GetRulingsByMTGOID returns rulings for a card with the given MTGO ID (also known as the Catalog ID). The ID can either be the card's MTGO ID or its MTGO foil ID.

func (*Client) GetRulingsByMultiverseID 

func (c *Client) GetRulingsByMultiverseID(ctx context.Context, multiverseID int) ([]Ruling, error)

GetRulingsByMultiverseID returns the rulings for a card with the given multiverse ID. If the card has multiple multiverse IDs, GetRulingsByMultiverseID can find either of them.

func (*Client) GetRulingsBySetCodeAndCollectorNumber 

func (c *Client) GetRulingsBySetCodeAndCollectorNumber(ctx context.Context, setCode string, collectorNumber int) ([]Ruling, error)

GetRulingsBySetCodeAndCollectorNumber returns a list of rulings for the card with the given set code and collector number.

func (*Client) GetSet 

func (c *Client) GetSet(ctx context.Context, code string) (Set, error)

GetSet returns a set with the given set code.

func (*Client) GetSpellTypesCatalog 

func (c *Client) GetSpellTypesCatalog(ctx context.Context) (Catalog, error)

GetSpellTypesCatalog returns a Catalog of all spell types in Scryfall's database. Values are updated as soon as a new card is entered for spoiler seasons.

func (*Client) GetSuperTypesCatalog added in v0.8.0 

func (c *Client) GetSuperTypesCatalog(ctx context.Context) (Catalog, error)

GetSuperTypesCatalog returns a Catalog of all Magic card supertypes in Scryfall's database. Values are updated as soon as a new card is entered for spoiler seasons.

func (*Client) GetToughnessesCatalog 

func (c *Client) GetToughnessesCatalog(ctx context.Context) (Catalog, error)

GetToughnessesCatalog returns a Catalog of 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.

func (*Client) GetWatermarksCatalog 

func (c *Client) GetWatermarksCatalog(ctx context.Context) (Catalog, error)

GetWatermarksCatalog returns a Catalog of all card watermarks in Scryfall's database. Values are updated as soon as a new card is entered for spoiler seasons.

func (*Client) GetWordBankCatalog 

func (c *Client) GetWordBankCatalog(ctx context.Context) (Catalog, error)

GetWordBankCatalog returns a Catalog of 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.

func (*Client) ListBulkData 

func (c *Client) ListBulkData(ctx context.Context) ([]BulkData, error)

ListBulkData returns a list of all bulk data items on Scryfall.

func (*Client) ListCardSymbols 

func (c *Client) ListCardSymbols(ctx context.Context) ([]CardSymbol, error)

ListCardSymbols returns a list of all card symbols.

func (*Client) ListSets 

func (c *Client) ListSets(ctx context.Context) ([]Set, error)

ListSets lists all of the sets on Scryfall.

func (*Client) OAuthConvert 

func (c *Client) OAuthConvert(ctx context.Context, code string) (OAuthGrant, error)

OAuthConvert exchanges an OAuth code for a full OAuth grant object. The returned object will contain the GrantSecret that you should use for future requests inside the Authorization header for that account.

Each code expires in 5 minutes, and can only be used once. Repeated requests sent to this method with the same code will fail.

Ensure that you save both the GrantID and the GrantSecret you receive, as well as recording any other data in the object that your application needs to run, such as the information inside the account object.

Requires application authentication.

func (*Client) OAuthDowngrade 

func (c *Client) OAuthDowngrade(ctx context.Context, grantID string) (OAuthGrant, error)

OAuthDowngrade downgrades the scope of the OAuth grant identified by the submitted grantID.

If the scope of the grant is OAuthScopeReadWrite, it will change to OAuthScopeRead. If the scope was already OAuthScopeRead, the grant object is returned unchanged (OAuthScopeRead is the lowest permission scope).

Downgraded grants cannot be upgraded later, this change is permanent.

This method is designed to allow your application to proactively relinquish rights to a user's account if you no longer need OAuthScopeReadWrite scope.

Requires application authentication.

func (*Client) OAuthRevoke 

func (c *Client) OAuthRevoke(ctx context.Context, grantID string) (OAuthRevokeResponse, error)

OAuthRevoke revokes the OAuth grant identified by the provided grantID. The entire grant is immediately invalidated, no further requests may be made using its grant ID or grant secret. A minimal revoked version of the grant is returned as confirmation.

The user must perform the full OAuth flow to establish a new grant with your application if they so desire.

This method is designed to allow your application to proactively disconnect from this user's Scryfall account from your side.

Requires application authentication.

func (*Client) ParseManaCost 

func (c *Client) ParseManaCost(ctx context.Context, cost string) (ManaCost, error)

ParseManaCost parses a string mana cost 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}).

func (*Client) SearchCards 

func (c *Client) SearchCards(ctx context.Context, query string, opts SearchCardsOptions) (CardListResponse, error)

SearchCards returns a list cards found using a full text search. The query parameter is the full text search query. See the search reference docs for more information on the full text search query format: https://scryfall.com/docs/reference.

Example 
package main

import (
	"context"
	"fmt"

	scryfall "github.com/BlueMonday/go-scryfall"
)

func main() {
	ctx := context.Background()
	client, err := scryfall.NewClient()
	if err != nil {
		fmt.Println(err.Error())
	}

	so := scryfall.SearchCardsOptions{
		Unique:        scryfall.UniqueModePrints,
		Order:         scryfall.OrderSet,
		Dir:           scryfall.DirDesc,
		IncludeExtras: true,
	}
	result, err := client.SearchCards(ctx, "storm cro", so)
	if err != nil {
		fmt.Println(err.Error())
	}

	fmt.Printf("%s\n", result.Cards[0].Colors)
}

Output:

[U]

type ClientOption 

type ClientOption func(*clientOptions)

ClientOption configures the Scryfall API client.

func WithBaseURL 

func WithBaseURL(baseURL string) ClientOption

WithBaseURL returns an option which overrides the base URL.

func WithClientSecret 

func WithClientSecret(clientSecret string) ClientOption

WithClientSecret returns an option which sets the client secret. The client secret will configure the client to perform requests as the application associated with the client secret.

func WithGrantSecret 

func WithGrantSecret(grantSecret string) ClientOption

WithGrantSecret returns an option which sets the grant secret. The grant secret will configure the client to perform requests with the rights of the grant account.

func WithHTTPClient 

func WithHTTPClient(client *http.Client) ClientOption

WithHTTPClient returns an option which overrides the default HTTP client.

func WithLimiter added in v0.2.0 

func WithLimiter(limiter ratelimit.Limiter) ClientOption

WithLimiter returns an option which overrides the default rate limiter. A nil ratelimiter will disable rate limiting.

func WithUserAgent added in v0.6.0 

func WithUserAgent(userAgent string) ClientOption

WithUserAgent returns an option which overrides the default HTTP user agent.

type Color 

type Color string

Color represents a color in Magic: The Gathering. 

const (
	// ColorWhite is the white mana color.
	ColorWhite Color = "W"

	// ColorBlue is the blue mana color.
	ColorBlue Color = "U"

	// ColorBlack is the black mana color.
	ColorBlack Color = "B"

	// ColorRed is the red mana color.
	ColorRed Color = "R"

	// ColorGreen is the green mana color.
	ColorGreen Color = "G"
)

type Component 

type Component string

Component is a field explaining what role a card plays in a relationship. 

const (
	// ComponentToken represents a token related to a card.
	ComponentToken Component = "token"

	// ComponentMeldPart represents one of the parts of a meld.
	ComponentMeldPart Component = "meld_part"

	// ComponentMeldResult represents the result of a meld.
	ComponentMeldResult Component = "meld_result"

	// ComponentComboPiece represents a combo piece related to a card.
	ComponentComboPiece Component = "combo_piece"
)

type Date 

type Date struct {
	time.Time
}

Date is a date returned by the Scryfall API.

func (*Date) MarshalJSON added in v0.5.0 

func (d *Date) MarshalJSON() ([]byte, error)

func (*Date) UnmarshalJSON 

func (d *Date) UnmarshalJSON(b []byte) error

UnmarshalJSON parses a JSON encoded Scryfall date and stores the result.

type Dir 

type Dir string

Dir is a direction used to sort cards. 

const (
	// DirAuto lets Scryfall automatically choose the most intuitive
	// direction to sort.
	DirAuto Dir = "auto"

	// DirAsc sorts cards in ascending order.
	DirAsc Dir = "asc"

	// DirDesc sorts cards in descending order.
	DirDesc Dir = "desc"
)

type Error 

type Error struct {
	Status   int      `json:"status"`
	Code     string   `json:"code"`
	Details  string   `json:"details"`
	Type     *string  `json:"type"`
	Warnings []string `json:"warnings"`
}

Error is a Scryfall API error response.

func (*Error) Error 

func (e *Error) Error() string

type Finish added in v0.2.0 

type Finish string

Finish is a finish a card can come in. 

const (
	// FinishFoil represents a foild card finish.
	FinishFoil Finish = "foil"

	// FinishNonFoil represents a nonfoild card finish.
	FinishNonFoil Finish = "nonfoil"

	// FinishEtched represents a etched card finish.
	FinishEtched Finish = "etched"

	// FinishGlossy represents a glossy card finish.
	FinishGlossy Finish = "glossy"
)

type Frame 

type Frame string

Frame tracks the major edition of the card frame of used for the re/print in question. The frame has gone though several major revisions in Magic's lifetime. 

const (
	// Frame1993 is the original Magic card frame, starting from Limited
	// Edition Alpha.
	Frame1993 Frame = "1993"

	// Frame1997 is the updated classic frame starting from Mirage block.
	Frame1997 Frame = "1997"

	// Frame2003 is the “modern” Magic card frame, introduced in Eighth
	// Edition and Mirrodin block.
	Frame2003 Frame = "2003"

	// Frame2015 is the holofoil-stamp Magic card frame, introduced in
	// Magic 2015.
	Frame2015 Frame = "2015"

	// FrameFuture is the frame used on cards from the future.
	FrameFuture Frame = "future"
)

type FrameEffect 

type FrameEffect string

FrameEffect tracks additional frame artwork applied over a particular frame. For example, there are both 2003 and 2015-frame cards with the Nyx-touched effect. 

const (
	// FrameEffectLegendary is the legendary crown introduced in Dominaria.
	FrameEffectLegendary FrameEffect = "legendary"

	// FrameEffectMiracle is the miracle frame effect.
	FrameEffectMiracle FrameEffect = "miracle"

	// FrameEffectNyxTouched is the Nyx-touched frame effect.
	FrameEffectNyxTouched FrameEffect = "nyxtouched"

	// FrameEffectDraft is the draft-matters frame effect.
	FrameEffectDraft FrameEffect = "draft"

	// FrameEffectDevoid is the Devoid frame effect.
	FrameEffectDevoid FrameEffect = "devoid"

	// FrameEffectTombstone is the Odyssey tombstone mark frame effect.
	FrameEffectTombstone FrameEffect = "tombstone"

	// FrameEffectColorShifted is the colorshifted frame effect.
	FrameEffectColorShifted FrameEffect = "colorshifted"

	// FrameEffectInverted is the FNM-style inverted frame effect.
	FrameEffectInverted FrameEffect = "inverted"

	// FrameEffectSunMoonDFC is the sun and moon transform marks frame
	// effect.
	FrameEffectSunMoonDFC FrameEffect = "sunmoondfc"

	// FrameEffectCompassLandDFC is the compass and land transform marks
	// frame effect.
	FrameEffectCompassLandDFC FrameEffect = "compasslanddfc"

	// FrameEffectOriginPWDFC is the Origins and planeswalker transform
	// marks frame effect.
	FrameEffectOriginPWDFC FrameEffect = "originpwdfc"

	// FrameEffectMoonEldraziDFC is the moon and Eldrazi transform marks
	// frame effect.
	FrameEffectMoonEldraziDFC FrameEffect = "mooneldrazidfc"

	// FrameEffectMoonReverseMoonDFC is the waxing and waning crescent moon
	// transform marks frame effect.
	FrameEffectMoonReverseMoonDFC FrameEffect = "moonreversemoondfc"

	// FrameEffectShowcase is the custom Showcase frame effect.
	FrameEffectShowcase FrameEffect = "showcase"

	// FrameEffectExtendedArt is the extended art frame effect.
	FrameEffectExtendedArt FrameEffect = "extendedart"

	// FrameEffectCompanion is the companion frame effect.
	FrameEffectCompanion FrameEffect = "companion"

	// FrameEffectEtched is the etched foil treatment frame effect.
	FrameEffectEtched FrameEffect = "etched"

	// FrameEffectSnow is the snowy frame effect.
	FrameEffectSnow FrameEffect = "snow"

	// FrameEffectLesson is the lesson frame effect.
	FrameEffectLesson FrameEffect = "lesson"

	// FrameEffectShatteredGlass is the shattered glass frame effect.
	FrameEffectShatteredGlass FrameEffect = "shatteredglass"

	// FrameEffectConvertDFC is the more than meets the eye marks frame
	// effect.
	FrameEffectConvertDFC FrameEffect = "convertdfc"

	// FrameEffectFanDFC is the fan transforming marks frame effect.
	FrameEffectFanDFC FrameEffect = "fandfc"

	// FrameEffectUpsideDownDFC is the upside down transforming marks frame
	// effect.
	FrameEffectUpsideDownDFC FrameEffect = "upsidedowndfc"

	// FrameEffectSpree is the spree asterisk frame effect.
	FrameEffectSpree FrameEffect = "spree"
)

type GetCardByNameOptions 

type GetCardByNameOptions struct {
	// Set limits the search to the specified set.
	Set string `url:"set,omitempty"`
}

GetCardByNameOptions holds the options used to get a card by name.

type GetCardsByIdentifiersRequest 

type GetCardsByIdentifiersRequest struct {
	Identifiers []CardIdentifier `json:"identifiers"`
}

GetCardsByIdentifiersRequest represents a request to get cards which correspond to the provided card identifiers.

type GetCardsByIdentifiersResponse 

type GetCardsByIdentifiersResponse struct {
	// NotFound contains the list of card identifiers which did not
	// correspond to any card.
	NotFound []CardIdentifier `json:"not_found"`

	// Data is the list of cards retrieved using the provided card
	// identifiers. The cards are in the order they were requested, cards that
	// aren't found will throw off the mapping of request identifiers to
	// results, so you should not rely on positional index alone while parsing
	// the data.
	Data []Card `json:"data"`
}

GetCardsByIdentifiersResponse represents the list of cards retrieved using a list of card identifiers.

type ImageStatus added in v0.3.0 

type ImageStatus string

ImageStatus is a computer-readable indicator for the state of this card's image, one of missing, placeholder, lowres, or highres_scan. 

const (
	// ImageStatusMissing represents that the card has no image, or the image is being processed.
	// This value should only be temporary for very new cards.
	ImageStatusMissing ImageStatus = "missing"

	// ImageStatusPlaceholder represents that Scryfall doesn't have an image of this card,
	// but we know it exists and we have uploaded a placeholder in the meantime.
	// This value is most common on localized cards.
	ImageStatusPlaceholer ImageStatus = "placeholder"

	// ImageStatusHighres represents that the card's image is low-quality,
	// either because it was just spoiled or we don't have better photography for it yet.
	ImageStatusLowres ImageStatus = "lowres"

	// ImageStatusHighres represents that the card has a full-resolution scanner image. Crisp and glossy!
	ImageStatusHighres ImageStatus = "highres_scan"
)

type ImageURIs 

type ImageURIs struct {
	// Small is a small full card image. Designed for use as thumbnail or
	// list icon.
	Small string `json:"small"`

	// Normal is a medium-sized full card image.
	Normal string `json:"normal"`

	// Large is a large full card image.
	Large string `json:"large"`

	// PNG is a transparent, rounded full card PNG. This is the best image
	// to use for videos or other high-quality content.
	PNG string `json:"png"`

	// ArtCrop is a rectangular crop of the card's art only. Not guaranteed
	// to be perfect for cards with outlier designs or strange frame
	// arrangements
	ArtCrop string `json:"art_crop"`

	// BorderCrop is a full card image with the rounded corners and the
	// majority of the border cropped off. Designed for dated contexts where
	// rounded images can't be used.
	BorderCrop string `json:"border_crop"`
}

ImageURIs contains links to the different image sizes and crops for a given card.

type Lang 

type Lang string

Lang is an ISO-like language code. 

const (
	// LangEnglish is the English language code.
	LangEnglish Lang = "en"

	// LangSpanish is the Spanish language code.
	LangSpanish Lang = "es"

	// LangFrench is the French language code.
	LangFrench Lang = "fr"

	// LangGerman is the German language code.
	LangGerman Lang = "de"

	// LangItalian is the Italian language code.
	LangItalian Lang = "it"

	// LangPortuguese is the Portuguese language code.
	LangPortuguese Lang = "pt"

	// LangJapanese is the Japanese language code.
	LangJapanese Lang = "ja"

	// LangKorean is the Korean language code.
	LangKorean Lang = "ko"

	// LangRussian is the Russian language code.
	LangRussian Lang = "ru"

	// LangSimplifiedChinese is the simplified Chinese language code.
	LangSimplifiedChinese Lang = "zhs"

	// LangTraditionalChinese is the traditional Chinese language code.
	LangTraditionalChinese Lang = "zht"

	// LangHebrew is the Hebrew language code.
	LangHebrew Lang = "he"

	// LangLatin is the Latin language code.
	LangLatin Lang = "la"

	// LangAncientGreek is the ancient Greek language code.
	LangAncientGreek Lang = "grc"

	// LangArabic is the Arabic language code.
	LangArabic Lang = "ar"

	// LangSanskrit is the Sanskrit language code.
	LangSanskrit Lang = "sa"

	// LangPhyrexian is the Phyrexian language code.
	LangPhyrexian Lang = "ph"
)

type Layout 

type Layout string

Layout categorizes the arrangement of card parts, faces, and other bounded regions on cards. The layout can be used to programmatically determine which other properties on a card you can expect. 

const (
	// LayoutNormal is a standard Magic card layout with one face.
	LayoutNormal Layout = "normal"

	// LayoutSplit is a split-faced card layout.
	LayoutSplit Layout = "split"

	// LayoutFlip is a card layout that inverts vertically with the flip
	// keyword.
	LayoutFlip Layout = "flip"

	// LayoutTransform is a double-sided card layout that transforms.
	LayoutTransform Layout = "transform"

	// LayoutModalDFC is a double-sided card layout that can be played either-side.
	LayoutModalDFC Layout = "modal_dfc"

	// LayoutMeld is a card layout with meld parts printed on the back.
	LayoutMeld Layout = "meld"

	// LayoutLeveler is a level up card layout.
	LayoutLeveler Layout = "leveler"

	// LayoutClass is class-type enchantment cards layout.
	LayoutClass Layout = "class"

	// LayoutCase is a case-type enchantment cards layout.
	LayoutCase Layout = "case"

	// LayoutSaga is saga card layout.
	LayoutSaga Layout = "saga"

	// LayoutAdventure is a card layout with an Adventure spell part.
	LayoutAdventure Layout = "adventure"

	// LayoutMutate is mutate card layout.
	LayoutMutate Layout = "mutate"

	// LayoutPrototype is prototype card layout.
	LayoutPrototype Layout = "prototype"

	// LayoutBattle is a battle-type card layout.
	LayoutBattle Layout = "battle"

	// LayoutPlanar is a plane and phenomenon card layout.
	LayoutPlanar Layout = "planar"

	// LayoutScheme is a scheme card layout.
	LayoutScheme Layout = "scheme"

	// LayoutVanguard is a vanguard card layout.
	LayoutVanguard Layout = "vanguard"

	// LayoutToken is a token card layout.
	LayoutToken Layout = "token"

	// LayoutDoubleFacedToken is a card token layout with another token
	// printed on the back.
	LayoutDoubleFacedToken Layout = "double_faced_token"

	// LayoutEmblem is an emblem card layout.
	LayoutEmblem Layout = "emblem"

	// LayoutAugment is an augment card layout.
	LayoutAugment Layout = "augment"

	// LayoutHost is host card layout.
	LayoutHost Layout = "host"

	// LayoutArtSeries is an Art Series collectable double-faced card layout.
	LayoutArtSeries Layout = "art_series"

	// LayoutReversible is a card layout with two sides that are unrelated.
	LayoutReversible Layout = "reversible_card"
)

type Legalities 

type Legalities struct {
	Standard  Legality `json:"standard"`
	Modern    Legality `json:"modern"`
	Pauper    Legality `json:"pauper"`
	Pioneer   Legality `json:"pioneer"`
	Legacy    Legality `json:"legacy"`
	Penny     Legality `json:"penny"`
	Vintage   Legality `json:"vintage"`
	Duel      Legality `json:"duel"`
	Commander Legality `json:"commander"`
	Future    Legality `json:"future"`
}

Legalities describes the legality of a card across formats.

type Legality 

type Legality string

Legality is the legality of a card in a particular format. 

const (
	// LegalityLegal indicates the card is legal in the format.
	LegalityLegal Legality = "legal"

	// LegalityNotLegal indicates the card is not legal in the format.
	LegalityNotLegal Legality = "not_legal"

	// LegalityBanned indicates the card is banned in the format.
	LegalityBanned Legality = "banned"

	// LegalityRestricted indicates the card is restricted to one copy in
	// the format.
	LegalityRestricted Legality = "restricted"
)

type ManaCost 

type ManaCost struct {
	// Cost is the normalized cost, with correctly-ordered and wrapped mana
	// symbols.
	Cost string `json:"cost"`

	// CMC is the converted mana cost. If you submit Un-set mana symbols,
	// this decimal could include fractional parts.
	CMC float64 `json:"cmc"`

	// Colors is the colors of the given cost.
	Colors []Color `json:"colors"`

	// Colorless is true if the cost is colorless.
	Colorless bool `json:"colorless"`

	// Monocolored is true if the cost is monocolored.
	Monocolored bool `json:"monocolored"`

	// Multicolored is true if the cost is multicolored.
	Multicolored bool `json:"multicolored"`
}

ManaCost is Scryfall's interpretation of a mana cost.

type OAuthConvertRequest 

type OAuthConvertRequest struct {
	Code string `json:"code"`
}

OAuthConvertRequest is an OAuth convert request.

type OAuthDowngradeRequest 

type OAuthDowngradeRequest struct {
	GrantID string `json:"grant_id"`
}

OAuthDowngradeRequest is an OAuth downgrade request.

type OAuthGrant 

type OAuthGrant struct {
	GrantID     string     `json:"grant_id"`
	CreatedAt   Timestamp  `json:"created_at"`
	Scope       OAuthScope `json:"scope"`
	GrantSecret string     `json:"grant_secret"`
	Revoked     bool       `json:"revoked"`
	Account     Account    `json:"account"`
}

OAuthGrant is an OAuth grant.

type OAuthRevokeRequest 

type OAuthRevokeRequest struct {
	GrantID string `json:"grant_id"`
}

OAuthRevokeRequest is an OAuth revoke request.

type OAuthRevokeResponse 

type OAuthRevokeResponse struct {
	GrantID   string    `json:"grant_id"`
	CreatedAt Timestamp `json:"created_at"`
	Revoked   bool      `json:"revoked"`
}

OAuthRevokeResponse is an OAuth revoke response.

type OAuthScope 

type OAuthScope string

OAuthScope is the level of access. 

const (
	// OAuthScopeRead grants the ability to inspect data on a user's
	// account. No methods that change data will be allowed.
	OAuthScopeRead OAuthScope = "read"

	// OAuthScopeReadWrite grants full API access to a user's account. The
	// application will be able to use methods that update, delete, and add
	// account data on behalf of the user.
	OAuthScopeReadWrite OAuthScope = "read_write"

	// OAuthScopeEphemeral will grant access to the user's public account
	// information, and then revoke access immediately afterward.
	//
	// Useful for creating software such as polls or petitions that only
	// need to make sure that a unique and valid account is signing or voting
	// as a one-time action.
	OAuthScopeEphemeral OAuthScope = "ephemeral"
)

type Order 

type Order string

Order is a method used to sort cards. 

const (
	// OrderName sorts cards by name, A → Z.
	OrderName Order = "name"

	// OrderSet sorts cards by their set and collector number: oldest →
	// newest.
	OrderSet Order = "set"

	// OrderRarity sorts cards by their rarity: Common → Mythic.
	OrderRarity Order = "rarity"

	// OrderColor sorts cards by their color and color identity: WUBRG →
	// multicolor → colorless.
	OrderColor Order = "color"

	// OrderUSD sorts cards by their lowest known U.S. Dollar price: 0.01 →
	// highest, null last.
	OrderUSD Order = "usd"

	// OrderTix sorts cards by their lowest known TIX price: 0.01 →
	// highest, null last.
	OrderTix Order = "tix"

	// OrderEUR sorts cards by their lowest known Euro price: 0.01 →
	// highest, null last.
	OrderEUR Order = "eur"

	// OrderCMC sorts cards by their converted mana cost: 0 → highest.
	OrderCMC Order = "cmc"

	// OrderPower sorts cards by their power: null → highest.
	OrderPower Order = "power"

	// OrderToughness sorts cards by their toughness: null → highest.
	OrderToughness Order = "toughness"

	// OrderEDHREC sorts cards by their EDHREC ranking: lowest → highest.
	OrderEDHREC Order = "edhrec"

	// OrderArtist sorts cards by their front-side artist name: A → Z.
	OrderArtist Order = "artist"
)

type Preview 

type Preview struct {
	// PreviewedAt is the date this card was previewed.
	PreviewedAt Date `json:"previewed_at"`

	// SourceURI is a link to the preview for this card.
	SourceURI string `json:"source_uri"`

	// Source is the name of the source that previewed this card.
	Source string `json:"source"`
}

type Prices 

type Prices struct {
	// USD is the price of the card in US dollars.
	USD string `json:"usd"`

	// USD is the price of the foil card in US dollars.
	USDFoil string `json:"usd_foil"`

	// USDEtched is the price of the etched card in US dollars.
	USDEtched string `json:"usd_etched"`

	// EUR is the price of the card in Euros.
	EUR string `json:"eur"`

	// EURFoil is the price of the foil card in Euros.
	EURFoil string `json:"eur_foil"`

	// Tix is the price of the card in MTGO event tickets.
	Tix string `json:"tix"`
}

Prices contains daily price information for this card, including usd, usd_foil, eur, and tix prices.

type PurchaseURIs 

type PurchaseURIs struct {
	TCGPlayer   string `json:"tcgplayer"`
	CardMarket  string `json:"cardmarket"`
	CardHoarder string `json:"cardhoarder"`
}

PurchaseURIs contains links to the card on online card stores.

type RelatedCard 

type RelatedCard struct {
	// ID is a unique ID for this card in Scryfall's database.
	ID string `json:"id"`

	// Component is a field explaining what role this card plays in the
	// relationship.
	Component Component `json:"component"`

	// Name is the name of this particular related card.
	Name string `json:"name"`

	// TypeLine is the type line of this particular related card.
	TypeLine string `json:"type_line"`

	// URI is a URI where you can retrieve a full object describing this
	// card on Scryfall's API.
	URI string `json:"uri"`
}

RelatedCard is a card that is closely related to another card (because it calls it by name, or generates a token, or meld, etc).

type RelatedURIs 

type RelatedURIs struct {
	Gatherer       string `json:"gatherer"`
	TCGPlayerDecks string `json:"tcgplayer_decks"`
	EDHREC         string `json:"edhrec"`
	MTGTop8        string `json:"mtgtop8"`
}

RelatedURIs contains links related to a card.

type Ruling 

type Ruling struct {
	// Source indicates which company produced the ruling.
	Source Source `json:"source"`

	// PublishedAt is the date when the ruling or note was published.
	PublishedAt Date `json:"published_at"`

	// Comment is the text of the ruling.
	Comment string `json:"comment"`
}

Ruling represents an Oracle ruling, Wizards of the Coast set release notes, or Scryfall notes for a particular card.

If two cards have the same name, they will have the same set of rulings objects. If a card has rulings, it usually has more than one.

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

type SearchCardsOptions 

type SearchCardsOptions struct {
	// Unique is the strategy for omitting similar cards. The default
	// strategy is UniqueModeCards.
	Unique UniqueMode `url:"unique,omitempty"`

	// Order is the method used to sort the cards. The default method is
	// OrderName.
	Order Order `url:"order,omitempty"`

	// Dir is the direction to sort the cards. The default direction is
	// DirAuto.
	Dir Dir `url:"dir,omitempty"`

	// IncludeExtras determines whether extra cards (tokens, planes, etc.)
	// should be included.
	IncludeExtras bool `url:"include_extras,omitempty"`

	// IncludeMultilingual determines whether cards in every language
	// supported by Scryfall will be included. Defaults to false.
	IncludeMultilingual bool `url:"include_multilingual,omitempty"`

	// IncludeVariations determines whether rare care variants will be
	// included, like the Hairy Runesword. Defaults to false.
	IncludeVariations bool `url:"include_variations,omitempty"`

	// Page is the page number to return. Page numbers start at 1 and the
	// default is 1.
	Page int `url:"page,omitempty"`
}

SearchCardsOptions holds the options used to search for cards.

type Set 

type Set struct {
	// ID is a unique ID for this set in Scryfall's database.
	ID string `json:"id"`

	// Code is the unique three or four-letter code for this set.
	Code string `json:"code"`

	// MTGOCode is the unique code for this set on MTGO, which may differ
	// from the regular code.
	MTGOCode *string `json:"mtgo_code"`

	// ArenaCode is the unique code for this set on Magic: The Gathering Arena,
	// which may differ from the regular code.
	ArenaCode *string `json:"arena_code"`

	// TCGplayerID is the set ID on TCGplayer's API, also known as the groupId.
	TCGplayerID *int `json:"tcgplayer_id"`

	// Name is the English name of the set.
	Name string `json:"name"`

	// URI is a link to this set object on Scryfall's API.
	URI string `json:"uri"`

	// ScryfallURI is a link to this card's permapage on Scryfall's website.
	ScryfallURI string `json:"scryfall_uri"`

	// SetType is a computer-readable classification for this set.
	SetType SetType `json:"set_type"`

	// ReleasedAt is the date the set was released (in GMT-8 Pacific
	// time). Not all sets have a known release date.
	ReleasedAt *Date `json:"released_at"`

	// BlockCode is the block code for this set, if any.
	BlockCode *string `json:"block_code"`

	// Block the block or group name code for this set, if any.
	Block *string `json:"block"`

	// ParentSetCode is the set code for the parent set, if any. promo and
	// token sets often have a parent set.
	ParentSetCode string `json:"parent_set_code"`

	// CardCount is the number of cards in this set.
	CardCount int `json:"card_count"`

	// Digital is true if this set was only released on Magic Online.
	Digital bool `json:"digital"`

	// FoilOnly is true if this set contains only foil cards.
	FoilOnly bool `json:"foil_only"`

	// IconSVGURI is 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.
	IconSVGURI string `json:"icon_svg_uri"`

	// SearchURI is a Scryfall API URI that you can request to begin
	// paginating over the cards in this set.
	SearchURI string `json:"search_uri"`
}

Set is an object which represents a group of related Magic cards. All Card objects on Scryfall belong to exactly one set.

type SetType 

type SetType string

SetType is a computer-readable classification for a set. 

const (
	// SetTypeCore is a yearly Magic core set (Tenth Edition, etc).
	SetTypeCore SetType = "Core"

	// SetTypeExpansion is a rotational expansion set in a block (Zendikar,
	// etc).
	SetTypeExpansion SetType = "expansion"

	// SetTypeMasters is a reprint set that contains no new cards (Modern
	// Masters, etc).
	SetTypeMasters SetType = "masters"

	// SetTypeMasterpiece is a set that contains masterpiece series premium
	// foil cards.
	SetTypeMasterpiece SetType = "masterpiece"

	// SetTypeFromTheVault is a From the Vault gift set.
	SetTypeFromTheVault SetType = "from_the_vault"

	// SetTypeSpellbook is a Spellbook series gift set.
	SetTypeSpellbook SetType = "spellbook"

	// SetTypePremiumDeck is a premium Deck Series decks set.
	SetTypePremiumDeck SetType = "premium_deck"

	// SetTypeDuelDeck is a Duel Decks set.
	SetTypeDuelDeck SetType = "duel_deck"

	// SetTypeDraftInnovation is a special draft set, like Conspiracy and Battlebond
	SetTypeDraftInnovation SetType = "draft_innovation"

	// SetTypeTreasureChest is a Magic Online treasure chest prize set.
	SetTypeTreasureChest SetType = "treasure_chest"

	// SetTypeCommander is a commander preconstructed set.
	SetTypeCommander SetType = "commander"

	// SetTypePlanechase is a Planechase set.
	SetTypePlanechase SetType = "planechase"

	// SetTypeArchenemy is an Archenemy set.
	SetTypeArchenemy SetType = "archenemy"

	// SetTypeVanguard is a Vanguard card set.
	SetTypeVanguard SetType = "vanguard"

	// SetTypeFunny is a funny un-set or set with funny promos (Unglued,
	// Happy Holidays, etc).
	SetTypeFunny SetType = "funny"

	// SetTypeStarter is a starter/introductory set (Portal, etc).
	SetTypeStarter SetType = "starter"

	// SetTypeBox is a gift box set.
	SetTypeBox SetType = "box"

	// SetTypePromo is a set that contains purely promotional cards.
	SetTypePromo SetType = "promo"

	// SetTypeToken is a set made up of tokens and emblems.
	SetTypeToken SetType = "token"

	// SetTypeMemorabilia is a set made up of gold-bordered, oversize, or
	// trophy cards that are not legal.
	SetTypeMemorabilia SetType = "memorabilia"
)

type Source 

type Source string

Source indicates which company produced the ruling. 

const (
	// SourceWOTC is a Wizards of the Coast ruling source.
	SourceWOTC Source = "wotc"

	// SourceScryfall is a Scryfall ruling source.
	SourceScryfall Source = "scryfall"
)

type Timestamp 

type Timestamp struct {
	time.Time
}

Timestamp is a timestamp returned by the Scryfall API.

func (*Timestamp) UnmarshalJSON 

func (t *Timestamp) UnmarshalJSON(b []byte) error

UnmarshalJSON parses a JSON encoded Scryfall timestamp and stores the result.

type UniqueMode 

type UniqueMode string

UniqueMode specifies whether Scryfall should remove duplicates from search results. 

const (
	// UniqueModeCards 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.
	UniqueModeCards UniqueMode = "cards"

	// UniqueModeArt 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.
	UniqueModeArt UniqueMode = "art"

	// UniqueModePrints 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.
	UniqueModePrints UniqueMode = "prints"
)

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.