scryfall

package module
v0.1.1 Latest Latest
Warning

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

 Go to latest Published: Dec 25, 2025 License: MIT Imports: 11 Imported by: 0

README

Scryfall Go Client

Go Reference Go Report Card CI

A lightweight Go client for the Scryfall API.

  • Focused on the core API + bulk data endpoints
  • Configurable base URL, user agent, rate limiter, and HTTP client
  • Streaming bulk data parsing for large payloads

Installation

go get github.com/repricah/scryfall

Quick Start

package main

import (
    "context"
    "fmt"

    "github.com/repricah/scryfall"
)

func main() {
    client := scryfall.NewClient(
        scryfall.WithUserAgent("my-app/1.0"),
    )

    card, err := client.GetCardByID(context.Background(), "0cc2cb3f-b1e7-4d6c-8ae6-6f4d095e0b6c")
    if err != nil {
        panic(err)
    }

    fmt.Println(card.Name)
}

Bulk Data Streaming

err := client.DownloadBulkDataStream(ctx, bulk.DownloadURI, func(card scryfall.Card) error {
    // process each card
    return nil
}, func(current, total int64) {
    // progress tracking
})

Configuration

client := scryfall.NewClient(
    scryfall.WithBaseURL("https://api.scryfall.com"),
    scryfall.WithUserAgent("my-app/1.0"),
    scryfall.WithLimiter(rate.NewLimiter(rate.Limit(10), 10)),
    scryfall.WithHTTPClient(&http.Client{Timeout: 30 * time.Second}),
)

API Notes

Scryfall requests should include a clear user agent that identifies your app. See the official documentation and API announcements for usage policies and bulk data details:

License

MIT License - see LICENSE for details.

Documentation

Overview

Package scryfall provides a lightweight Go client for the Scryfall API.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type APIError 

type APIError struct {
	StatusCode int
	Details    string   `json:"details"`
	Type       string   `json:"type"`
	Warnings   []string `json:"warnings"`
}

APIError represents an error returned by the Scryfall API.

func (*APIError) Error 

func (e *APIError) Error() string

type Card 

type Card struct {
	ID              string            `json:"id"`
	OracleID        string            `json:"oracle_id"`
	Name            string            `json:"name"`
	Lang            string            `json:"lang"`
	ReleasedAt      string            `json:"released_at"`
	Set             string            `json:"set"`
	CollectorNumber string            `json:"collector_number"`
	Rarity          string            `json:"rarity"`
	Layout          string            `json:"layout"`
	ManaCost        string            `json:"mana_cost"`
	TypeLine        string            `json:"type_line"`
	OracleText      string            `json:"oracle_text"`
	Power           string            `json:"power"`
	Toughness       string            `json:"toughness"`
	Loyalty         string            `json:"loyalty"`
	CMC             float64           `json:"cmc"`
	Keywords        []string          `json:"keywords"`
	Prices          CardPrices        `json:"prices"`
	ImageURIs       map[string]string `json:"image_uris"`
	CardFaces       []CardFace        `json:"card_faces"`
	TcgplayerID     int               `json:"tcgplayer_id"`
	CardmarketID    int               `json:"cardmarket_id"`
	Uri             string            `json:"uri"`
	ScryfallURI     string            `json:"scryfall_uri"`
	RulingsURI      string            `json:"rulings_uri"`
	PrintsSearchURI string            `json:"prints_search_uri"`
	Digital         bool              `json:"digital"`
	Reserved        bool              `json:"reserved"`
	EDHRecRank      int               `json:"edhrec_rank"`
	PennyRank       int               `json:"penny_rank"`
	Games           []string          `json:"games"`
	Promo           bool              `json:"promo"`
	Reprint         bool              `json:"reprint"`
	Variation       bool              `json:"variation"`
	Oversized       bool              `json:"oversized"`
	StorySpotlight  bool              `json:"story_spotlight"`
	FullArt         bool              `json:"full_art"`
	Textless        bool              `json:"textless"`
	Booster         bool              `json:"booster"`
	FrameEffects    []string          `json:"frame_effects"`
	Frame           string            `json:"frame"`
	SecurityStamp   string            `json:"security_stamp"`
	BorderColor     string            `json:"border_color"`
	Watermark       string            `json:"watermark"`
}

Card represents the subset of the Scryfall card schema we ingest.

type CardBulkData 

type CardBulkData struct {
	ID              string `json:"id"`
	Type            string `json:"type"`
	UpdatedAt       string `json:"updated_at"`
	URI             string `json:"uri"`
	Name            string `json:"name"`
	Description     string `json:"description"`
	DownloadURI     string `json:"download_uri"`
	ContentType     string `json:"content_type"`
	ContentEncoding string `json:"content_encoding"`
	CompressedSize  int64  `json:"compressed_size"`
	PermalinkURI    string `json:"permalink_uri"`
}

CardBulkData describes downloadable data sets available from Scryfall.

type CardFace 

type CardFace struct {
	Name       string            `json:"name"`
	ManaCost   string            `json:"mana_cost"`
	TypeLine   string            `json:"type_line"`
	OracleText string            `json:"oracle_text"`
	Colors     []string          `json:"colors"`
	Power      string            `json:"power"`
	Toughness  string            `json:"toughness"`
	Loyalty    string            `json:"loyalty"`
	FlavorText string            `json:"flavor_text"`
	ImageURIs  map[string]string `json:"image_uris"`
}

CardFace captures the data returned for double-faced cards.

type CardPrices 

type CardPrices struct {
	USD       string `json:"usd"`
	USDFoil   string `json:"usd_foil"`
	USDEtched string `json:"usd_etched"`
	EUR       string `json:"eur"`
	EURFoil   string `json:"eur_foil"`
	TIX       string `json:"tix"`
}

CardPrices represent the various market prices returned by Scryfall as strings.

type CardSet 

type CardSet struct {
	ID          string `json:"id"`
	Code        string `json:"code"`
	Name        string `json:"name"`
	ReleasedAt  string `json:"released_at"`
	SetType     string `json:"set_type"`
	CardCount   int    `json:"card_count"`
	Digital     bool   `json:"digital"`
	NonfoilOnly bool   `json:"nonfoil_only"`
	FoilOnly    bool   `json:"foil_only"`
	IconSVGURI  string `json:"icon_svg_uri"`
}

CardSet represents a Scryfall set object.

type Client 

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

Client interacts with the public Scryfall API while enforcing basic rate limiting and structured logging.

func NewClient 

func NewClient(opts ...Option) *Client

NewClient constructs a Scryfall API client with sane defaults.

func (*Client) DownloadBulkData 

func (c *Client) DownloadBulkData(ctx context.Context, downloadURI string) ([]Card, error)

DownloadBulkData is a legacy wrapper around DownloadBulkDataStream that loads everything into memory. Deprecated: Use DownloadBulkDataStream for large datasets.

func (*Client) DownloadBulkDataStream 

func (c *Client) DownloadBulkDataStream(ctx context.Context, downloadURI string, cardCallback func(Card) error, progressFn ProgressFunc) error

DownloadBulkDataStream downloads and parses a bulk data file from Scryfall using streaming. It calls the provided callback for each card object encountered. progressFn, if provided, will be called periodically with the number of bytes read.

func (*Client) DownloadToFile 

func (c *Client) DownloadToFile(ctx context.Context, downloadURI string, filePath string, progress ProgressFunc) error

DownloadToFile downloads a bulk data file to a local file path with progress tracking.

func (*Client) GetBulkDataByType 

func (c *Client) GetBulkDataByType(ctx context.Context, bulkType string) (*CardBulkData, error)

GetBulkDataByType retrieves a single bulk data object by its type.

func (*Client) GetCardByID 

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

GetCardByID retrieves an individual card using its Scryfall UUID.

func (*Client) ListBulkData 

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

ListBulkData fetches metadata about Scryfall bulk data exports.

func (*Client) ListSets 

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

ListSets fetches all sets from Scryfall.

func (*Client) ProcessBulkDataStream 

func (c *Client) ProcessBulkDataStream(reader io.Reader, cardCallback func(Card) error) error

ProcessBulkDataStream handles the streaming JSON parsing from an io.Reader.

type ClientAPI 

type ClientAPI interface {
	GetCardByID(ctx context.Context, id string) (*Card, error)
	ListBulkData(ctx context.Context) ([]CardBulkData, error)
	ListSets(ctx context.Context) ([]CardSet, error)
	GetBulkDataByType(ctx context.Context, bulkType string) (*CardBulkData, error)
	DownloadBulkDataStream(ctx context.Context, downloadURI string, cardCallback func(Card) error, progressFn ProgressFunc) error
	DownloadBulkData(ctx context.Context, downloadURI string) ([]Card, error)
}

ClientAPI exposes the Scryfall client methods used by downstream services. It enables testing with lightweight fakes without pulling in extra deps.

type Option 

type Option func(*Client)

Option configures the Scryfall client.

func WithBaseURL 

func WithBaseURL(rawURL string) Option

WithBaseURL overrides the API base URL.

func WithHTTPClient 

func WithHTTPClient(httpClient *http.Client) Option

WithHTTPClient sets a custom HTTP client instance.

func WithLimiter 

func WithLimiter(limiter *rate.Limiter) Option

WithLimiter injects a custom rate limiter configuration.

func WithLogger 

func WithLogger(logger *log.Logger) Option

WithLogger sets a custom structured logger.

func WithUserAgent 

func WithUserAgent(ua string) Option

WithUserAgent overrides the default user agent header.

type ProgressFunc 

type ProgressFunc func(current, total int64)

ProgressFunc is a callback for tracking progress in bytes.

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.