Skip to documentation
DOCUMENTATIONAPI referenceCardsIdentify from image
CARDS / V1

Identify from image

OCR a PNG, JPEG or WebP data URL. Accepts 100–3,000,000 decoded bytes, at most 16,000,000 pixels and 8,000 pixels per dimension. JSON body cap: 4,100,000 bytes. Successful OCR survives an identification outage.

POST/v1/identify-image
Bearer key requiredJSON response

The sample is a tiny synthetic image; replace it with your card photo. Uploaded bytes are processed in memory, not retained as image files.

Example requestv1
curl --request POST --max-time 35 \  --url 'https://pokepos-market-api.vercel.app/v1/identify-image' \  --header "Authorization: Bearer $CARDCOUNTER_API_KEY" \  --header 'Content-Type: application/json' \  --data '{"imageDataUrl":"data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAgAAAAICAYAAADED76LAAAAsUlEQVR4nAXBMZHEMAxAUTFYBisEYZARATPwjACYgQv1YZBGdRikUrsMrhOaf++JiKDyweSLy0HIScqgZNKyENEPql9MD1xPQgepk9JF60bEvqgdmJ24DcImaYuyTduFiB+on5gP3Cfhi/RN+UX7jUicaAwsJh6LiE3GRcVNx4NIDjQnlgvPTeRF5k3lQ+eLSE20FlYbr4uom6yHqpeuHyK90N5YX3jfRD9kv1T/6P7jH3V3kEGfv930AAAAAElFTkSuQmCC","setHint":""}'
Response illustrative JSON
{  "ocr": {    "text": "Example Pokémon card\n066/128",    "confidence": 86,    "suggested": {      "name": "Example Pokémon card",      "cardNumber": "066/128",      "query": "Example Pokémon card 066/128"    }  },  "identification": {    "source": "tcgplayer-public-site",    "query": "Example Pokémon card 066/128",    "parsed": {      "name": "Example Pokémon card",      "cardNumber": "066/128",      "setHint": "Example set"    },    "matchedSet": {      "name": "Example set",      "slug": "example-set"    },    "searchedCount": 1,    "totalSearchResults": 1,    "truncated": false,    "exactMatchProductId": 704860,    "ambiguous": false,    "setResolution": "matched",    "candidates": [      {        "productId": 704860,        "name": "Example Pokémon card",        "category": "Pokemon",        "setName": "Example set",        "setId": 100,        "setCode": "EXM",        "cardNumber": "066/128",        "rarity": "Rare",        "sealed": false,        "marketPrice": 5.45,        "lowestPrice": 3,        "listingCount": 1,        "matchScore": 500,        "match": {          "name": "exact",          "cardNumber": "exact",          "set": "exact",          "exact": true,          "reasons": [            "name:exact",            "cardNumber:exact",            "set:exact"          ]        }      }    ]  },  "identificationStatus": "ok",  "identificationError": null}
Example values can change with the source.
REQUEST

JSON body

Send this object with Content-Type: application/json.

imageDataUrlstringrequired

Complete data URL, not raw base64. 100–3,000,000 decoded bytes; at most 16,000,000 pixels and 8,000 pixels per dimension. Total JSON body limit: 4,100,000 bytes.

setHintstring

Value returned by the market data source.

RESPONSE

Response object

Identify from image The root schema is ImageIdentifyResult.

ocrOcrrequired

Text and confidence extracted from the card photo.

identificationIdentifyResult | nullrequired

Candidate lookup from the suggested query, if available.

identificationStatusstringrequired

One of ok, unavailable, not_attempted.

identificationErrorError | nullrequired

Catalog lookup error while preserving successful OCR.

SCHEMAS

Related objects

Expand a type to inspect its fields.

Ocr3 fields
textstringrequired

Text recognized from the photo.

confidencenumber | nullrequired

Tesseract confidence on a 0–100 scale; null when unavailable.

suggestedobjectrequired

Best-effort card identity inferred from OCR text.

Fields in suggested
suggested.namestring | nullrequired

Display name from the source catalog.

suggested.cardNumberstring | nullrequired

Collector number printed on the card.

suggested.querystring | nullrequired

Original or normalized search text.

IdentifyResult11 fields
sourcestringrequired

Always tcgplayer-public-site.

querystringrequired

Original or normalized search text.

parsedobjectrequired

Name, number, and set hint parsed from the card query.

Fields in parsed
parsed.namestringrequired

Display name from the source catalog.

parsed.cardNumberstring | nullrequired

Collector number printed on the card.

parsed.setHintstring | nullrequired

Value returned by the market data source.

matchedSetMatchedSet | nullrequired

Set matched from the optional hint, if any.

searchedCountintegerrequired

Number of products inspected while ranking matches.

totalSearchResultsinteger | nullrequired

Null means source coverage is unknown. Unknown or truncated coverage prevents a verified exact match.

truncatedbooleanrequired

Whether candidate inspection stopped at its search cap.

candidatesCandidate[]required

Ranked exact-printing candidates.

exactMatchProductIdinteger | nullrequired

Only a unique verified exact match is returned; null means confirm candidates manually.

ambiguousbooleanrequired

Whether several candidates remain plausible.

setResolutionstringrequired

One of unused, matched, unmatched, unavailable.

MatchedSet2 fields
namestring | nullrequired

Display name from the source catalog.

slugstringrequired

URL-safe identifier for a category or set.

Candidate14 fields
productIdintegerrequired

Numeric ID for the exact catalog product.

namestring | nullrequired

Display name from the source catalog.

categorystring | nullrequired

Product line or category for this result.

setNamestring | nullrequired

Value returned by the market data source.

setIdinteger | nullrequired

Value returned by the market data source.

setCodestring | nullrequired

Value returned by the market data source.

cardNumberstring | nullrequired

Collector number printed on the card.

raritystring | nullrequired

Rarity label reported by the catalog.

sealedbooleanrequired

Whether the product is sealed rather than a single card.

marketPricenumber | nullrequired

USD decimal dollars. Null means no usable observation, not zero.

lowestPricenumber | nullrequired

USD decimal dollars. Null means no usable observation, not zero.

listingCountinteger | nullrequired

Number of current listings, when reported.

matchScorenumberrequired

Relative score used to rank a candidate.

matchMatchrequired

Identity evidence for this candidate; matchScore alone is insufficient.

ProductSummary12 fields
productIdintegerrequired

Numeric ID for the exact catalog product.

namestring | nullrequired

Display name from the source catalog.

categorystring | nullrequired

Product line or category for this result.

setNamestring | nullrequired

Value returned by the market data source.

setIdinteger | nullrequired

Value returned by the market data source.

setCodestring | nullrequired

Value returned by the market data source.

cardNumberstring | nullrequired

Collector number printed on the card.

raritystring | nullrequired

Rarity label reported by the catalog.

sealedbooleanrequired

Whether the product is sealed rather than a single card.

marketPricenumber | nullrequired

USD decimal dollars. Null means no usable observation, not zero.

lowestPricenumber | nullrequired

USD decimal dollars. Null means no usable observation, not zero.

listingCountinteger | nullrequired

Number of current listings, when reported.

Match5 fields
namestringrequired

One of exact, partial.

cardNumberstringrequired

One of exact, partial, absent.

setstringrequired

One of exact, partial, absent, mismatch.

exactbooleanrequired

Value returned by the market data source.

reasonsstring[]required

Value returned by the market data source.

Error2 fields
codestringrequired

Machine-readable status or error code.

messagestringrequired

Human-readable explanation of the error.

HTTP

Status codes

200

Identify from image

400

Check route parameters or the JSON body.

401

Account-backed key is invalid, inactive, expired or revoked.

404

Unknown route.

405

Use the method published for this route.

413

Request body exceeds the accepted byte limit.

429

Quota or admission limit; inspect error.code and Retry-After.

500

Request failed; preserve x-request-id for support.

502

The source returned an error. Source 404 may map to API 404.

503

Account access store is unavailable or misconfigured.

504

Source request exceeded its budget.

Errors use error.code and error.message. Keep x-request-id for tracing. Read the error code catalog and examples.

Response headers

x-request-id

Request ID for tracing and support.

x-plan

Plan for admitted account-backed requests.

x-ratelimit-limit

Account allowance per UTC minute.

x-ratelimit-remaining

Remaining requests in the UTC minute.

x-monthly-limit

Account allowance per UTC month.

x-monthly-remaining

Remaining requests in the UTC month.

Retry-After

Nonnegative seconds until retry is useful for quota, cooldown or admission failures.

Success, empty, partial, stale and error examples
200 · success
{
  "ocr": {
    "text": "Example Pokémon card\n066/128",
    "confidence": 86,
    "suggested": {
      "name": "Example Pokémon card",
      "cardNumber": "066/128",
      "query": "Example Pokémon card 066/128"
    }
  },
  "identification": {
    "source": "tcgplayer-public-site",
    "query": "Example Pokémon card 066/128",
    "parsed": {
      "name": "Example Pokémon card",
      "cardNumber": "066/128",
      "setHint": "Example set"
    },
    "matchedSet": {
      "name": "Example set",
      "slug": "example-set"
    },
    "searchedCount": 1,
    "totalSearchResults": 1,
    "truncated": false,
    "exactMatchProductId": 704860,
    "ambiguous": false,
    "setResolution": "matched",
    "candidates": [
      {
        "productId": 704860,
        "name": "Example Pokémon card",
        "category": "Pokemon",
        "setName": "Example set",
        "setId": 100,
        "setCode": "EXM",
        "cardNumber": "066/128",
        "rarity": "Rare",
        "sealed": false,
        "marketPrice": 5.45,
        "lowestPrice": 3,
        "listingCount": 1,
        "matchScore": 500,
        "match": {
          "name": "exact",
          "cardNumber": "exact",
          "set": "exact",
          "exact": true,
          "reasons": [
            "name:exact",
            "cardNumber:exact",
            "set:exact"
          ]
        }
      }
    ]
  },
  "identificationStatus": "ok",
  "identificationError": null
}
200 · partial
{
  "ocr": {
    "text": "Example Pokémon card\n066/128",
    "confidence": 86,
    "suggested": {
      "name": "Example Pokémon card",
      "cardNumber": "066/128",
      "query": "Example Pokémon card 066/128"
    }
  },
  "identification": null,
  "identificationStatus": "unavailable",
  "identificationError": {
    "code": "UPSTREAM_HTTP_503",
    "message": "Source data is unavailable"
  }
}
200 · empty
{
  "ocr": {
    "text": "",
    "confidence": null,
    "suggested": {
      "name": null,
      "cardNumber": null,
      "query": null
    }
  },
  "identification": null,
  "identificationStatus": "not_attempted",
  "identificationError": null
}
400 · INVALID_INPUT
{
  "error": {
    "code": "INVALID_INPUT",
    "message": "Check route parameters or the JSON body."
  }
}
401 · INVALID_API_KEY
{
  "error": {
    "code": "INVALID_API_KEY",
    "message": "Account-backed key is invalid, inactive, expired or revoked."
  }
}
401 · UNAUTHORIZED
{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "The optional local single-key credential is missing or invalid."
  }
}
404 · NOT_FOUND
{
  "error": {
    "code": "NOT_FOUND",
    "message": "Unknown route."
  }
}
404 · IMAGE_NOT_AVAILABLE
{
  "error": {
    "code": "IMAGE_NOT_AVAILABLE",
    "message": "No source image is available for this product."
  }
}
405 · METHOD_NOT_ALLOWED
{
  "error": {
    "code": "METHOD_NOT_ALLOWED",
    "message": "Use the method published for this route."
  }
}
413 · INVALID_INPUT
{
  "error": {
    "code": "INVALID_INPUT",
    "message": "Request body exceeds the accepted byte limit."
  }
}
429 · RATE_LIMITED
{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Minute allowance exhausted; use Retry-After."
  }
}
429 · MONTHLY_QUOTA_EXCEEDED
{
  "error": {
    "code": "MONTHLY_QUOTA_EXCEEDED",
    "message": "Monthly allowance exhausted; retry after the next UTC month."
  }
}
429 · AUTH_RATE_LIMITED
{
  "error": {
    "code": "AUTH_RATE_LIMITED",
    "message": "Authentication admission limit reached."
  }
}
429 · DIAGNOSTIC_RATE_LIMITED
{
  "error": {
    "code": "DIAGNOSTIC_RATE_LIMITED",
    "message": "Usage diagnostic rate limit reached."
  }
}
500 · INTERNAL_ERROR
{
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "Request failed; preserve x-request-id for support."
  }
}
502 · UPSTREAM_HTTP_status
{
  "error": {
    "code": "UPSTREAM_HTTP_503",
    "message": "The source returned an error. Source 404 may map to API 404."
  }
}
502 · UPSTREAM_INVALID_RESPONSE
{
  "error": {
    "code": "UPSTREAM_INVALID_RESPONSE",
    "message": "Source data failed response or identity validation."
  }
}
502 · UPSTREAM_RESPONSE_TOO_LARGE
{
  "error": {
    "code": "UPSTREAM_RESPONSE_TOO_LARGE",
    "message": "Source or aggregate API response exceeds the byte limit."
  }
}
502 · UPSTREAM_NETWORK_ERROR
{
  "error": {
    "code": "UPSTREAM_NETWORK_ERROR",
    "message": "Source transport failed."
  }
}
502 · UPSTREAM_CANCELED
{
  "error": {
    "code": "UPSTREAM_CANCELED",
    "message": "Source work was canceled."
  }
}
503 · ACCESS_STORE_UNAVAILABLE
{
  "error": {
    "code": "ACCESS_STORE_UNAVAILABLE",
    "message": "Account access store is unavailable or misconfigured."
  }
}
503 · USAGE_UNAVAILABLE
{
  "error": {
    "code": "USAGE_UNAVAILABLE",
    "message": "Usage diagnostics require account-backed mode."
  }
}
503 · SERVICE_BUSY
{
  "error": {
    "code": "SERVICE_BUSY",
    "message": "Service admission capacity exhausted; use Retry-After."
  }
}
503 · ACCESS_BUSY
{
  "error": {
    "code": "ACCESS_BUSY",
    "message": "Database authorization capacity exhausted; use Retry-After."
  }
}
503 · UPSTREAM_BUSY
{
  "error": {
    "code": "UPSTREAM_BUSY",
    "message": "Source queue is full; use Retry-After."
  }
}
503 · OCR_BUSY
{
  "error": {
    "code": "OCR_BUSY",
    "message": "Photo recognition queue is full; use Retry-After."
  }
}
503 · OCR_UNAVAILABLE
{
  "error": {
    "code": "OCR_UNAVAILABLE",
    "message": "Photo recognition is unavailable."
  }
}
504 · UPSTREAM_TIMEOUT
{
  "error": {
    "code": "UPSTREAM_TIMEOUT",
    "message": "Source request exceeded its budget."
  }
}
504 · OCR_TIMEOUT
{
  "error": {
    "code": "OCR_TIMEOUT",
    "message": "Photo recognition exceeded its processing budget."
  }
}
504 · REQUEST_DEADLINE_EXCEEDED
{
  "error": {
    "code": "REQUEST_DEADLINE_EXCEEDED",
    "message": "Total request deadline exceeded."
  }
}