Skip to main content

Search cards

Search for one or many cards given a search query.

HTTP Request#


URL Parameters#


Body Parameters#


Query Parameters#

All query parameters are optional.

ParameterDescriptionDefault Value
qThe search query. Examples can be found below.
pageThe page of data to access.1
pageSizeThe maximum amount of cards to return.250 (max of 250)
orderByThe field(s) to order the results by. Examples can be found below.
selectA comma delimited list of fields to return in the response (ex. ?select=id,name). By default, all fields are returned if this query parameter is not used.

To perform search queries, you use the q parameter. The search syntax is a very familiar Lucene like syntax.

Keyword matching:#

Search for all cards that have "charizard" in the name field.


Search for the phrase "venusaur v" in the name field.

name:"venusaur v"

Search for "charizard" in the name field AND the type "mega" in the subtypes field.

name:charizard subtypes:mega

Search for "charizard" in the name field AND either the subtypes of "mega" or "vmax."

name:charizard (subtypes:mega OR subtypes:vmax)

Search for all "mega" subtypes, but NOT water types.

subtypes:mega -types:water

Wildcard Matching#

Search for any card that starts with "char" in the name field.


Search for any card that starts with "char" in the name and ends with "der."


Exact Matching#

Search for any card named "charizard." That is, no other word except for "charizard" appears in the name field.


Range Searches#

Some fields support searching on a range. This includes fields with numerical data like hp and nationalPokedexNumbers.

Search for only cards that feature the original 151 pokemon.

nationalPokedexNumbers:[1 TO 151]

Using square brackets [ and ] means to do an inclusive range search, while using curly braces { and } means exclusive.

Search for cards with a max HP up to 100.

hp:[* TO 100]

Search for cards with any HP greater than or equal to 150.

hp:[150 TO *]

Search on nested fields#

To search nested fields, use a period . as a separator. For example, to filter by the set id:

Or to filter on cards where they have an attack named "Spelunk":

Find cards that are banned in Standard.


Every field in the response is searchable.

Ordering Data#

You can also order data using the orderBy query parameter.

Order all cards from Sun & Moon by their number.


Order all cards from Sun & Moon by their name (ascending) and then their number (descending)


Code Samples#

# Get all cards (will take awhile, automatically pages through data)
cards = Card.all()
# Get a single page of cards
cards = Card.where(page=1, pageSize=250)
# Filter cards via query parameters
cards = Card.where(q=' subtypes:mega')
# Order by release date (descending)
cards = Card.where(q='subtypes:mega', orderBy='-set.releaseDate')

Sample Response#

"data": [
"id": "g1-1",
"name": "Venusaur-EX",
"supertype": "Pokémon",
"subtypes": [
"hp": "180",
"types": [
"evolvesTo": [
"M Venusaur-EX"
"rules": [
"Pokémon-EX rule: When a Pokémon-EX has been Knocked Out, your opponent takes 2 Prize cards."
"attacks": [
"name": "Frog Hop",
"cost": [
"convertedEnergyCost": 3,
"damage": "40+",
"text": "Flip a coin. If heads, this attack does 40 more damage."
"name": "Poison Impact",
"cost": [
"convertedEnergyCost": 4,
"damage": "80",
"text": "Your opponent's Active Pokémon is now Asleep and Poisoned."
"weaknesses": [
"type": "Fire",
"value": "×2"
"retreatCost": [
"convertedRetreatCost": 4,
"set": {
"id": "g1",
"name": "Generations",
"series": "XY",
"printedTotal": 115,
"total": 115,
"legalities": {
"unlimited": "Legal",
"expanded": "Legal"
"ptcgoCode": "GEN",
"releaseDate": "2016/02/22",
"updatedAt": "2020/08/14 09:35:00",
"images": {
"symbol": "",
"logo": ""
"number": "1",
"artist": "Eske Yoshinob",
"rarity": "Rare Holo EX",
"nationalPokedexNumbers": [
"legalities": {
"unlimited": "Legal",
"expanded": "Legal"
"images": {
"small": "",
"large": ""
"tcgplayer": {
"url": "",
"updatedAt": "2021/07/15",
"prices": {
"holofoil": {
"low": 2.44,
"mid": 5.4,
"high": 16.99,
"market": 5.38,
"directLow": 6.1
"page": 1,
"pageSize": 250,
"count": 117,
"totalCount": 117