Collectibles – Text Search

QuickstartTaxonomyBlog

To use the Ximilar API, register at Ximilar App to get your API token. This service is available in paid plans (see Pricing). To access it, please contact us at tech@ximilar.com.

This page describes the Collectibles Text Search API, which lets you search a database of collectible items using text queries. You can also filter by attributes such as grading company, publisher, or year.

Endpoints

Currently supported endpoints:

https://api.ximilar.com/collectibles/text/v2/tcg/catalog     → Search catalog of trading cards
POST/text/v2/tcg/catalog

TCG Catalog Text Search

Taxonomy

This endpoint lets you search our catalog of collectible trading cards using text queries like card names, sets, or series, or any other textual information related to collectibles.

It supports Pokémon, Yu-Gi-Oh!, Magic: The Gathering, One Piece, Lorcana, and many more – (see full taxonomy).

Required attributes

  • Name
    query_record
    Type
    dict
    Description

    A record containing the search query. Must include a _text_data field with the search text.

Optional attributes

  • Name
    page
    Type
    integer
    Description

    Page number for pagination (starts from 1).

  • Name
    size
    Type
    integer
    Default
    Default:10
    Max
    Maximum:20
    Description

    Number of results per page.

  • Name
    k
    Type
    integer
    Description

    Number of top results to consider for relevance ranking.

  • Name
    filter
    Type
    str
    Description

    String filter. Supported operators include: =, !=, >, >=, <, <=, EXISTS. See available filter fields below.

Returns

HTTP error code 2XX, if the method was OK, and other HTTP error code, if the method failed. The response body is a JSON object with the following fields:

  • Name
    answer_records
    Type
    array
    Description

    An array of collectible items matching the search query, each containing detailed information about the item including name, set, series, rarity, and other attributes.

  • Name
    answer_count
    Type
    integer
    Description

    Total number of items matching the search query across all pages.

  • Name
    page
    Type
    integer
    Description

    Current page number.

  • Name
    totalPages
    Type
    integer
    Description

    Total number of pages.

Request

POST
/text/v2/tcg/catalog
curl --location 'https://api.ximilar.com/collectibles/text/v2/tcg/catalog' \
--header 'Content-Type: application/json' \
--header 'Authorization: Token __API_TOKEN__' \
--data '{
  "query_record": {
    "_text_data": "Pikachu ex 247 Surging Sparks"
  },
  "page": 1,
  "size": 10,
  "filter": "lang = 'en'"
}'

Response

{
  "answer_count": 571,
  "answer_records": [
    {
      "Subcategory": "Pokemon",
      "_id": "eb863290-c435-4b48-9ea5-ae3dc73fec4e",
      "card_number": "247",
      "lang": "en",
      "name": "Pikachu ex",
      "rarity": "Hyper Rare",
      "series": "Scarlet & Violet",
      "set": "Surging Sparks",
      "set_code": "SSP",
      "year": 2024
    },
    {
      "Subcategory": "Pokemon",
      "_id": "bc8f12eb-894e-46bc-ae81-48f2aff424fa",
      "card_number": "057",
      "lang": "en",
      "name": "Pikachu ex",
      "rarity": "Double Rare",
      "series": "Scarlet & Violet",
      "set": "Surging Sparks",
      "set_code": "SSP",
      "year": 2024
    },
    {
      "Subcategory": "Pokemon",
      "_id": "2bc0df4a-3d2c-47fa-a3d7-688add47a4fa",
      "card_number": "179",
      "lang": "en",
      "name": "Pikachu ex",
      "rarity": "Hyper Rare",
      "series": "Scarlet & Violet Series",
      "set": "Prismatic Evolutions",
      "set_code": "PRE",
      "year": 2025
    },
    ...
  ],
  "page": 1,
  "query_records": [
    "Pikachu ex 247 Surging Sparks"
  ],
  "size": 10,
  "statistics": {
    "OperationTime": 718
  },
  "totalPages": 58
}

Available Filter Fields

You can filter the results using the filter parameter with the following fields:

  • Subcategory: e.g., Pokemon, Magic The Gathering
  • lang: language code (jp, en, zh_TW, zh_CN)
  • set_code: set code of the game (string)
  • year: year of release (numerical value)
  • card_number: card number (string)

Filter Examples

"Subcategory = 'Magic The Gathering'"
"set_code = 'BW1'"
"lang = 'jp'"
"card_number = '247'"
"year < 2020"

The whole request with filter:

cURL

  curl --location 'https://api.ximilar.com/collectibles/text/v2/tcg/catalog' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Token __API_TOKEN__' \
  --data '{
    "query_record": {
      "_text_data": "Snow"
    },
    "filter": "Subcategory = 'Magic The Gathering'"
    "page": 1,
    "size": 10
  }'

Was this page helpful?