MTGJSON

# MTGGraphQL

MTGGraphQL (opens new window), a sub-service of MTGJSON, is a GraphQL API and Server built on top of the MTGJSON data sets. The goal being to reduce the amount of unnecessary data retrieved and empowering clients with the power to ask for exactly what they need from the MTGJSON service and nothing more. This service will also allow us to connect future projects & changes under a single API that can evolve over time. The current service focuses on JSON payloads for:

  • Cards
  • Decks
  • Sets
  • Metadata

The beta rollout of the service will be available to all Patreon supporters with the goal of bringing a version to the rest of the community in the near future. Feel free to submit suggestions via the Discord Server (opens new window).

# Service Overview

# Data Source

The GraphQL endpoint is based on the latest MTGJSONv5 release. The dataset is normally refreshed once a week, coinciding with the MTGJSON weekly rebuild.

# Rate Limits

The current rate limits are capped at 1,000 requests per IP Address per hour and 500 requests per key per hour.

# NPM Typescript Package

To go along with MTGGraphQL, we have released a Typescript package for your convenience: mtggraphql (opens new window)

# Service Usage

# GraphQL Playground

We provide an GraphQL Playground (opens new window) where you can query the server and get a response. The playground consists of 3 main sections:

  • The top left, for your query.
  • The bottom left tabs, containing HTTP HEADERS for your authorization.
  • The right, which has the server response.

# Example Headers Authorization

{
  "authorization": "Bearer <Token>"
}

# Example Query

query{
  cards(
    input:{
        name: "Phelddagrif"
      },
      page:{
        take: 100,
        skip: 0
      },
      order:{
        order:ASC
      }
  )
  {
    name
    setCode
    type
    text
  }
}

# Example Response

{
  "data": {
    "cards": [
      {
        "name": "Phelddagrif",
        "setCode": "ME1",
        "type": "Legendary Creature — Phelddagrif",
        "text": "{G}: Phelddagrif gains trample until end of turn. Target opponent creates a 1/1 green Hippo creature token.\n{W}: Phelddagrif gains flying until end of turn. Target opponent gains 2 life.\n{U}: Return Phelddagrif to its owner's hand. Target opponent may draw a card."
      },
      ... // More cards
    ]
  }
}

# Client-based Querying

Assuming you send the proper Headers, you can use an HTTP request on the GraphQL endpoint with the following format:

https://mtgjson.com/graphql?query=query{cards(input:{name:"Phelddagrif"},page:{take:100,skip:0},order:{order:ASC}){name,setCode,type,text}}

You can utilize a tool like Apollo to make client-based calls. See the Apollo Documentation (opens new window) for more information.