mtg-db

Ruby gem containing structured data for all Magic: The Gathering cards.

Installation

Include in your Gemfile

source 'https://rubygems.org'
gem 'mtg-db', '>= 2.4.2'

or install from Rubygems

gem install mtg-db

Usage

Ruby

require 'mtg-db'

all_sets = Mtg::Db.sets
all_set_json = Mtg::Db.sets.to_json

all_cards = Mtg::Db.cards
all_card_json = Mtg::Db.cards.to_json

aether_revolt_cards = Mtg::Db.cards(:aer)

JSON Format

Sets

A set¹ in Magic: The Gathering is a pool of cards released together and designed for the same play environment.

ATTRIBUTES

• name Required string. The set's name as listed on Wizards of the Coasts's Gatherer card database.
• release_date Required string. The calendar date of the set's release. In the case of some older sets, the closest known date is used.
• code Required string. The unique code used to identify the set. Often a three-character string. Notable exceptions are Masterpiece sets and Duel Decks with codes mps_kld, dd3_dvd, etc.

EXAMPLE JSON

{
  "name": "Aether Revolt",
  "release_date": "January 20, 2017",
  "code": "aer"
}

EXCEPTIONS

mtg-db overrides the attributes of some sets to maintain internal consistency and correct Gatherer errors. See these override files:

• excluded_sets.yml
• set_code_overrides.yml
• set_name_overrides.yml

Cards

ATTRIBUTES

• name Required string. The cards's name as listed on Wizards of the Coasts's Gatherer card database.
• set_name Required string. The Magic set this card is from.
• collector_num² Required string. This card's collector number. First used in Exous, collector numbers for earlier sets have been generated using the same ordering system. May contain letters and numbers.
• illustrator Optional string. The illustrator of this card's art.
• types³ Required string array of the card's types. Possible values are Artifact, Conspiracy, Creature, Enchantment, Instant, Land, Planeswalker, Sorcery, Tribal, and Vanguard.
• supertypes⁴ Optional string array of the card's supertypes. Possible values are Basic, Legendary, World, and Snow.
• subtypes⁵ Optional string array of the card's subtypes.
• rarity⁶ Required string. Rarity defines the scarcity of cards in boosters and indicates the complexity of the card. Possible values are Common, Uncommon, Rare, Mythic, Special, and Land.
• mana_cost⁷ Optional string. The mana payment required to cast a spell. See mana_cost_symbols.yml for the system used to encode mana symbols.
• converted_mana_cost⁸ Required integer. The total amount of mana the card's mana cost, regardless of color.
• oracle_text⁹ Optional string array of the card's up-to-date rules text. Each element of the array represents one line of rules text. Four times a year the Oracle is updated to incorporate changes to cards that do not work as intended.
• flavor_text¹⁰ Optional string. Italicized text that serves to provide mood or give background information on the game world, but has no effect on gameplay.
• power¹¹ Optional string. The amount of damage a Creature or Vehicle deals. Usually an integer, but may contain a modifier such as * or X.
• toughness¹² Optional string. The amount of damage needed to kill a Creature or Vehicle. Usually an integer, but may contain a modifier such as * or X.
• loyalty¹³ Optional string. The number of loyalty counters a Planeswalker enters the battlefield with. Usually an integer, but may contain a modifier such as X.
• multiverse_id: Optional integer. An identifier unique to the printing of a card. Cards missing from Gatherer will have an empty multiverse_id.
• other_part: Optional string. The name of the other half of a double-faced,¹⁴ flip,¹⁵ meld,¹⁶ or split card.¹⁷
• color_indicator¹⁸ Optional string. Used when a card's color can't be identified by its mana cost. Possible values are White, Blue, Black, Red, or Green
• rulings Optional array of objects, each containing the text and date for an Oracle ruling associated with this card.

EXAMPLE JSON

{
  "name": "Aerial Modification",
  "set_name": "Aether Revolt",
  "collector_num": "1",
  "illustrator": "Jung Park",
  "types": [
    "Enchantment"
  ],
  "supertypes": [],
  "subtypes": [
    "Aura"
  ],
  "rarity": "Uncommon",
  "mana_cost": "4W",
  "converted_mana_cost": 5,
  "oracle_text": [
    "Enchant creature or Vehicle",
    "As long as enchanted permanent is a Vehicle, it's a creature in addition to its other types.",
    "Enchanted creature gets +2/+2 and has flying."
  ],
  "flavor_text": null,
  "power": null,
  "toughness": null,
  "loyalty": null,
  "multiverse_id": 423668,
  "other_part": null,
  "color_indicator": null,
  "rulings": [
    {
      "date": "2/9/2017",
      "text": "If Aerial Modification becomes unattached from a Vehicle that’s attacking or blocking, that Vehicle will be removed from combat unless another effect (such as its crew ability) is also making it a creature."
    }
  ]
}

EXCEPTIONS

mtg-db overrides the attributes of some cards to maintain internal consistency and correct Gatherer errors. See these override files:

• card_json_overrides.yml
• card_name_overrides.yml
• collector_num_overrides.yml
• excluded_multiverse_ids.yml
• flavor_text_overrides.yml
• illustrator_overrides.yml
• partner_card_names.yml
• split_card_names.yml