Is there an API that identifies Pokémon cards from a photo?

What you send

One POST request to https://europe-west1-neosatoshi.cloudfunctions.net/detectApi with the header Authorization: Bearer <key> and a JSON body with either image (a base64 JPEG or PNG, up to 12 MB) or image_url (a public https link to one). Pokémon is the default game, so you do not need to send "tcg". This request uses our example binder photo and the public demo key and works as is:

curl -X POST https://europe-west1-neosatoshi.cloudfunctions.net/detectApi \
  -H "Authorization: Bearer nsk_live_9c253fbed995042a98280ad13e5c47d3c4a59c9b4f0f7274" \
  -H "Content-Type: application/json" \
  -d '{"image_url": "https://neosatoshi.com/static/images/example_api_multi.jpg"}'

What comes back for each card

{
  "name": "Charizard ex",
  "name_ja": null,
  "language": "en",
  "set": { "id": "sv3pt5", "ptcgo_code": "MEW", "name": "151", "number": "006" },
  "rarity": "Illustration Rare",
  "cardmarket_id": 746497,
  "reverse_holo": false,
  "first_edition": false,
  "prices": {
    "cardmarket": { "trend": 3.93, "low": 2.50, "avg7": 4.05, "avg30": 4.21, "currency": "EUR" }
  },
  "confidence": 0.97,
  "alternatives": [
    { "name": "Charizard", "set": "Base", "number": "004", "score": 0.81 }
  ]
}

• name: the card name in its printed language. For Japanese, Korean and Chinese cards it is the English name, and the original name is in name_ja, name_ko or name_zh.
• language: the detected card language, for example "en", "de", "ja" or "zh".
• set: the set id, ptcgo_code (the short code printed on modern cards, such as MEW for 151), the set name and the card number.
• rarity: the printed rarity.
• reverse_holo and first_edition: true when the photo shows a Reverse Holo or a 1st Edition print. Reverse Holo is only considered where rarity and era allow it.
• cardmarket_id: the Cardmarket product ID (idProduct). It is null for a few cards.
• prices.cardmarket: trend, low, avg7 and avg30 in EUR, refreshed daily.
• possible_variants: known catalog versions of the card (for example stamped versions), with their own Cardmarket ID and price where known. These are options for your user to confirm, not something read from the photo. Null means there is no variant data, not that no variants exist.
• is_energy_card and is_card_back: flags so your app can skip basic energies and card backs.
• images: reference images in two sizes.
• confidence (0 to 1) and image_quality (blurred, unusual dimensions).
• alternatives: lower-scored candidates with name, set, number and score, so your users can pick the right card by hand when the first match is wrong.

The full schema is in the OpenAPI spec and the documentation.

Several cards per photo and binder pages

One photo can hold many Pokémon cards: cards laid out on a table, a grid or a full binder page. Each card comes back as its own object in cards, with its own confidence, and count says how many cards were confidently detected. Results are best with up to about 20 cards per photo in good, even light. There is no hard limit, but more cards per photo means smaller cards and harder detection. Avoid glare from sleeves and binder pockets.

Japanese, Korean and Chinese cards

Japanese, Korean and Simplified Chinese cards are recognised from the card itself. name holds the English name, so you can search and sort across languages, and the original name comes in name_ja, name_ko or name_zh. Japanese cards are matched to their Japanese set and Cardmarket product. Traditional Chinese cards are not supported yet.

Cost, limits and speed

• One card scan per detected card: a binder page with nine cards uses nine. A card the model is not confident about is not charged, and a photo without any card returns HTTP 422 and costs nothing.
• The public demo key allows 10 requests per day per network, whatever the number of cards in each photo. Every demo response shows demo.remaining_today.
• For your own key you need a paid plan. Start-Up, the smallest paid plan, costs 19 per month (15 per month paid yearly, the same number in EUR, USD or CHF) and includes 1,000 card scans per month, from the same balance as the NeoSatoshi app. Current plans: pricing.
• The request is synchronous: a warm request takes about 5 seconds, a cold one 10 to 15 seconds. Set a client timeout of 120 seconds.

What the API does not do

• It does not grade condition. Centering, corners, edges and surface are never judged; let your user set the condition.
• It does not check whether a card is genuine.
• It does not read stamps or other special versions from the photo; possible_variants lists the known options for your user to pick.
• It does not read Traditional Chinese cards yet.

Frequently asked questions

Can the API read a whole binder page?

Yes. Send the photo of the page as one image; every card comes back as its own entry. Results are best with up to about 20 cards per photo, in even light and without glare.

Which Cardmarket price should I use?

trend is Cardmarket's trend price, low the lowest current offer, and avg7 and avg30 the average sale prices of the last 7 and 30 days. Many sellers start from avg30 because it moves less. A value can be 0 or missing when Cardmarket has no data for it, so fall back to another field.

How do I tell a Reverse Holo from the normal card?

Check reverse_holo. On Cardmarket a Reverse Holo is the same product as the normal card, sold with its own Reverse Holo flag and its own price, so keep the flag when you list or price the card.

Is there a Python example?

Yes, with a single photo, a folder to CSV and error handling: how to build a trading card scanner app. For the other games, see the API for Magic, Lorcana, Yu-Gi-Oh! and One Piece.