Automating Magic: The Gathering Card Collection in Notion with Python and the notion-client Library

3 min read Nexus Nook

I've got an interesting post for you today. If you're into Magic: The Gathering, you're in for a treat. But don't worry if Magic isn't your thing – you might still be interested in the Notion API I used to create this script. I made use of this Python library: https://pypi.org/project/notion-client/.

Thanks to my brother, since 1997 I'm into Magic the Gathering, even if I stopped for about 15 years, since 2022 I'm back in the game, so I felt compelled to create a database, inspired by Thomas Frank tweet:

You can find the GitHub repository here: https://github.com/alessandrobelli/mtg-notion-importer. Any suggestion or help is welcome!

First, let's take a look at the Notion Database table structure that you need to create before you run the script. You can get a better understanding of the table from the new_page variable:

Column Name Column Type Description
Name Title Name of the card
Type Multi-select Card type(s)
Mana Cost Text Mana cost of the card
Set Multi-select Set the card belongs to
Rarity Select Rarity of the card
Text Text Oracle text of the card
Flavor Text Text Flavor text of the card
Power Text Power of the card (for creatures)
Toughness Text Toughness of the card (for creatures)
Power/Toughness Text Combined power/toughness (for creatures)
Loyalty Text Loyalty of the card (for planeswalkers)
Legalities Multi-select Legalities in various formats
Artist Text Name of the card's artist
Keywords Multi-select Keywords found in the card's oracle text
Scryfall ID Text Unique identifier for the card from Scryfall database

To run the script, follow these steps:

  1. Ensure you have Python installed on your computer. If you don't have it, you can download it from the official Python website.
  2. Install the required Python libraries by running the following command in your terminal or command prompt:pip install notion-client requests.
  3. Clone or download the script from the GitHub repository. If you're not familiar with cloning a GitHub repository, you can simply download the ZIP file and extract it to a folder on your computer.
  4. Create a .env file and set up your Notion API key and database ID.

Open your terminal or command prompt, navigate to the directory where you saved the script, and run the following command: python script_name.py
Replace script_name.py with the actual name of the script file.

This is how it looks when importing:

For more detailed instructions and explanations, please visit the GitHub page of the project.

Now let's break down the main functions of the script:

  1. get_most_recent_card(): Retrieves the most recent card from your Notion database, based on the updated_at property. This is used to ask if you want to restart after a crash, or you want to simply restart the script from the same set after you stopped it.
  2. update_or_create_page(): Updates an existing page or creates a new one with the card information. This function uses exponential backoff to handle HTTP errors and timeouts. I'm not sure why, but while developing the script I encountered a lot of 502 and timeout errors in the Notion Api.
  3. create_table_block(): Creates a table block for the card page, containing preview data, prices, related URIs, and purchase URIs.
  4. format_legalities(): Formats the card's legalities into a more readable form.
  5. get_card_by_scryfall_id(): Retrieves a card from the Notion database by its Scryfall ID, using exponential backoff for error handling.
  6. extract_keywords(): Extracts keywords from a card's oracle text.
  7. import_cards(): Imports cards from the Scryfall API, updating or creating pages for each card in the Notion database.

In conclusion, this script is a great way to import Magic: The Gathering cards into your Notion database. There I created a “self relation” property called “combo”, but you can find in many ways how to build decks or find combos.

However, please be aware that it might take some time to finish since Magic has more than 22,000 cards. I hope you found this article useful or you could be a little inspired by the script.

Thanks a lot for reading, feel free to share if you liked it! See you next time!

Get the Notion Nook

Successfully sent!

Check your inbox for the email confirmation.

Error!

Something went wrong.