NAV
ruby python elixir javascript php cURL

Overview

Welcome to the Pokémon TCG API! You can use the API to access Pokémon TCG API endpoints, which can get information on cards and sets. All API access is performed over HTTPS and accessed from the api.pokemontcg.io domain.

There are language bindings in multiple languages! You can view code examples in the dark area to the right, and you can switch the programming language of the examples with the tabs in the top right.

To chat with other developers and discuss the API and SDKs, check out the Discord Server!

Developer SDKs

There are multiple developer SDKs available. To see how to install and use them, check the links below:

Keep an eye out for more SDKs as they become available.

Contributing

The best way to contribute to the project right now is by creating developer SDKs. When creating an SDK, you should try to follow the design of the others. For example, in general, the following basic functionality should be supported:

Card.all Card.find(id) Card.where(params) Set.all Set.find(id) Set.where(params)

When developing, it is important to follow idiomatic consistency. That is, if you are developing a Ruby SDK, make sure it looks and feels like Ruby. So while part of a card response in JSON is nationalPokedexNumber, this should be represented as national_pokedex_number in Ruby.

Rate Limits

Overview

HTTP/1.1 403 Forbidden
Date: Mon, 21 Apr 2014 13:26:48 GMT
Content-Type: application/json; charset=utf-8
{
  "message": "Rate Limit Exceeded"
}

Rate limits are enforced for all third-party applications and services. This document is an overview of the rate limits themselves, as well as how they are enforced and best practices for handling the errors returned when a rate limit is reached.

Third-party applications are currently throttled to 5000 requests per hour and resource. That is, you could make 5000 requests to the Card resource in an hour, and also 5000 requests to the Set resource in an hour. As this API continues to age, the rate limits may be updated to provide better performance to users.

Rationale

As previously mentioned, the primary goal is to provide a responsive interface for developers and users to use when accessing the Pokémon TCG data. Since each request made to the API incurs a computational cost, it’s in the best interest of both Pokémon TCG API and its developer partners that these costs be minimized to the greatest degree possible.

Rate limiting also helps third-party developers by encouraging them to build their integrations to make economical use of API requests.

Errors

HTTP/1.1 404 Not Found
Date: Mon, 21 Apr 2014 13:26:48 GMT
Content-Type: application/json; charset=utf-8
{
  "status": "404",
  "error": "Not Found"
}

The Pokémon TCG API uses the following error codes:

Error Code Meaning
400 Bad Request – Your request sucks
403 Forbidden – You have exceeded the rate limit
404 Not Found – The specified resource could not be found
500 Internal Server Error – We had a problem with our server. Try again later.
503 Service Unavailable – We’re temporarially offline for maintanance. Please try again later.

Headers

There are quite a few custom response headers available when making a request. Some of these will only show up when the results are paginated.

Link: <https://api.pokemontcg.io/v1/cards?page=82>; rel="last", <https://api.pokemontcg.io/v1/cards?page=2>; rel="next"
Page-Size: 100
Count: 100
Total-Count: 8190
Ratelimit-Limit: 5000
Ratelimit-Remaining: 4999
  1. Link: Link headers with prev, last, next, first links (when appropriate)
  2. Page-Size: The page size for the request
  3. Count: The number of elements returned
  4. Total-Count: The total number of elements (across all pages)
  5. Ratelimit-Limit: The ratelimit for a given user
  6. Ratelimit-Remaining: The number of requests left before the ratelimit is exceeded.

Cards

Get All Cards

This endpoint retrieves all cards.

By default, results are limited to 100 cards. Use the page url parameter to view more results. You can also adjust the limit via the pageSize url parameter. This has a maximum of 1000 cards per request.

https://api.pokemontcg.io/v1/cards?page=5&pageSize=500

require 'pokemon_tcg_sdk'

# Get all Cards
cards = Pokemon::Card.all

# Filter Cards
# You can chain 'where' clauses together. The key of the hash
# should be the URL parameter you are trying to filter on
cards = Pokemon::Card.where(supertype: 'pokemon')
                 .where(types: 'dragon|fire|flying')
                 .where(hp: 'gt100')
                 .all

# Get cards on a specific page / pageSize
cards = Pokemon::Card.where(page: 50).where(pageSize: 500).all
from pokemontcgsdk import Card

# Get all Cards
cards = Card.all()

# Filter Cards
# You can chain 'where' clauses together. The key of the hash
# should be the URL parameter you are trying to filter on
cards = Card.where(supertype='pokemon') \
                 .where(types='dragon|fire|flying') \
                 .where(hp='gt100') \
                 .all()

# Get cards on a specific page / pageSize
cards = Card.where(page=50).where(pageSize=500).all()
# Get all Cards
cards = Pokemon.Card.all

# Filter Cards
cards = Pokemon.Card.where(supertype: "pokemon", types: "dragon|fire|flying", hp: "gt100")

# Get cards on a specific page / pageSize
cards = Pokemon.Card.where(page: 5, pageSize: 100)
const pokemon = require('pokemontcgsdk')

// Get all cards
pokemon.card.all()
.on('data', function (card) {
  console.log(card.name)
});

// Filter Cards
pokemon.card.all({ supertype: 'pokemon', types: 'dragon|fire|flying', hp: 'gt100' })
.on('data', function (card) {
    console.log(card.name)
});

// Get cards on a specific page / pageSize
pokemon.card.where({ page: 50, pageSize: 500})
.then(cards => {
    console.log(cards[0].name)
})

<?php

# Get all Cards
$cards = Pokemon::Card()->all();

# Filter Cards
$cards = Pokemon::Card()->where([
  'supertype' => 'pokemon', 
  'types' => 'dragon|fire|flying',
  'hp' => 'gt100'
])->all();

# Get cards on a specific page / pageSize
$cards = Pokemon::Card()->where([
    'page'     => 50,
    'pageSize' => 100
])->all();
# Get all cards
curl "https://api.pokemontcg.io/v1/cards"

# Filter cards
curl "https://api.pokemontcg.io/v1/cards?supertype=pokemon&types=dragon|fire|flying&hp=gt100"

# Get specific page of data
curl "https://api.pokemontcg.io/v1/cards?page=50&pageSize=500"

The following JSON is what a sample response to the Cards resource looks like:

{
  "cards": [
  {
    "id": "xy7-54",
    "name": "Gardevoir",
    "nationalPokedexNumber": 282,
    "imageUrl": "https://s3.amazonaws.com/pokemontcg/xy7/54.png",
    "subtype": "Stage 2",
    "supertype": "Pokémon",
    "ability": {
      "name": "Bright Heal",
      "text": "Once during your turn (before your attack), you may heal 20 damage from each of your Pokémon."
    },
    "hp": "130",
    "retreatCost": [
      "Colorless",
      "Colorless"
    ],
    "number": "54",
    "artist": "TOKIYA",
    "rarity": "Rare Holo",
    "series": "XY",
    "set": "Ancient Origins",
    "setCode": "xy7",
    "types": [
      "Fairy"
    ],
    "attacks": [
      {
      "cost": [
        "Colorless",
        "Colorless",
        "Colorless"
      ],
      "name": "Telekinesis",
      "text": "This attack does 50 damage to 1 of your opponent's Pokémon. This attack's damage isn't affected by Weakness or Resistance.",
      "damage": "",
      "convertedEnergyCost": 3
      }
    ],
    "weaknesses": [
      {
        "type": "Metal",
        "value": "×2"
      }
    ],
    "resistances": [
      {
        "type": "Darkness",
        "value": "-20"
      }
    ]
}

HTTP Request

GET https://api.pokemontcg.io/v1/cards

Query Parameters

Each field below can be used as a query parameter. By default, fields that have a singular value such as rarity, set, and name will always use a logical “or” operator when querying with a list of values. Fields that can have multiple values such as types, weaknesses and resistances can use a logical “and” or a logical “or” operator.

The accepted delimiters when querying fields are the pipe character (’|’) or a comma (’,’) character. The pipe represents a logical “or”, and a comma represents a logical “and”. The comma can only be used with fields that accept multiple values (like types).

Example: name=charizard|blastoise|venusaur

More examples: types=metal,psychic versus types=metal|psychic

Parameter Accepts List Description
name true The card name.
nationalPokedexNumber false The national pokedex number for a card that features a Pokémon supertype
types true {and/or} The types of the card. These typically appear in the top right of card, and are denoted by energy symbol (ex. Fire, Fighting, Psychic, etc.)
subtype true The subtype of the card. Examples include MEGA, Stage 1, BREAK, Supporter, etc.
supertype true The supertype of the card. Either Pokémon, Trainer, or Energy.
hp false The hit points of the card. This typically appears in the top right corner of the card.
number true The number of the card for the set it was released in. Found on the bottom right side of the card.
artist true The artist of the card.
rarity true The rarity of the card (ex. Rare, Rare Holo, Common, etc.)
series true The series the card appears in (ex. Base, XY, EX, etc.)
set true The set the card appears in (ex. BREAKthrough, Phantom Forces, Jungle, etc.)
setCode true The unique code of the set (ex. base1, xy5, ex3)
retreatCost false The amount of energy it takes to retreat. Found on the bottom of the card.
text true {and/or} Any additional text on a card. This includes special rules (like MEGA rules or EX), and text that appears on Trainer cards.
attackDamage false The attack damage of any given attack for a card
attackCost false The energy cost of a given attack for a card
attackName true {and/or} The name of an attack
attackText true {and/or} The text description of an attack
weaknesses true {and/or} The weaknesses of the card (ex. Fire, Water, Grass)
resistances true {and/or} The resistances of the card (ex. Fire, Water, Grass)
ancientTrait true {and/or} The Ancient Trait of the card (if exists)
abilityName true {and/or} The name of the ability
abilityText true {and/or} The text of the ability
abilityType true {and/or} The type of the ability (such as Poké-Power, Poké-Body, Pokémon Power or Ability)
contains true {and/or} Filter on cards that contain a specific field in the JSON response (ex. ?contains=ancientTrait)

Other Fields in Response

The fields below are also part of the response (if not null), but cannot be used as query parameters.

Field Description
id A unique id for this card. It is made up by taking the set code and concatenating the card number to it. (ex. xy1-1)
imageUrl The image url for a card.
imageUrlHiRes The high resolution image url for a card.
ability A passive effect during battle. Also known as Poké-Powers and Poké-Bodies from older set. With the release of Black & White, all Pokémon Powers are known as Abilities.
attacks The attacks for a given card.

Get a Specific Card

This endpoint retrieves a specific card by its id.

require 'pokemon_tcg_sdk'

card = Pokemon::Card.find('xy7-54')
from pokemontcgsdk import Card

card = Card.find('xy7-54')
card = Pokemon.Card.find("xy7-54")
const pokemon = require('pokemontcgsdk')

pokemon.card.find('xy7-54')
.then(result => {
    console.log(result.card.name)
})

<?php

$card = Pokemon::Card()->find('xy7-54');
curl "https://api.pokemontcg.io/v1/cards/xy7-54"

A sample JSON response is below:

{
  "card": {
    "id": "xy7-54",
    "name": "Gardevoir",
    "imageUrl": "https://s3.amazonaws.com/pokemontcg/xy7/54.png",
    "subtype": "Stage 2",
    "supertype": "Pokémon",
    ...
  }
}

HTTP Request

GET https://api.pokemontcg.io/v1/cards/<id>

Advanced Usage

require 'pokemon_tcg_sdk'

cards = Pokemon::Card.where(hp: 'gt100')
                     .where(types: 'psychic')
                     .all
from pokemontcgsdk import Card

cards = Card.where(hp='gt100') \
            .where(types='psychic') \
            .all()
cards = Pokemon.Card.where(hp: "gt100", types: "psychic")
const pokemon = require('pokemontcgsdk')

pokemon.card.all({ hp: 'gt100', types: 'psychic' })
.on('data', card => {
    console.log(card.name)
})

<?php

$cards = Pokemon::Card()->where([
  'hp' => 'gt100', 
  'types' => 'psychic'
])->all();
curl "https://api.pokemontcg.io/v1/cards?hp=gt100&types=psychic"

The following fields allow the modifiers gt (greater than), gte (greater than or equal to), lt (less than), and lte (less than or equal to) to used in the url parameter:

For example: https://api.pokemontcg.io/v1/cards?hp=gt50

Get cards that have the types metal and fire

# filter by type
cards = Pokemon::Card.where(types: 'metal,fire').all
# filter by type
cards = Card.where(types='metal,fire').all()
cards = Pokemon.Card.where(types: "metal,fire")
pokemon.card.all({ types: 'metal,fire' })
.on('data', card => {
    console.log(card.name)
})

<?php

$cards = Pokemon::Card()->where(['types' => 'metal,fire'])->all();
curl "https://api.pokemontcg.io/v1/cards?types=metal,fire"

GET https://api.pokemontcg.io/v1/cards?types=metal,fire

Get cards that have at least one of the types metal or fire

# filter by type (with logical or)
cards = Pokemon::Card.where(types: 'metal|fire').all
# filter by type (with logical or)
cards = Card.where(types='metal|fire').all()
cards = Pokemon.Card.where(types: "metal|fire")
pokemon.card.all({ types: 'metal|fire' })
.on('data', card => {
    console.log(card.name)
})

<?php

$cards = Pokemon::Card()->where(['types' => 'metal|fire'])->all();
curl "https://api.pokemontcg.io/v1/cards?types=metal|fire"

GET https://api.pokemontcg.io/v1/cards?types=metal|fire

Get a card by doing a partial match on the name

# filter by partial name match
cards = Pokemon::Card.where(name: 'flareon').all
# filter by partial name match
cards = Card.where(name='flareon').all()
cards = Pokemon.Card.where(name: "flareon")
pokemon.card.all({ name: 'flareon' })
.on('data', card => {
    console.log(card.name)
})

<?php

$cards = Pokemon::Card()->where(['name' => 'flareon'])->all();
curl "https://api.pokemontcg.io/v1/cards?name=flareon"

GET https://api.pokemontcg.io/v1/cards?name=flareon

Get a card by doing an exact match on the name

# filter by exact name match
cards = Pokemon::Card.where(name: '"flareon"').all
# filter by exact name match
cards = Card.where(name='"flareon"').all()
cards = Pokemon.Card.where(name: "\"flareon\"")
pokemon.card.all({ name: '"flareon"' })
.on('data', card => {
    console.log(card.name)
})

<?php

$cards = Pokemon::Card()->where(['name' => '"flareon"'])->all();
curl "https://api.pokemontcg.io/v1/cards?name="flareon""

GET https://api.pokemontcg.io/v1/cards?name="flareon"

Get cards that have a weakness to fire or fighting from the set generations

# filter by weakness and set
cards = Pokemon::Card.where(weaknesses: 'fire|fighting')
                     .where(set: 'generations')
                     .all
# filter by weakness and set
cards = Card.where(weaknesses='fire|fighting') \
            .where(set='generations') \
            .all()
cards = Pokemon.Card.where(weaknesses: "fire|fighting", set: "generations")
pokemon.card.all({ weaknesses: 'fire|fighting', set: 'generations' })
.on('data', card => {
    console.log(card.name)
})

<?php

$cards = Pokemon::Card()->where([
  'weaknesses' => 'fire|fighting', 
  'set' => 'generations'
])->all();
curl "https://api.pokemontcg.io/v1/cards?weaknesses=fire|fighting&set=generations"

GET https://api.pokemontcg.io/v1/cards?weaknesses=fire|fighting&set=generations

Sets

Get All Sets

This endpoint retrieves all sets.

require 'pokemon_tcg_sdk'

# Get all Sets
sets = Pokemon::Set.all

# Filter Sets
sets = Pokemon::Set.where(standardLegal: true).all

# Get sets on a specific page / pageSize
sets = Pokemon::Set.where(page: 2).where(pageSize: 10).all
from pokemontcgsdk import Set

# Get all Sets
sets = Set.all()

# Filter Sets
sets = Set.where(standardLegal=true).all()

# Get sets on a specific page / pageSize
sets = Set.where(page=2).where(pageSize=10).all()
# Get all Sets
sets = Pokemon.Set.all

# Filter sets
sets = Pokemon.Set.where(standardLegal: true)

# Get sets on a specific page / pageSize
sets = Pokemon.Set.where(page: 2, pageSize: 10)
// Not yet supported
<?php

# Get all Sets
$sets = Pokemon::Set()->all();

# Filter Sets
$set = Pokemon::Set()->where(['standardLegal' => 'true'])->all();

# Get sets on a specific page / pageSize
$sets = Pokemon::Set()->where([
    'page'     => 2,
    'pageSize' => 10
])->all();
# Get all sets
curl "https://api.pokemontcg.io/v1/sets"

# Filter cards
curl "https://api.pokemontcg.io/v1/sets?standardLegal=true"

# Get specific page of data
curl "https://api.pokemontcg.io/v1/sets?page=2&pageSize=10"

The following JSON is what a sample request to the Sets resource looks like:

{  
  "sets":[  
    {  
      "code":"base1",
      "name":"Base",
      "series":"Base",
      "totalCards":102,
      "standardLegal":false,
      "releaseDate":"01/09/1999"
    },
    {  
      "code":"base2",
      "name":"Jungle",
      "series":"Base",
      "totalCards":64,
      "standardLegal":false,
      "releaseDate":"06/16/1999"
    }
  ]
}

HTTP Request

GET https://api.pokemontcg.io/v1/sets

Query Parameters

Each field below can be used as a query parameter. Some can be used in a comma separated list such as ?name=base,jungle.

Parameter Accepts List Description
name true The name of the set
series true The series the set belongs to
totalCards false The number of cards in the set
standardLegal false Whether or not the set is tournament legal for standard format
expandedLegal false Whether or not the set is tournament legal for expanded format

Other Fields in Response

The fields below are also part of the response (if not null), but cannot be used as query parameters/

Field Description
code The code name of the set
releaseDate The date the set was released

Get a Specific Set

This endpoint retrieves a specific set by its set code.

require 'pokemon_tcg_sdk'

set = Pokemon::Set.find('xy1')
from pokemontcgsdk import Set

set = Set.find('xy1')
set = Pokemon.Set.find("base1")
// Not yet supported
<?php

$set = Pokemon::Set()->find('base1');
curl "https://api.pokemontcg.io/v1/sets/xy1"

A sample JSON response is below:

{  
  "set":{  
    "code":"xy1",
    "name":"XY",
    "series":"XY",
    "totalCards":140,
    "standardLegal":true,
    "releaseDate":"02/05/2014"
  }
}

HTTP Request

GET https://api.pokemontcg.io/v1/sets/<code>

Card Types

Get all Types

This endpoint retrieves all card types

require 'pokemon_tcg_sdk'

types = Pokemon::Type.all
from pokemontcgsdk import Type

types = Type.all()
types = Pokemon.Type.all
<?php

$types = Pokemon::Type()->all();
curl "https://api.pokemontcg.io/v1/types"

The following is a sample JSON response:

{  
  "types":[  
    "Colorless",
    "Dark",
    "Darkness",
    "Dragon",
    "Fairy",
    "Fighting",
    "Fire",
    "Grass",
    "Lightning",
    "Metal",
    "Psychic",
    "Water"
  ]
}

HTTP Request

GET https://api.pokemontcg.io/v1/types

Get all Supertypes

This endpoint retrieves all card supertypes

require 'pokemon_tcg_sdk'

supertypes = Pokemon::Supertype.all
from pokemontcgsdk import Supertype

supertypes = Supertype.all()
supertypes = Pokemon.Supertype.all
<?php

$supertypes = Pokemon::Supertype()->all();
curl "https://api.pokemontcg.io/v1/supertypes"

The following is a sample JSON response:

{  
  "supertypes":[  
    "Pokémon",
    "Energy",
    "Trainer"
  ]
}

HTTP Request

GET https://api.pokemontcg.io/v1/supertypes

Get all Subtypes

This endpoint retrieves all card subtypes

require 'pokemon_tcg_sdk'

subtypes = Pokemon::Subtype.all
from pokemontcgsdk import Subtype

subtypes = Subtype.all()
subtypes = Pokemon.Subtype.all
<?php

$subtypes = Pokemon::Subtype()->all();
curl "https://api.pokemontcg.io/v1/subtypes"

The following is a sample JSON response:

{  
  "subtypes":[  
    "MEGA",
    "Item",
    "Level Up",
    "Supporter",
    "EX",
    "Technical Machine",
    "Rocket's Secret Machine",
    "Stadium",
    "Restored",
    "Stage 1",
    "LEGEND",
    "BREAK",
    "Pokémon Tool",
    "Stage 2",
    "Special",
    "Basic"
  ]
}

HTTP Request

GET https://api.pokemontcg.io/v1/subtypes