Skip to content

Collectibles Recognition

PRICING DEMO TAXONOMY

This page describes API of Collectibles Recognition service for images. This service provides basic analysing of photos with collectible items. The API method first detect all collectible items on a photo recognizes their types (Stamps, Coins, Banknotes, Comics, Cards, Slab Label).

If a trading card is detected on the image then the card is further analyzed to recognize the card Category (Sport Card or Trading Card Game), Subcategory (Baseball, Football, Pokemon, Magic The Gathering, ...), Alphabet/Language, Holo/Foil, etc.

For several specific games like Pokemon, Magic The Gathering, Yugioh! (and others) this AI service is able to identify the card (Set, Set code, Series, Card number, Full Name of the card, Year of release). For TCG identification please use /v2/card_id endpoint.

The API follows the general rules of Ximilar API as described in Section First steps.

Collectibles Recognition is available only in Business and Professional pricing plans..

More Detailed Analysis/Visual Search

If you are looking for a more detailed analysis of collector items, e.g.:

  • you are missing a specific feature and would like to add it to this endpoint,
  • you want to automatically read text/name from banknote/coin/trading cards/etc.,
  • you want to do automatic visual inspection and grading of collector items,
  • you want visual search or identification of the stamp, comics, posters, vinyl covers, cards, etc.,

then please contact us at care@ximilar.com and we can create a customized soluton for your business.

Try the service in Ximilar App or Demo

In order to get access to the Collectibles Recognition service, please register at https://app.ximilar.com. In the app pick "Ready-To-Use Image Recognition" on the main dashboard and then Collectibles Recognition. You must have at least business plan to access this service. A public demo is to be launched soon at demo.ximilar.com.

This service API has several api endpoints running at URLs:

https://api.ximilar.com/collectibles/v2/process
https://api.ximilar.com/collectibles/v2/analyze
https://api.ximilar.com/collectibles/v2/card_id
https://api.ximilar.com/collectibles/v2/card_ocr_id
https://api.ximilar.com/collectibles/v2/slab_id
https://api.ximilar.com/collectibles/v2/detect

Collectibles Recognition /v2/process

Given a list of image records, this method returns and objects of collector's items for each of them. The result images with _objects (with _tags), which represents location of the detected items and if the item is in graded sleeve/package.

Parameters:

  • records: list of photos to analyze
    • must contain either of _url or _base64 field - see section image data for details
    • maximum batch of records is 10

$ curl https://api.ximilar.com/collectibles/v2/process -H "Content-Type: application/json" -H "Authorization: Token __API_TOKEN__" -d '{
    "records": [
        { "_url": "https://images.ximilar.com/examples/cards/jordan.jpeg"}
    ]
}'

Returns:

  • HTTP error code 2XX, if the method was OK and other HTTP error code, if the method failed.
  • Body of the response is a JSON object (map) with the following fields:
    • status - a JSON map with a status of the method processing. It contains these subfields:
      • code - a numeric code of the operation status; it follows the concept of HTTP status codes (2XX, 4XX). Specific codes are described for each type of answer (or operation) (see below).
      • text - a text describing the status code
      • error_description - in case of the processing ended with error (codes 4XX), this field contains a detailed description of the error; this might include Java stack traces.
    • Example of statuses that can be returned:
      "status": {"code": 200, "text": "OK"}
      "status": {"code": 402, "text": "aborted by error", error_description="..."}
      "status": {"code": 500, "text": "unknown error", "error_description": "..."}
    • statistics - a map of various statistics about the processing. The only statistic included every time is
      • processing time - time of actual processing of the query [in seconds]
    • records - JSON array with the input records, each record enriched by fields, _objects with _tags
CLICK TO SHOW JSON RESULT

{
    "records": [
        {
            "_url": "https://images.ximilar.com/examples/cards/jordan.jpeg",
            "_status": {
                "code": 200,
                "text": "OK",
                "request_id": "b528b51b-435f-480c-bb17-a2f597340d85"
            },
            "_id": "97480960-be47-43c2-b10b-49a3052d8d70",
            "_width": 954,
            "_height": 1516,
            "_objects": [
                {
                    "name": "Card",
                    "id": "76fa9ec3-e0d9-408a-b582-55a1cd6712e0",
                    "bound_box": [
                        83,
                        343,
                        862,
                        1445
                    ],
                    "prob": 0.9307230114936829,
                    "area": 0.5935693621634778,
                    "Top Category": "Card",
                    "_tags": {
                        "Category": [
                            {
                                "prob": 0.96291,
                                "name": "Card/Sport Card",
                                "id": "a5634621-4a37-4b37-aa3d-720b2d6b35ec"
                            }
                        ],
                        "Foil/Holo": [
                            {
                                "prob": 0.95268,
                                "name": "no_foil",
                                "id": "78b14f77-192d-45e4-919e-b7f403759e07"
                            }
                        ],
                        "Subcategory": [
                            {
                                "prob": 0.98437,
                                "name": "basketball",
                                "id": "b8ccec14-4d8a-4b26-83a2-6cc690845ba4"
                            }
                        ],
                        "Side": [
                            {
                                "prob": 0.96881,
                                "name": "front",
                                "id": "651c8141-2b18-479b-a8b1-b959bc34b729"
                            }
                        ],
                        "Autograph": [
                            {
                                "prob": 0.94523,
                                "name": "not autograph",
                                "id": "5c1bb98b-cd69-42c9-ab2a-75e480ffa2b0"
                            }
                        ],
                        "Top Category": [
                            {
                                "id": "8ae26c4a-ae79-4c01-9b54-ac4e2b42e914",
                                "name": "Card",
                                "prob": 1.0
                            }
                        ]
                    },
                    "_tags_simple": [
                        "not autograph",
                        "front",
                        "Card/Sport Card",
                        "basketball",
                        "no_foil",
                        "Card"
                    ],
                    "Category": "Card/Sport Card"
                }
            ]
        }
    ],
    "status": {
        "code": 200,
        "text": "OK",
        "request_id": "b528b51b-435f-480c-bb17-a2f597340d85",
        "proc_id": "de2b192f-5e9b-4998-8152-f6b9008a1bc3"
    },
    "statistics": {
        "processing time": 13.916424751281738
    }
}

Card Identification /v2/card_id

Given a list of image records, this method returns and identification for largest card detected on image. The identification is working right now for Pokemon, Yugioh!, Magic The Gathering, Flesh and Blood, OnePiece, Lorcana and MetaZoo games. It also detects the slab label and tries do recognize the grading company.

Card identification will return best match against english language card, however you can get better insight about alphabet via _tags.Alphabet (International/Latin, Japanese, Korean, Chinese, Russian, ...) field. If you need to distinguish international/latin alphabet language (English, German, Portuguese, Spanish, ...) send lang: true and in returned _ocr field you will find a proper language identification. For some cards we are able to return also links to tcgplayer.com, pkmncards.com, ...

Parameters:

  • records: list of photos to analyze
    • must contain either of _url or _base64 field - see section image data for details
  • lang: set true if you need to distinguish language of trading card in latin alphabet, otherwise take the language information from _tags
  • slab_id: if set to true, then the slab identification will be done via OCR and AI, default False. This will analyse only one slab label on the image and also count additional API credits according to /v2/slab_id.

$ curl https://api.ximilar.com/collectibles/v2/card_id -H "Content-Type: application/json" -H "Authorization: Token __API_TOKEN__" -d '{
    "records": [
        { "_url": "__PATH_TO_IMAGE_URL__"}
    ], "lang": false, "slab_id": false
}'

Returns:

  • HTTP error code 2XX, if the method was OK and other HTTP error code, if the method failed.
  • Body of the response is a JSON object (map) with the following fields:
    • status - a JSON map with a status of the method processing. It contains these subfields:
      • code - a numeric code of the operation status; it follows the concept of HTTP status codes (2XX, 4XX). Specific codes are described for each type of answer (or operation) (see below).
      • text - a text describing the status code
      • error_description - in case of the processing ended with error (codes 4XX), this field contains a detailed description of the error; this might include Java stack traces.
    • records - JSON array with the input records, each record enriched by field _objects (of type Slab Label or Card).
      • _objects (Card) contains _tags, _tags_simple and _identification. The _identification contains best_match and alternatives fields. The identification returns info like name, full_name, year, set, ...
CLICK TO SHOW JSON RESULT

{
    "records": [
        {
            "_url": "__URL_LINK__",
            "_status": {
                "code": 200,
                "text": "OK",
                "request_id": "5755e5ae-02e2-4f35-ac66-7a919beeb041"
            },
            "_id": "c8dc0a1e-853e-4267-b212-814fe813d34d",
            "_objects": [
                {
                    "name": "Card",
                    "id": "76fa9ec3-e0d9-408a-b582-55a1cd6712e0",
                    "bound_box": [
                        38,
                        172,
                        340,
                        606
                    ],
                    "prob": 0.9829951524734497,
                    "area": 0.5112833575839376,
                    "Top Category": [
                        {
                            "id": "8ae26c4a-ae79-4c01-9b54-ac4e2b42e914",
                            "name": "Card",
                            "prob": 1.0
                        }
                    ],
                    "_tags": {
                        "Category": [
                            {
                                "prob": 0.99732,
                                "name": "Card/Trading Card Game",
                                "id": "d44efa56-09c3-4829-b3e7-226fe9cfe798"
                            }
                        ],
                        "Autograph": [
                            {
                                "prob": 0.9712,
                                "name": "not autograph",
                                "id": "5c1bb98b-cd69-42c9-ab2a-75e480ffa2b0"
                            }
                        ],
                        "Subcategory": [
                            {
                                "prob": 0.99109,
                                "name": "Pokemon",
                                "id": "fdbb3942-b7e0-476a-8f13-af77aedd13e6"
                            }
                        ],
                        "Foil/Holo": [
                            {
                                "prob": 0.95268,
                                "name": "no_foil",
                                "id": "78b14f77-192d-45e4-919e-b7f403759e07"
                            }
                        ],
                        "Alphabet": [
                            {
                                "prob": 0.93945,
                                "name": "latin",
                                "id": "f0339837-aa0b-414f-acb8-d47d6ef3b7fa"
                            }
                        ]
                    },
                    "_tags_simple": [
                        "Card/Trading Card Game",
                        "Pokemon",
                        "latin",
                        "no_foil",
                        "not autograph"
                    ],
                    "_identification": {
                        "best_match": {
                            "name": "Dark Gyarados",
                            "full_name": "Dark Gyarados Team Rocket (RO) #8",
                            "set": "Team Rocket",
                            "set_code": "RO",
                            "series": "Classic",
                            "card_number": "8",
                            "year": 2000,
                            "sources": {
                                "pkmncards.com": "__URL_LINK__",
                                "tcgplayer.com": "__URL_LINK__"
                            }
                        },
                        "alternatives": [
                            {
                                "name": "Dark Gyarados",
                                "full_name": "Dark Gyarados Celebrations (CEL) #8",
                                "set": "Celebrations",
                                "set_code": "CEL",
                                "series": "Sword & Shield",
                                "set_series_code": "Ann25thR",
                                "card_number": "8",
                                "year": 2021,
                                "subcategory": "Pokemon",
                                "sources": {
                                    "pkmncards.com": "__URL_LINK__",
                                    "tcgplayer.com": "__URL_LINK__",
                                    "pokemon.com": "__URL_LINK__"
                                }
                            },
                            {
                                "name": "Dark Gyarados",
                                "full_name": "Dark Gyarados Team Rocket (RO) #25",
                                "set": "Team Rocket",
                                "set_code": "RO",
                                "series": "Classic",
                                "card_number": "25",
                                "year": 2000,
                                "sources": {
                                    "pkmncards.com": "__URL_LINK__",
                                    "tcgplayer.com": "__URL_LINK__"
                                }
                            },
                            {
                                "name": "Hypno",
                                "full_name": "Hypno Furious Fists (FFI) #36",
                                "set": "Furious Fists",
                                "set_code": "FFI",
                                "series": "XY",
                                "set_series_code": "XY3",
                                "card_number": "36",
                                "year": 2014,
                                "sources": {
                                    "pkmncards.com": "__URL_LINK__",
                                    "tcgplayer.com": "__URL_LINK__",
                                    "pokemon.com": "__URL_LINK__"
                                }
                            },
                            {
                                "name": "Ledian",
                                "full_name": "Ledian Neo Genesis (N1) #39",
                                "set": "Neo Genesis",
                                "set_code": "N1",
                                "series": "Neo",
                                "card_number": "39",
                                "year": 2000,
                                "sources": {
                                    "pkmncards.com": "__URL_LINK__",
                                    "tcgplayer.com": "__URL_LINK__"
                                }
                            }
                        ]
                    }
                },
                {
                    "name": "Slab Label",
                    "id": "9242aeda-1a35-4c93-b75c-958af91e63a7",
                    "bound_box": [
                        28,
                        22,
                        363,
                        127
                    ],
                    "prob": 0.8884860277175903,
                    "area": 0.13721421020397814,
                    "_tags": {
                        "Category": [
                            {
                                "prob": 0.97916,
                                "name": "PSA",
                                "id": "2f4545e7-08e4-492b-ab4e-02a409d58988"
                            }
                        ]
                    },
                    "_tags_simple": [
                        "PSA"
                    ]
                }
            ],
            "_width": 389,
            "_height": 659
        }
    ],
    "status": {
        "code": 200,
        "text": "OK",
        "proc_id": "d61cfa1e-e923-4777-9435-b16b23d43c50"
    },
    "statistics": {
        "processing time": 1.6086559295654297
    }
}

Card OCR & Identification /v2/card_ocr_id

Given a list of image records, this method returns and identification for largest card detected (and largest slab label if present) on image. The identification is suitable for sport cards and slab labels (PSA, BECKETT, ...). The identification is done by mining of information from ocr text via AI model (and that is why is sometimes not exactly precise).

Partially correct identification (missing year) for card can look like this:

{
    "name": "ERLING BRAUT HAALAND",
    "year": null,
    "subcategory": "soccer"
}

Correct identification for graded slab label can look like this:

{
    "name": "2019 FINEST UEFA ERLING BRAUT HAALAND",
    "grade": "10",
    "year": "2019",
    "certificate_number": "51974133"
}

Parameters:

  • records: list of photos to analyze
    • must contain either of _url or _base64 field - see section image data for details

$ curl https://api.ximilar.com/collectibles/v2/card_ocr_id -H "Content-Type: application/json" -H "Authorization: Token __API_TOKEN__" -d '{
    "records": [
        { "_url": "__URL_PATH__"}
    ]
}'

Returns:

  • HTTP error code 2XX, if the method was OK and other HTTP error code, if the method failed.
  • Body of the response is a JSON object (map) with the following fields:
    • status - a JSON map with a status of the method processing. It contains these subfields:
      • code - a numeric code of the operation status; it follows the concept of HTTP status codes (2XX, 4XX). Specific codes are described for each type of answer (or operation) (see below).
      • text - a text describing the status code
      • error_description - in case of the processing ended with error (codes 4XX), this field contains a detailed description of the error; this might include Java stack traces.
    • records - JSON array with the input records, each record enriched by field _objects (of type Slab Label or Card).
      • _objects (Card, Slab Label) contains _ocr, _tags, _tags_simple and _identification. The _identification contains best_match field. The identification returns info like name, full_name, year, grade, certificate_number...
CLICK TO SHOW JSON RESULT

{
    "records": [
        {
            "_url": "__URL_PATH__",
            "_status": {
                "code": 200,
                "text": "OK",
                "request_id": "37d5842e-a6f1-443f-a2c4-6cafa5ed604b"
            },
            "_id": "8c26e90a-627e-444e-a3a6-92845f581858",
            "_objects": [
                {
                    "name": "Card",
                    "id": "76fa9ec3-e0d9-408a-b582-55a1cd6712e0",
                    "bound_box": [
                        213,
                        403,
                        872,
                        1273
                    ],
                    "prob": 0.978815495967865,
                    "area": 0.36865354938271605,
                    "Top Category": [
                        {
                            "id": "8ae26c4a-ae79-4c01-9b54-ac4e2b42e914",
                            "name": "Card",
                            "prob": 1.0
                        }
                    ],
                    "_tags": {
                        "Category": [
                            {
                                "prob": 0.99694,
                                "name": "Card/Sport Card",
                                "id": "a5634621-4a37-4b37-aa3d-720b2d6b35ec"
                            }
                        ],
                        "Side": [
                            {
                                "prob": 0.98772,
                                "name": "front",
                                "id": "651c8141-2b18-479b-a8b1-b959bc34b729"
                            }
                        ],
                        "Subcategory": [
                            {
                                "prob": 0.96789,
                                "name": "soccer",
                                "id": "3275f70c-10f4-4807-89ca-f166e8c3aa7c"
                            }
                        ],
                        "Autograph": [
                            {
                                "prob": 0.97277,
                                "name": "not autograph",
                                "id": "5c1bb98b-cd69-42c9-ab2a-75e480ffa2b0"
                            }
                        ]
                    },
                    "_tags_simple": [
                        "Card/Sport Card",
                        "front",
                        "soccer",
                        "not autograph"
                    ],
                    "_ocr": {
                        "texts": [
                            {
                                "polygon": [
                                    [
                                        61.0,
                                        60.0
                                    ],
                                    [
                                        159.0,
                                        55.0
                                    ],
                                    [
                                        160.0,
                                        76.0
                                    ],
                                    [
                                        61.0,
                                        81.0
                                    ]
                                ],
                                "text": "Tirest",
                                "prob": 0.8078048825263977
                            },
                            {
                                "polygon": [
                                    [
                                        519.0,
                                        97.0
                                    ],
                                    [
                                        557.0,
                                        97.0
                                    ],
                                    [
                                        557.0,
                                        111.0
                                    ],
                                    [
                                        519.0,
                                        111.0
                                    ]
                                ],
                                "text": "SEFA",
                                "prob": 0.7368016839027405
                            },
                            {
                                "polygon": [
                                    [
                                        481.0,
                                        113.0
                                    ],
                                    [
                                        597.0,
                                        111.0
                                    ],
                                    [
                                        597.0,
                                        129.0
                                    ],
                                    [
                                        482.0,
                                        131.0
                                    ]
                                ],
                                "text": "CHAMPIONS",
                                "prob": 0.9519932866096497
                            },
                            {
                                "polygon": [
                                    [
                                        508.0,
                                        127.0
                                    ],
                                    [
                                        573.0,
                                        129.0
                                    ],
                                    [
                                        572.0,
                                        146.0
                                    ],
                                    [
                                        508.0,
                                        144.0
                                    ]
                                ],
                                "text": "LEAGUE,",
                                "prob": 0.8668462634086609
                            },
                            {
                                "polygon": [
                                    [
                                        207.0,
                                        300.0
                                    ],
                                    [
                                        372.0,
                                        307.0
                                    ],
                                    [
                                        370.0,
                                        363.0
                                    ],
                                    [
                                        205.0,
                                        356.0
                                    ]
                                ],
                                "text": "Red Bul",
                                "prob": 0.9309224486351013
                            },
                            {
                                "polygon": [
                                    [
                                        61.0,
                                        712.0
                                    ],
                                    [
                                        250.0,
                                        684.0
                                    ],
                                    [
                                        254.0,
                                        719.0
                                    ],
                                    [
                                        66.0,
                                        747.0
                                    ]
                                ],
                                "text": "ERLING BRAUT",
                                "prob": 0.9668567180633545
                            },
                            {
                                "polygon": [
                                    [
                                        186.0,
                                        753.0
                                    ],
                                    [
                                        370.0,
                                        730.0
                                    ],
                                    [
                                        375.0,
                                        773.0
                                    ],
                                    [
                                        191.0,
                                        795.0
                                    ]
                                ],
                                "text": "HAALAND",
                                "prob": 0.9960637092590332
                            },
                            {
                                "polygon": [
                                    [
                                        330.0,
                                        786.0
                                    ],
                                    [
                                        471.0,
                                        766.0
                                    ],
                                    [
                                        474.0,
                                        788.0
                                    ],
                                    [
                                        333.0,
                                        807.0
                                    ]
                                ],
                                "text": "FC SALZBURG",
                                "prob": 0.9561893343925476
                            }
                        ],
                        "full_text": "Tirest SEFA CHAMPIONS LEAGUE, Red Bul ERLING BRAUT HAALAND FC SALZBURG ",
                        "lang_name": "german",
                        "lang": "de"
                    },
                    "_identification": {
                        "best_match": {
                            "name": "ERLING BRAUT HAALAND",
                            "year": null,
                            "subcategory": "soccer"
                        }
                    }
                },
                {
                    "name": "Slab Label",
                    "id": "9242aeda-1a35-4c93-b75c-958af91e63a7",
                    "bound_box": [
                        205,
                        108,
                        868,
                        309
                    ],
                    "prob": 0.7645022869110107,
                    "area": 0.0856886574074074,
                    "_tags": {
                        "Category": [
                            {
                                "prob": 0.97388,
                                "name": "PSA",
                                "id": "2f4545e7-08e4-492b-ab4e-02a409d58988"
                            }
                        ]
                    },
                    "_tags_simple": [
                        "PSA"
                    ],
                    "_ocr": {
                        "texts": [
                            {
                                "polygon": [
                                    [
                                        555.0,
                                        48.0
                                    ],
                                    [
                                        614.0,
                                        48.0
                                    ],
                                    [
                                        614.0,
                                        75.0
                                    ],
                                    [
                                        555.0,
                                        75.0
                                    ]
                                ],
                                "text": "#91",
                                "prob": 0.9994840025901794
                            },
                            {
                                "polygon": [
                                    [
                                        42.0,
                                        55.0
                                    ],
                                    [
                                        306.0,
                                        50.0
                                    ],
                                    [
                                        306.0,
                                        75.0
                                    ],
                                    [
                                        43.0,
                                        80.0
                                    ]
                                ],
                                "text": "2019 FINESTUCL",
                                "prob": 0.9491297006607056
                            },
                            {
                                "polygon": [
                                    [
                                        41.0,
                                        87.0
                                    ],
                                    [
                                        435.0,
                                        82.0
                                    ],
                                    [
                                        435.0,
                                        106.0
                                    ],
                                    [
                                        42.0,
                                        111.0
                                    ]
                                ],
                                "text": "ERLING BRAUT HAALAND",
                                "prob": 0.9451332092285156
                            },
                            {
                                "polygon": [
                                    [
                                        488.0,
                                        81.0
                                    ],
                                    [
                                        617.0,
                                        81.0
                                    ],
                                    [
                                        617.0,
                                        106.0
                                    ],
                                    [
                                        488.0,
                                        106.0
                                    ]
                                ],
                                "text": "GEMMT",
                                "prob": 0.9794451594352722
                            },
                            {
                                "polygon": [
                                    [
                                        578.0,
                                        111.0
                                    ],
                                    [
                                        620.0,
                                        111.0
                                    ],
                                    [
                                        620.0,
                                        140.0
                                    ],
                                    [
                                        578.0,
                                        140.0
                                    ]
                                ],
                                "text": "10",
                                "prob": 0.999181866645813
                            },
                            {
                                "polygon": [
                                    [
                                        459.0,
                                        149.0
                                    ],
                                    [
                                        617.0,
                                        146.0
                                    ],
                                    [
                                        618.0,
                                        173.0
                                    ],
                                    [
                                        459.0,
                                        175.0
                                    ]
                                ],
                                "text": "51974133",
                                "prob": 0.999428927898407
                            }
                        ],
                        "full_text": "#91 2019 FINESTUCL ERLING BRAUT HAALAND GEMMT 10 51974133 ",
                        "lang_name": "german",
                        "lang": "de"
                    },
                    "_identification": {
                        "best_match": {
                            "name": "2019 FINEST UEFA ERLING BRAUT HAALAND",
                            "grade": "10",
                            "year": "2019",
                            "certificate_number": "51974133"
                        }
                    }
                }
            ]
        }
    ],
    "statistics": {
        "processing time": 6.20737099647522
    },
    "status": {
        "code": 200,
        "text": "OK",
        "request_id": "37d5842e-a6f1-443f-a2c4-6cafa5ed604b",
        "proc_id": "189995ef-c1e0-4799-a35e-ad32f4730c81"
    }
}

Collectibles Complex Analysis /v2/analyze

Given a list of image records, this method returns and a complex analysis for collectibles. It is combination of /v2/process, /v2/card_id and /v2/card_ocr_id endpoints. For largest card detected (and largest slab label if present) it also tries to do _ocr analysis and identification of card.

Parameters:

  • records: list of photos to analyze
    • must contain either of _url or _base64 field - see section image data for details

$ curl https://api.ximilar.com/collectibles/v2/analyze -H "Content-Type: application/json" -H "Authorization: Token __API_TOKEN__" -d '{
    "records": [
        { "_url": "__URL_PATH__"}
    ]
}'

Returns:

  • HTTP error code 2XX, if the method was OK and other HTTP error code, if the method failed.
  • Body of the response is a JSON object (map) with the following fields:
    • status - a JSON map with a status of the method processing. It contains these subfields:
      • code - a numeric code of the operation status; it follows the concept of HTTP status codes (2XX, 4XX). Specific codes are described for each type of answer (or operation) (see below).
      • text - a text describing the status code
      • error_description - in case of the processing ended with error (codes 4XX), this field contains a detailed description of the error; this might include Java stack traces.
    • records - JSON array with the input records, each record enriched by field _objects (of type Slab Label or Card).
      • _objects the specific objects (Card, Slab Label) contains _tags, _tags_simple, _ocr and _identification.
CLICK TO SHOW JSON RESULT

{
    "records": [
        {
            "_url": "__PATH_TO_URL__",
            "_status": {
                "code": 200,
                "text": "OK",
                "request_id": "0373f16e-b601-43a2-8e94-6241bb54f502"
            },
            "_id": "b828fd25-82b0-42ba-b4c5-c083bb3ec865",
            "_objects": [
                {
                    "name": "Card",
                    "id": "76fa9ec3-e0d9-408a-b582-55a1cd6712e0",
                    "bound_box": [
                        232,
                        395,
                        839,
                        1257
                    ],
                    "prob": 0.975487232208252,
                    "area": 0.3364416152263375,
                    "Top Category": [
                        {
                            "id": "8ae26c4a-ae79-4c01-9b54-ac4e2b42e914",
                            "name": "Card",
                            "prob": 1.0
                        }
                    ],
                    "_tags": {
                        "Category": [
                            {
                                "prob": 0.99689,
                                "name": "Card/Sport Card",
                                "id": "a5634621-4a37-4b37-aa3d-720b2d6b35ec"
                            }
                        ],
                        "Side": [
                            {
                                "prob": 0.98539,
                                "name": "front",
                                "id": "651c8141-2b18-479b-a8b1-b959bc34b729"
                            }
                        ],
                        "Subcategory": [
                            {
                                "prob": 0.9753,
                                "name": "soccer",
                                "id": "3275f70c-10f4-4807-89ca-f166e8c3aa7c"
                            }
                        ],
                        "Autograph": [
                            {
                                "prob": 0.97245,
                                "name": "not autograph",
                                "id": "5c1bb98b-cd69-42c9-ab2a-75e480ffa2b0"
                            }
                        ]
                    },
                    "_tags_simple": [
                        "Card/Sport Card",
                        "front",
                        "soccer",
                        "not autograph"
                    ],
                    "_ocr": {
                        "texts": [
                            {
                                "polygon": [
                                    [
                                        69.0,
                                        57.0
                                    ],
                                    [
                                        99.0,
                                        57.0
                                    ],
                                    [
                                        99.0,
                                        67.0
                                    ],
                                    [
                                        69.0,
                                        67.0
                                    ]
                                ],
                                "text": "Ocp",
                                "prob": 0.5447567701339722
                            },
                            {
                                "polygon": [
                                    [
                                        41.0,
                                        68.0
                                    ],
                                    [
                                        142.0,
                                        64.0
                                    ],
                                    [
                                        143.0,
                                        85.0
                                    ],
                                    [
                                        42.0,
                                        89.0
                                    ]
                                ],
                                "text": "Tirest",
                                "prob": 0.7674761414527893
                            },
                            {
                                "polygon": [
                                    [
                                        499.0,
                                        105.0
                                    ],
                                    [
                                        540.0,
                                        105.0
                                    ],
                                    [
                                        540.0,
                                        120.0
                                    ],
                                    [
                                        499.0,
                                        120.0
                                    ]
                                ],
                                "text": "JEFA",
                                "prob": 0.7145532965660095
                            },
                            {
                                "polygon": [
                                    [
                                        462.0,
                                        122.0
                                    ],
                                    [
                                        579.0,
                                        120.0
                                    ],
                                    [
                                        579.0,
                                        137.0
                                    ],
                                    [
                                        462.0,
                                        139.0
                                    ]
                                ],
                                "text": "CHAMPIONS",
                                "prob": 0.9965648651123047
                            },
                            {
                                "polygon": [
                                    [
                                        490.0,
                                        139.0
                                    ],
                                    [
                                        553.0,
                                        139.0
                                    ],
                                    [
                                        553.0,
                                        153.0
                                    ],
                                    [
                                        490.0,
                                        153.0
                                    ]
                                ],
                                "text": "LEAGUE",
                                "prob": 0.9776656627655029
                            },
                            {
                                "polygon": [
                                    [
                                        186.0,
                                        309.0
                                    ],
                                    [
                                        356.0,
                                        316.0
                                    ],
                                    [
                                        354.0,
                                        370.0
                                    ],
                                    [
                                        184.0,
                                        363.0
                                    ]
                                ],
                                "text": "Red Bull",
                                "prob": 0.8857282996177673
                            },
                            {
                                "polygon": [
                                    [
                                        41.0,
                                        720.0
                                    ],
                                    [
                                        229.0,
                                        693.0
                                    ],
                                    [
                                        234.0,
                                        728.0
                                    ],
                                    [
                                        46.0,
                                        755.0
                                    ]
                                ],
                                "text": "ERLING BRAUT",
                                "prob": 0.9621443748474121
                            },
                            {
                                "polygon": [
                                    [
                                        168.0,
                                        763.0
                                    ],
                                    [
                                        349.0,
                                        740.0
                                    ],
                                    [
                                        354.0,
                                        779.0
                                    ],
                                    [
                                        173.0,
                                        801.0
                                    ]
                                ],
                                "text": "HAALAND",
                                "prob": 0.9926786422729492
                            },
                            {
                                "polygon": [
                                    [
                                        310.0,
                                        795.0
                                    ],
                                    [
                                        452.0,
                                        773.0
                                    ],
                                    [
                                        456.0,
                                        794.0
                                    ],
                                    [
                                        313.0,
                                        816.0
                                    ]
                                ],
                                "text": "FCSALZBURG",
                                "prob": 0.9913728833198547
                            }
                        ],
                        "full_text": "Ocp Tirest JEFA CHAMPIONS LEAGUE Red Bull ERLING BRAUT HAALAND FCSALZBURG ",
                        "lang_name": "english",
                        "lang": "en"
                    },
                    "_identification": {
                        "best_match": {
                            "name": "ERLING BRAUT HAALAND",
                            "year": null,
                            "subcategory": "soccer"
                        }
                    }
                },
                {
                    "name": "Slab Label",
                    "id": "9242aeda-1a35-4c93-b75c-958af91e63a7",
                    "bound_box": [
                        210,
                        101,
                        861,
                        331
                    ],
                    "prob": 0.7469318509101868,
                    "area": 0.0962770061728395,
                    "Top Category": [
                        {
                            "id": "79425eda-c25b-48e3-a9de-0fe8303a4635",
                            "name": "Slab Label",
                            "prob": 1.0
                        }
                    ],
                    "_tags": {
                        "Category": [
                            {
                                "prob": 0.98442,
                                "name": "PSA",
                                "id": "2f4545e7-08e4-492b-ab4e-02a409d58988"
                            }
                        ]
                    },
                    "_tags_simple": [
                        "PSA"
                    ],
                    "_ocr": {
                        "texts": [
                            {
                                "polygon": [
                                    [
                                        550.0,
                                        55.0
                                    ],
                                    [
                                        609.0,
                                        55.0
                                    ],
                                    [
                                        609.0,
                                        82.0
                                    ],
                                    [
                                        550.0,
                                        82.0
                                    ]
                                ],
                                "text": "#91",
                                "prob": 0.9994840025901794
                            },
                            {
                                "polygon": [
                                    [
                                        35.0,
                                        62.0
                                    ],
                                    [
                                        302.0,
                                        57.0
                                    ],
                                    [
                                        302.0,
                                        82.0
                                    ],
                                    [
                                        36.0,
                                        86.0
                                    ]
                                ],
                                "text": "2019 FINESTUCL",
                                "prob": 0.942436695098877
                            },
                            {
                                "polygon": [
                                    [
                                        35.0,
                                        95.0
                                    ],
                                    [
                                        429.0,
                                        88.0
                                    ],
                                    [
                                        429.0,
                                        112.0
                                    ],
                                    [
                                        36.0,
                                        118.0
                                    ]
                                ],
                                "text": "ERLING BRAUT HAALAND",
                                "prob": 0.9580448865890503
                            },
                            {
                                "polygon": [
                                    [
                                        483.0,
                                        88.0
                                    ],
                                    [
                                        611.0,
                                        88.0
                                    ],
                                    [
                                        611.0,
                                        113.0
                                    ],
                                    [
                                        483.0,
                                        113.0
                                    ]
                                ],
                                "text": "GEMMT",
                                "prob": 0.993017315864563
                            },
                            {
                                "polygon": [
                                    [
                                        572.0,
                                        118.0
                                    ],
                                    [
                                        614.0,
                                        118.0
                                    ],
                                    [
                                        614.0,
                                        147.0
                                    ],
                                    [
                                        572.0,
                                        147.0
                                    ]
                                ],
                                "text": "10",
                                "prob": 0.9991844892501831
                            },
                            {
                                "polygon": [
                                    [
                                        454.0,
                                        156.0
                                    ],
                                    [
                                        612.0,
                                        154.0
                                    ],
                                    [
                                        612.0,
                                        180.0
                                    ],
                                    [
                                        454.0,
                                        182.0
                                    ]
                                ],
                                "text": "51974133",
                                "prob": 0.9994531273841858
                            }
                        ],
                        "full_text": "#91 2019 FINESTUCL ERLING BRAUT HAALAND GEMMT 10 51974133 ",
                        "lang_name": "german",
                        "lang": "de"
                    },
                    "_identification": {
                        "best_match": {
                            "name": "2019 FINEST UEFA ERLING BRAUT HAALAND",
                            "grade": "10",
                            "year": "2019",
                            "certificate_number": "51974133"
                        }
                    }
                }
            ]
        }
    ],
    "statistics": {
        "processing time": 6.233989953994751
    },
    "status": {
        "code": 200,
        "text": "OK",
        "proc_id": "743dc290-668f-4db0-be3a-2a4ce6945615"
    }
}

Slab Identification /v2/slab_id

Given a list of image records, this method returns detected objects (Card, Slab Label) with ocr analysis. The result Slab Label object with _objects (_tags and _ocr included), which represents location of the detected items (and readed text). The Slab Label contains information about company/category (BECKETT, CGC, PSA, SGC, Other) For one Slab Label per image, this model analyze readed text via AI of the slab and returns the analyzed info in _identification field:

"_identification": {
    "best_match": {
        "name": "POKEMON ROCKET DARK GYARADOS-HOLO",
        "grade": "9",
        "year": "2000",
        "certificate_number": "48658983"
    }
}

Parameters:

  • records: list of photos to analyze
    • must contain either of _url or _base64 field - see section image data for details
    • maximum batch of records is 10

$ curl https://api.ximilar.com/collectibles/v2/slab_id -H "Content-Type: application/json" -H "Authorization: Token __API_TOKEN__" -d '{
    "records": [
        { "_url": "__URL_IMAGE__"}
    ]
}'

Returns:

  • HTTP error code 2XX, if the method was OK and other HTTP error code, if the method failed.
  • Body of the response is a JSON object (map) with the following fields:
    • status - a JSON map with a status of the method processing. It contains these subfields:
      • code - a numeric code of the operation status; it follows the concept of HTTP status codes (2XX, 4XX). Specific codes are described for each type of answer (or operation) (see below).
      • text - a text describing the status code
      • error_description - in case of the processing ended with error (codes 4XX), this field contains a detailed description of the error; this might include Java stack traces.
    • Example of statuses that can be returned:
      "status": {"code": 200, "text": "OK"}
      "status": {"code": 402, "text": "aborted by error", error_description="..."}
      "status": {"code": 500, "text": "unknown error", "error_description": "..."}
    • statistics - a map of various statistics about the processing. The only statistic included every time is
      • processing time - time of actual processing of the query [in seconds]
    • records - JSON array with the input records, each record enriched by fields, Slab Label and _objects with _tags
CLICK TO SHOW JSON RESULT

{
    "records": [
        {
            "_url": "__URL_IMG__",
            "_status": {
                "code": 200,
                "text": "OK",
                "request_id": "6754d53f-6a92-456f-978a-aed572683c63"
            },
            "_id": "7ec4ef5c-0600-4400-9acb-b34d222c3002",
            "_objects": [
                {
                    "name": "Slab Label",
                    "id": "9242aeda-1a35-4c93-b75c-958af91e63a7",
                    "bound_box": [
                        28,
                        22,
                        363,
                        127
                    ],
                    "prob": 0.8884860277175903,
                    "area": 0.13721421020397814,
                    "_tags": {
                        "Category": [
                            {
                                "prob": 0.97916,
                                "name": "PSA",
                                "id": "2f4545e7-08e4-492b-ab4e-02a409d58988"
                            }
                        ]
                    },
                    "_tags_simple": [
                        "PSA"
                    ],
                    "_ocr": {
                        "texts": [
                            {
                                "polygon": [
                                    [
                                        296.0,
                                        22.0
                                    ],
                                    [
                                        322.0,
                                        22.0
                                    ],
                                    [
                                        322.0,
                                        45.0
                                    ],
                                    [
                                        296.0,
                                        45.0
                                    ]
                                ],
                                "text": "#8",
                                "prob": 0.9920072555541992
                            },
                            {
                                "polygon": [
                                    [
                                        19.0,
                                        25.0
                                    ],
                                    [
                                        218.0,
                                        25.0
                                    ],
                                    [
                                        218.0,
                                        40.0
                                    ],
                                    [
                                        19.0,
                                        40.0
                                    ]
                                ],
                                "text": "2000 POKEMON ROCKET",
                                "prob": 0.8794834613800049
                            },
                            {
                                "polygon": [
                                    [
                                        17.0,
                                        44.0
                                    ],
                                    [
                                        225.0,
                                        43.0
                                    ],
                                    [
                                        225.0,
                                        58.0
                                    ],
                                    [
                                        17.0,
                                        59.0
                                    ]
                                ],
                                "text": "DARK GYARADOS-HOLO",
                                "prob": 0.9649527668952942
                            },
                            {
                                "polygon": [
                                    [
                                        275.0,
                                        40.0
                                    ],
                                    [
                                        321.0,
                                        40.0
                                    ],
                                    [
                                        321.0,
                                        61.0
                                    ],
                                    [
                                        275.0,
                                        61.0
                                    ]
                                ],
                                "text": "MINT",
                                "prob": 0.99723219871521
                            },
                            {
                                "polygon": [
                                    [
                                        18.0,
                                        61.0
                                    ],
                                    [
                                        120.0,
                                        61.0
                                    ],
                                    [
                                        120.0,
                                        75.0
                                    ],
                                    [
                                        18.0,
                                        75.0
                                    ]
                                ],
                                "text": "1ST EDITION",
                                "prob": 0.948234498500824
                            },
                            {
                                "polygon": [
                                    [
                                        307.0,
                                        60.0
                                    ],
                                    [
                                        319.0,
                                        60.0
                                    ],
                                    [
                                        319.0,
                                        77.0
                                    ],
                                    [
                                        307.0,
                                        77.0
                                    ]
                                ],
                                "text": "9",
                                "prob": 0.9962127208709717
                            },
                            {
                                "polygon": [
                                    [
                                        146.0,
                                        73.0
                                    ],
                                    [
                                        188.0,
                                        73.0
                                    ],
                                    [
                                        188.0,
                                        98.0
                                    ],
                                    [
                                        146.0,
                                        98.0
                                    ]
                                ],
                                "text": "PA",
                                "prob": 0.9810179471969604
                            },
                            {
                                "polygon": [
                                    [
                                        239.0,
                                        77.0
                                    ],
                                    [
                                        321.0,
                                        77.0
                                    ],
                                    [
                                        321.0,
                                        95.0
                                    ],
                                    [
                                        239.0,
                                        95.0
                                    ]
                                ],
                                "text": "48658983",
                                "prob": 0.9986459016799927
                            }
                        ],
                        "full_text": "#8 2000 POKEMON ROCKET DARK GYARADOS-HOLO MINT 1ST EDITION 9 PA 48658983 ",
                        "lang_name": "english",
                        "lang": "en"
                    },
                    "_identification": {
                        "best_match": {
                            "name": "POKEMON ROCKET DARK GYARADOS-HOLO",
                            "grade": "9",
                            "year": "2000",
                            "certificate_number": "48658983"
                        }
                    }
                },
                {
                    "name": "Card",
                    "id": "76fa9ec3-e0d9-408a-b582-55a1cd6712e0",
                    "bound_box": [
                        38,
                        172,
                        340,
                        606
                    ],
                    "prob": 0.9829951524734497,
                    "area": 0.5112833575839376,
                    "Top Category": [
                        {
                            "id": "8ae26c4a-ae79-4c01-9b54-ac4e2b42e914",
                            "name": "Card",
                            "prob": 1.0
                        }
                    ]
                }
            ],
            "_width": 389,
            "_height": 659
        }
    ],
    "status": {
        "code": 200,
        "text": "OK",
        "request_id": "6754d53f-6a92-456f-978a-aed572683c63",
        "proc_id": "95e103eb-ea75-469b-a675-9263504973da"
    },
    "statistics": {
        "processing time": 3.3978192806243896
    }
}

Collectibles Detection /v2/detect

Given a list of image records, this method returns and objects of collector's items for each of them. The result images with _objects which represents location of the detected items. This method can be used as a first step for other endpoints as /v2/card_id ...

Parameters:

  • records: list of photos to analyze
    • must contain either of _url or _base64 field - see section image data for details
    • maximum batch of records is 10

$ curl https://api.ximilar.com/collectibles/v2/detect -H "Content-Type: application/json" -H "Authorization: Token __API_TOKEN__" -d '{
    "records": [
        { "_url": "https://images.ximilar.com/examples/cards/jordan.jpeg"}
    ]
}'

Returns:

  • HTTP error code 2XX, if the method was OK and other HTTP error code, if the method failed.
  • Body of the response is a JSON object (map) with the following fields:
    • status - a JSON map with a status of the method processing. It contains these subfields:
      • code - a numeric code of the operation status; it follows the concept of HTTP status codes (2XX, 4XX). Specific codes are described for each type of answer (or operation) (see below).
      • text - a text describing the status code
      • error_description - in case of the processing ended with error (codes 4XX), this field contains a detailed description of the error; this might include Java stack traces.
    • Example of statuses that can be returned:
      "status": {"code": 200, "text": "OK"}
      "status": {"code": 402, "text": "aborted by error", error_description="..."}
      "status": {"code": 500, "text": "unknown error", "error_description": "..."}
    • statistics - a map of various statistics about the processing. The only statistic included every time is
      • processing time - time of actual processing of the query [in seconds]
    • records - JSON array with the input records, each record enriched by fields (_objects)
CLICK TO SHOW JSON RESULT

{
    "records": [
        {
            "_url": "__IMAGE_URL__",
            "_status": {
                "code": 200,
                "text": "OK",
                "request_id": "1e459b5d-8bed-4d9a-8647-fc1c99997875"
            },
            "_id": "ebb627dd-e859-4677-83cf-612032d2ebb9",
            "_objects": [
                {
                    "name": "Card",
                    "id": "76fa9ec3-e0d9-408a-b582-55a1cd6712e0",
                    "bound_box": [
                        105,
                        348,
                        853,
                        1436
                    ],
                    "prob": 0.9431861639022827,
                    "area": 0.5242204881844521,
                    "expand_by_bound_box": [
                        91,
                        327,
                        867,
                        1457
                    ],
                    "Top Category": [
                        {
                            "id": "8ae26c4a-ae79-4c01-9b54-ac4e2b42e914",
                            "name": "Card",
                            "prob": 1.0
                        }
                    ]
                },
                {
                    "name": "Slab Label",
                    "id": "9242aeda-1a35-4c93-b75c-958af91e63a7",
                    "bound_box": [
                        77,
                        32,
                        943,
                        249
                    ],
                    "prob": 0.4136030375957489,
                    "area": 0.12104897690483277,
                    "expand_by_bound_box": [
                        60,
                        28,
                        960,
                        253
                    ],
                    "Top Category": [
                        {
                            "id": "79425eda-c25b-48e3-a9de-0fe8303a4635",
                            "name": "Slab Label",
                            "prob": 1.0
                        }
                    ]
                }
            ],
            "_width": 999,
            "_height": 1554
        }
    ],
    "status": {
        "code": 200,
        "text": "OK",
        "request_id": "1e459b5d-8bed-4d9a-8647-fc1c99997875",
        "proc_id": "219ad5f2-ad11-440c-b337-4f78f304e47b"
    },
    "statistics": {
        "processing time": 2.1185216903686523
    }
}