Identify a card from a photo

No key yet? One call gets you one: POST /v1/accounts/free with an Idempotency-Key header and your email address returns a working key in the response. Keep the original Idempotency-Key and body for response replay for up to 24 hours, under the conditions in the quickstart. The trial is 800 credits over 30 days once the address is confirmed, no card; paid plans start at 29 € a month. See the quickstart and the pricing.

A photograph goes in and a ranked list comes out. Reprints and regional twins can share their artwork, so the image ranking alone may be ambiguous. When available, OCR reads the printed collector fraction on the winning card crop and selects a card only if its number matches exactly one candidate. The response includes the candidates, their distances and whether the evidence is clear enough to act on.

How it works

Every catalogue image is reduced to a 64-byte perceptual signature — a DCT signature of its low frequencies plus a gradient signature — and your photograph is reduced the same way. The comparison is a Hamming distance across the whole index, which is a linear scan and costs under a millisecond.

The photograph does not need to be a tight crop. Before hashing, the card is looked for as a quadrilateral in the frame and each candidate quadrilateral is straightened into the canonical portrait crop; those hypotheses compete with a set of concentric centre crops, and the one that actually matches the catalogue wins on distance. A quadrilateral that grabbed the table instead of the card lands about three times farther away and simply loses.

For an ambiguous ranking with at least two candidates, the service may read the collector number from the bottom of the winning crop. A fraction such as 048/172 matches card number 48; prefixes and suffixes such as TG12, SV045 and 194a are kept when comparing numbers. When several nearby cards share that number, OCR may also read the printed set code beside it. A unique exact number and set-code match gives decision_reason: "ocr_set_number"; OCR errors and timeouts leave the image ranking unchanged.

Reading the decision

data.id is populated only on match. On ambiguous it is null on purpose: a client that reads it without looking at decision should break immediately and visibly rather than quietly hand over the wrong printing.

decision_reason is clear for a match, reprint for a tied distance or the same name and number, close_call for other near matches, and none when no candidate qualifies. The decision uses at least two candidates and all ties even when top_k=1; top_k limits only the returned list.

meta.index_built_at is the newest signature timestamp in the loaded index. meta.index_loaded_at is when this process loaded it. The server checks for a new signature timestamp every hour by default.

Use include=index to put index_eur and last_price_at on each candidate. include=prices also puts the current prices[] quotes on each candidate, with the same legal and plan filters as the card batch. A Free trial sees English ungraded quotes; Growth includes graded and all locales. When the plan withholds quotes, both top-level withheld and the X-Plan-Withheld header list graded and/or non_english_locales. If there are no candidates, the extra include credits are refunded.

The index figures in the response example illustrate the field shape; they are not live valuations. Always read the returned timestamp and the current response for a value.

meta.ocr appears when the tie-break is considered. It reports applied, elapsed OCR time in ms, the detected number when available, or a reason (no_text, no_fraction, no_match, multiple, timeout, disabled, error). A set-code pass reports set_code on success or set_reason (no_token, no_match, multiple, timeout, error) otherwise. meta.elapsed_ms includes this time.

Body fields

Headers

Example request

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" \
  -F "include=index"

Example response

200 OK · Cache-Control: private, no-store

{
  "data": {
    "decision": "ambiguous",
    "decision_reason": "reprint",
    "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/media/cards/bs/4-normal.webp?e=1791763200&s=Nw8cT5kYq1zRv3jLp0xGbH",
        "index_eur": 350,
        "last_price_at": "2026-08-27T00:00:00.000Z",
        "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/media/cards/b2/4-normal.webp?e=1791763200&s=Fy2mK9wPd4sXn7bQr1tVcZ",
        "index_eur": 200,
        "last_price_at": "2026-08-27T00:00:00.000Z",
        "distance": 38,
        "confidence": 0.776
      }
    ]
  },
  "meta": {
    "count": 2,
    "cards_indexed": 51983,
    "index_built_at": "2026-08-27T04:10:22Z",
    "index_loaded_at": "2026-08-27T05:10:22Z",
    "signature_version": 1,
    "regions_detected": 2,
    "hypotheses_tried": 16,
    "ocr": { "applied": false, "number": 4, "ms": 210, "reason": "multiple" },
    "elapsed_ms": 284
  }
}

Errors

Every error body carries error.code, error.message and error.request_id. Switch on the code, never on the message.

The full taxonomy, with what to do about each code, is on the errors page.

Two candidates, one illustration

The example above is the normal case rather than an edge case. Base Set Charizard and its Base Set 2 reprint are the same illustration on the same layout; the seven bits between them are printing noise, not a difference the camera can see. Any scanner that picks one of the two silently is wrong about half the time, and it is wrong on precisely the cards people care most about.

The two ways out are both in your hands: pass set or region when your workflow knows them — someone inventorying a pack they just opened does — or present both and take one tap. What the API will not do is guess and call it certainty.