MTGJSON v5

MTGJSON is an open-source repository of Magic: The Gathering card data, specifically in JSON and CSV formats. This repository contains the build scripts we use to create our data sets.

How to Contribute

Running a project as large as ours isn't easy, and we rely on the community to help keep our project going. The community can support us through two different ways: financial contributions and code contributions.

We accept reoccurring donations via GitHub Sponsors, that grant priority support from MTGJSON maintainers and a special role on our Discord indicating your support. This is the preferred approach for financial contributions, as the MTGJSON team pays no fees for these types of donations!

We accept reoccurring donations via Patreon, that grant priority support from MTGJSON maintainers and a special role on our Discord indicating your support.

We accept one-time donations via PayPal, for those who want to say thank you to the project.

We love it when the community contributes back to the project! If you'd like to help improve our data for the hundreds of projects and stores we support, do reach out via Discord!

Connect With Us

The team stays in contact via Discord. The server is open to the public and is a great place to collaborate with other like-minded people. Stop by today and say hi!

About Us

The Team

The MTGJSON team has been led by Zach Halpern since 2018, with support from an awesome group of people. The full team lineup can be found MTGJSON's homepage.

Our Product

MTGJSON at its core is a database that can be downloaded for offline access to Magic: the Gathering card data. We pride ourselves on our documentation, and aim for full transparency with the community.

Our Partners

Over time, MTGJSON has gone through a number of transitions to bring the best product for our consumers. We'd like to thank the following groups, in alphabetical order, for helping to support our mission by enriching our data:

• CardHoarder
• CardKingdom
• CardMarket
• Gatherer
• MTG.wtf
• MTGBan
• Scryfall
• TCGPlayer
• What's in Standard

How to Use

For 99% of our Users

MTGJSON supplies precompiled databases at https://mtgjson.com/api/v5/. This is the recommended way to use our service.

As stated before, we pride ourselves on our documentation which can be found at https://mtgjson.com/. If you find anything to be unclear or ambiguous, please open a ticket on our documentation repository so we can address your concern immediately.

We fully rebuild our API data once a week (on Monday afternoons) and our price dataset once a day. You can poll the Meta.json file to see when our data was last updated.

For those who want to build MTGJSON locally

Most of our users shouldn't have a need to build MTGJSON locally. However, there are always exceptions and we aren't ones to judge.

Build Box

While MTGJSON will work on Windows, Mac, and Linux, we prefer working within the Linux environment for lower overheads and less manual dependency management.

• For Linux based build boxes (we recommend Ubuntu 20.04), your build box should have at least 2 cores and 4 GiB of RAM available.
• For Mac based build boxes, your build box should have at least 2 cores and 4 GiB of RAM available.
• For Windows based build boxes, your build box should have at least 4 cores and 8 GiB of RAM available.

Install Python3

MTGJSON is built on and tested against a wide range of Python3 verisons. Currently, we maintain support for the following versions:

• Python 3.6
• Python 3.7
• Python 3.8

Install MTGJSON

Local Installation

python3 -m pip install /path/to/mtgjson5/

PyPi Repository

We intend to put MTGJSON5 on the pip package archive in the near future, once the first set of revisions takes place.

Using MTGJSON

A fully up-to-date help menu can be achieved via python3 -m mtgjson5 -h, but for your convenience here is a recent rundown:

usage: mtgjson5 [-h] [-s [SET [SET ...]] | -a] [-c] [-x] [-z] [-p]
                [-SS [SET [SET ...]]] [-PB] [-R] [-NA]

optional arguments:
  -h, --help            show this help message and exit
  -s [SET [SET ...]], --sets [SET [SET ...]]
                        Set(s) to build, using Scryfall set code notation.
                        Non-existent sets silently ignored.
  -a, --all-sets        Build all possible sets, overriding the --sets option.
  -c, --full-build      Build new prices, MTGSQLive, and compiled outputs like
                        AllPrintings.
  -x, --resume-build    While determining what sets to build, ignore
                        individual set files found in the output directory.
  -z, --compress        Compress the output folder's contents for
                        distribution.
  -p, --pretty          When dumping JSON files, prettify the contents instead
                        of minifying them.
  -SS [SET [SET ...]], --skip-sets [SET [SET ...]]
                        Purposely exclude sets from the build that may have
                        been set using --sets or --all-sets.

mtgjson maintainer arguments:
  -PB, --price-build    Build updated pricing data then exit.
  -R, --referrals       Create and maintain a referral map for referral
                        linkages.
  -NA, --no-alerts      Prevent push notifications from sending when property
                        keys are defined.

MTGJSON Environment Variables

Due to how the new system is built, a few advanced values can be set by the user in the shell environment.

• MTGJSON5_DEBUG When set to 1 or true, additional logging will be dumped to the output files
• MTGJSON5_OUTPUT_PATH When set, MTGJSON will dump all outputs to a specific directory
  • Ex: MTGJSON5_OUTPUT_PATH=~/Desktop will dump database files to /home/USER/Desktop/mtgjson_build_5XXX and log files to /home/USER/Desktop/logs

Licensing

MTGJSON is a freely available product under the MIT License, allowing our users to enjoy Magic: the Gathering data free of charge, in perpetuity.