GraphQL reference

Optional, and useful when one round trip should return several games or several related resources. REST covers every capability if you would rather not run a GraphQL client.

When GraphQL earns its keep

Most card APIs are REST-only, and for a single lookup REST is simpler. GraphQL is worth it in two situations:

Several games at once. A collection view that spans Pokémon, Magic and Lorcana is one request instead of three.
Narrow field selection. Card records are large. If you only need names and prices for a list view, selecting two fields keeps the payload small on mobile.

If neither applies, use REST.

Endpoint

https://api.tcggraph.com/graphql

curl "https://api.tcggraph.com/graphql" \
  -H "Authorization: Bearer $TCGGRAPH_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"{ games { slug name sampleCount } }"}'

Schema

type Query {
  card(id: ID!): Card
  cards(filter: CardFilter, sort: CardSort, page: Int, limit: Int): CardConnection!
  games: [GameInfo!]!
  game(slug: String!): GameInfo
}

type Card {
  id: ID!
  game: Game!
  name: String!
  set: Set!
  collectorNumber: String!
  rarity: String!
  artist: String
  text: String
  images: Images!
  prices: [Price!]!
  legalities: JSON!
  gameData: JSON!
}

input CardFilter {
  game: Game
  name: String
  text: String
  rarity: String
  set: String
  artist: String
  source: PriceSource
  minPrice: Float
  maxPrice: Float
  gameData: JSON
}

enum PriceSource {
  TCGPLAYER   # North America, quoted in USD
  CARDMARKET  # Europe, quoted in EUR
}

type Price {
  source: PriceSource!
  region: PriceRegion!
  finish: String!
  condition: String!
  currency: String!
  market: Float
  low: Float
  high: Float
  trend: Float    # Cardmarket only
  avg1: Float     # Cardmarket only
  avg7: Float     # Cardmarket only
  avg30: Float    # Cardmarket only
  sellers: Int    # Cardmarket only
}

The Game enum

Enum values are the uppercase form of each game slug.

POKEMON                 # pokemon
MAGIC_THE_GATHERING     # magic-the-gathering
ONE_PIECE               # one-piece
YUGIOH                  # yugioh
DISNEY_LORCANA          # disney-lorcana
STAR_WARS_UNLIMITED     # star-wars-unlimited
DIGIMON                 # digimon
GRAND_ARCHIVE           # grand-archive

Selecting a market

Cards always return every quote they have. filter.source chooses which one minPrice, maxPrice and PRICE_DESC read from, in that source’s currency, and pageInfo.priceSource echoes the decision back. The price reference covers both markets in detail.

Several games in one request

Use aliases to fetch each game into its own key in the response.

query Binder {
  pokemon: cards(filter: { game: POKEMON }, sort: PRICE_DESC, limit: 3) {
    nodes { name prices { market } }
  }
  magic: cards(filter: { game: MAGIC_THE_GATHERING }, sort: PRICE_DESC, limit: 3) {
    nodes { name prices { market } }
  }
  lorcana: cards(filter: { game: DISNEY_LORCANA }, sort: PRICE_DESC, limit: 3) {
    nodes { name prices { market } }
  }
}

Complexity limits

Queries are bounded by depth and complexity to keep one client from degrading the service for everyone. Exceeding either returns 422 unprocessable_query naming the offending path. Each root field in a query is billed separately — see credits and rate limits.