Skip to content

Filtering, Sorting & Pagination

Most endpoints that return arrays can have filters, sorting, and paginations informations added in the query to help you buid on them

You can add filtering to the request you are making it will check if the field you are checking contains the defined string element or number

It is constructed like so : object.key=value ex: name=pikachu

Request:

https://api.tcgdex.net/v2/en/cards?name=pikachu

Response:

[
{
"id": "basep-1",
"localId": "1",
"name": "Pikachu",
"image": "https://assets.tcgdex.net/en/base/basep/1"
},
// ...
{
"id": "xyp-XY95",
"localId": "XY95",
"name": "Pikachu",
"image": "https://assets.tcgdex.net/en/xy/xyp/XY95"
}
]

To allow a more flexible way to use the API you can add differents prefixes to the filters to change how they work.

TL:DR: the table below resume how it works

NamePrefixExampleExpected output
Laxist Equality Filter , like:name=fu, name=like:fu, name=fu*Elements containing the value
Laxist Not Equality Filternot:notlike:name=not:fuelements not containing the value
Strict Equality Filtereq:name=eq:Furretelements with the exact value
Strict Different Filterneq:name=neq:FurretElements without the exact value
Greater or Equalgte:hp=gte:50Elements with more or equal than the value
Lesser or Equallte:hp=lte:50Elements with less or equal than the value
Greater thangt:hp=gt:50Elements with more  than the value
Lesser thanlt:hp=lt:50Elements with less than the value
Is nullnull:effect=null:Elements with no value
Is not nullnotnull:effect=notnull:Elements with a value

This is the default filter when doing a request, it does a laxist find in the specified field, meaning it search if the input is a part of the searched element, also it does this in a case insensitive maner.

ex: name=abo or name=like:abo the name is composed of abo somewhere (can match Abomasnow or Pumpkaboo)

If you add an asterisc at the start and/or end, for example name=*chu, it will check with the start/end of the text like *chu is equal to Pikachu but not Pikachu on the Ball likewise fu* is equal to Furret but not Stufful

You can reverse the previous filter by change the prefix to not: or notlike: it will find things that are not equal to it in the same way as above.

Adding a secondary equal = to the request will search for the exact value instead of the default laxist matching

?name=eq:abo

do a strict equality check and remove the ones that match.

ex: name=neq:abo the name MUST NOT be equal to abo

for numbers only

Allow you to get values that are greater or equal to the input

ex: hp=gte:10

for numbers only

Allow you to get values that are lesser or equal to the input

hp=lte:10

for numbers only

Allow you to get values that are greater or equal to the input

ex: hp=gt:10

for numbers only

Allow you to get values that are lesser or equal to the input

hp=lt:10

ex: effect=null: the card has no effect

make sur the : is set !

ex: effect=notnull: the card has an effect

make sur the : is set !

for some fields you can add multiple values to compare against.

ex: name=eq:Furret|Pikachu, it will match both Pikachu and Furret

Sorting is done by default in the API depending on the array returned releaseDate > localId > id

You can override the default sorting algorithm by adding parameters to your request :

query parameterdefault valuepossible valuesdescription
sort:fieldreleaseDate > localId > idkey of the objectchange the field that is used to sort (MUST be the name of one of the field of the object)
sort:orderASCASC, DESCchange the ordering done on the field

Request:

https://api.tcgdex.net/v2/en/sets?sort:field=name&sort:order=DESC

Response:

[
{
"id": "sma",
"name": "Yellow A Alternate",
"symbol": "https://assets.tcgdex.net/univ/sm/sma/symbol",
"cardCount": {
"total": 94,
"official": 94
}
},
// ...
{
"id": "sv03.5",
"name": "151",
"logo": "https://assets.tcgdex.net/en/sv/sv03.5/logo",
"symbol": "https://assets.tcgdex.net/univ/sv/sv03.5/symbol",
"cardCount": {
"total": 207,
"official": 165
}
}
]

Pagination is not done automatically to speed requests on your end.

you can still add it back by using the following query parameters:

query parameterdefault valuepossible valuesdescription
pagination:page1NumberIndicate on which page you are at
pagination:itemsPerPage100 (when pagination:page is set)Numberindicate the number of items displayed on each pages

Request:

https://api.tcgdex.net/v2/en/sets?pagination:page=3&pagination:itemsPerPage=2

Response:

[
{
"id": "base3",
"name": "Fossil",
"logo": "https://assets.tcgdex.net/en/base/base3/logo",
"symbol": "https://assets.tcgdex.net/univ/base/base3/symbol",
"cardCount": {
"total": 62,
"official": 62
}
},
{
"id": "jumbo",
"name": "Jumbo cards",
"cardCount": {
"total": 160,
"official": 160
}
}
]