Skip to content
pokemontcgapi.com
sign in

Card scanner API

A Pokémon card scanner API: identify a card from a photo

Send a photograph, get the card back as a catalogue id with ranked candidates. The card is located in the frame and straightened first, so a hand-held phone photo works, and when two printings share the artwork the response says so instead of guessing.

Request
POST /v1/vision/identify, multipart, one image field
Formats
JPEG or PNG, up to 10 MB
Answer
match, ambiguous or no_match, with ranked candidates
Plan
Growth and above, 25 credits a photo
get a free trial keyread the referencesee the plans

A card scanner is two problems: recognising the artwork, and knowing which of the printings that share that artwork you are holding. General-purpose vision models are confident and wrong on the second one. They will say "Base Set Charizard" in front of a reprint and have no way to know.

This endpoint matches the photo against an index of the catalogue's own card images and returns a decision. match fills in id. ambiguous returns the candidates, reprints and Japanese twins included, and leaves id null on purpose: picking one would be wrong half the time, on exactly the cards that are worth the most. no_match with regions_detected: 0 means the card was not found in the frame, which is a framing problem and a different message to show your user.

If your flow knows the set, because the user is logging a booster they just opened, pass set (or region) as a hint. It is what breaks the tie between printings.

One call, and what comes back

One photo in, ranked candidates out. `distance` is the raw figure to tune your own threshold on; `confidence` is the same information rescaled.

POST/v1/vision/identify25 credits · from Growthfull reference
curl -s -X POST "https://api.pokemontcgapi.com/v1/vision/identify" \
  -H "X-Api-Key: $PTCG_API_KEY" \
  -F "[email protected]" \
  -F "top_k=3"
response.json
{
  "data": {
    "decision": "ambiguous",
    "id": null,
    "candidates": [
      {
        "id": "bs-4",
        "name": "Charizard",
        "number": "4",
        "set": { "code": "bs", "name": "Base Set", "print_region": "WEST" },
        "rarity": "Rare Holo",
        "image_url": "https://img.pokemontcgapi.com/cards/bs/4-normal.webp",
        "distance": 31,
        "confidence": 0.818
      },
      {
        "id": "b2-4",
        "name": "Charizard",
        "number": "4",
        "set": { "code": "b2", "name": "Base Set 2", "print_region": "WEST" },
        "rarity": "Rare Holo",
        "image_url": "https://img.pokemontcgapi.com/cards/b2/4-normal.webp",
        "distance": 38,
        "confidence": 0.776
      }
    ]
  },
  "meta": {
    "count": 2,
    "cards_indexed": 51983,
    "index_built_at": "2026-08-27T04:10:22Z",
    "signature_version": 1,
    "regions_detected": 2,
    "hypotheses_tried": 8,
    "elapsed_ms": 74
  }
}

From the id to everything else

The id that comes back is a catalogue id, so the next call is the ordinary one: GET /v1/cards/{id}?include=prices returns the card with its image, set, rarity, illustrator and current prices. A scan-to-value flow is two requests and 27 credits.

Plan and cost

Photo recognition is served from Growth (€79/month, 200,000 credits a month) and costs 25 credits a photo. A key on a lower plan gets a 403 PLAN_REQUIRED before any credit is spent. The catalogue side of a scanner app, the search, the card pages and the prices, runs on the trial, so you can build everything around the camera first.

What it is not

Read this before you build on it. Every line here is a support ticket somebody else already opened.

Treat ambiguous as the normal case
Reprints share artwork. Design the picker screen first; the single-answer path is the shortcut, not the other way round.
Lighting and framing matter
Glare on a holo, a dark room or a card cut off by the frame lower the match quality. Guide the user to fill the frame, and offer the set hint.
One card per photo
The endpoint identifies a single card. A binder page or a spread of cards needs to be split on your side.

Questions people ask before signing up

Is there an API to identify a Pokémon card from an image?
Yes. POST /v1/vision/identify takes a JPEG or PNG and returns a decision (match, ambiguous or no_match) with ranked candidate cards from the catalogue, each with its id, set, number and image.
Does it work with photos taken on a phone?
Yes. The card is located in the frame and rectified before matching, so it does not need a flat scan or a clean crop. Even lighting and a card that fills the frame give the best results.
Can it tell a reprint from the original?
Not from the artwork alone, and it does not pretend to: when printings share the illustration the decision is ambiguous and the candidates are listed. Passing the set as a hint resolves it.
How much does card recognition cost?
25 credits per photo, from the Growth plan (€79/month). Failed requests and plan refusals cost nothing. Pricing

Keep reading