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.
/v1/identify-imageThe sample is a tiny synthetic image; replace it with your card photo. Uploaded bytes are processed in memory, not retained as image files.
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":""}'{ "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}JSON body
Send this object with Content-Type: application/json.
imageDataUrlstringrequiredComplete 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.
setHintstringValue returned by the market data source.
Response object
Identify from image The root schema is ImageIdentifyResult.
ocrOcrrequiredText and confidence extracted from the card photo.
identificationIdentifyResult | nullrequiredCandidate lookup from the suggested query, if available.
identificationStatusstringrequiredOne of ok, unavailable, not_attempted.
identificationErrorError | nullrequiredCatalog lookup error while preserving successful OCR.
Related objects
Expand a type to inspect its fields.
Ocr3 fields
textstringrequiredText recognized from the photo.
confidencenumber | nullrequiredTesseract confidence on a 0–100 scale; null when unavailable.
suggestedobjectrequiredBest-effort card identity inferred from OCR text.
Fields in suggested
suggested.namestring | nullrequiredDisplay name from the source catalog.
suggested.cardNumberstring | nullrequiredCollector number printed on the card.
suggested.querystring | nullrequiredOriginal or normalized search text.
IdentifyResult11 fields
sourcestringrequiredAlways tcgplayer-public-site.
querystringrequiredOriginal or normalized search text.
parsedobjectrequiredName, number, and set hint parsed from the card query.
Fields in parsed
parsed.namestringrequiredDisplay name from the source catalog.
parsed.cardNumberstring | nullrequiredCollector number printed on the card.
parsed.setHintstring | nullrequiredValue returned by the market data source.
matchedSetMatchedSet | nullrequiredSet matched from the optional hint, if any.
searchedCountintegerrequiredNumber of products inspected while ranking matches.
totalSearchResultsinteger | nullrequiredNull means source coverage is unknown. Unknown or truncated coverage prevents a verified exact match.
truncatedbooleanrequiredWhether candidate inspection stopped at its search cap.
candidatesCandidate[]requiredRanked exact-printing candidates.
exactMatchProductIdinteger | nullrequiredOnly a unique verified exact match is returned; null means confirm candidates manually.
ambiguousbooleanrequiredWhether several candidates remain plausible.
setResolutionstringrequiredOne of unused, matched, unmatched, unavailable.
MatchedSet2 fields
namestring | nullrequiredDisplay name from the source catalog.
slugstringrequiredURL-safe identifier for a category or set.
Candidate14 fields
productIdintegerrequiredNumeric ID for the exact catalog product.
namestring | nullrequiredDisplay name from the source catalog.
categorystring | nullrequiredProduct line or category for this result.
setNamestring | nullrequiredValue returned by the market data source.
setIdinteger | nullrequiredValue returned by the market data source.
setCodestring | nullrequiredValue returned by the market data source.
cardNumberstring | nullrequiredCollector number printed on the card.
raritystring | nullrequiredRarity label reported by the catalog.
sealedbooleanrequiredWhether the product is sealed rather than a single card.
marketPricenumber | nullrequiredUSD decimal dollars. Null means no usable observation, not zero.
lowestPricenumber | nullrequiredUSD decimal dollars. Null means no usable observation, not zero.
listingCountinteger | nullrequiredNumber of current listings, when reported.
matchScorenumberrequiredRelative score used to rank a candidate.
matchMatchrequiredIdentity evidence for this candidate; matchScore alone is insufficient.
ProductSummary12 fields
productIdintegerrequiredNumeric ID for the exact catalog product.
namestring | nullrequiredDisplay name from the source catalog.
categorystring | nullrequiredProduct line or category for this result.
setNamestring | nullrequiredValue returned by the market data source.
setIdinteger | nullrequiredValue returned by the market data source.
setCodestring | nullrequiredValue returned by the market data source.
cardNumberstring | nullrequiredCollector number printed on the card.
raritystring | nullrequiredRarity label reported by the catalog.
sealedbooleanrequiredWhether the product is sealed rather than a single card.
marketPricenumber | nullrequiredUSD decimal dollars. Null means no usable observation, not zero.
lowestPricenumber | nullrequiredUSD decimal dollars. Null means no usable observation, not zero.
listingCountinteger | nullrequiredNumber of current listings, when reported.
Match5 fields
namestringrequiredOne of exact, partial.
cardNumberstringrequiredOne of exact, partial, absent.
setstringrequiredOne of exact, partial, absent, mismatch.
exactbooleanrequiredValue returned by the market data source.
reasonsstring[]requiredValue returned by the market data source.
Error2 fields
codestringrequiredMachine-readable status or error code.
messagestringrequiredHuman-readable explanation of the error.
Status codes
Identify from image
Check route parameters or the JSON body.
Account-backed key is invalid, inactive, expired or revoked.
Unknown route.
Use the method published for this route.
Request body exceeds the accepted byte limit.
Quota or admission limit; inspect error.code and Retry-After.
Request failed; preserve x-request-id for support.
The source returned an error. Source 404 may map to API 404.
Account access store is unavailable or misconfigured.
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-idRequest ID for tracing and support.
x-planPlan for admitted account-backed requests.
x-ratelimit-limitAccount allowance per UTC minute.
x-ratelimit-remainingRemaining requests in the UTC minute.
x-monthly-limitAccount allowance per UTC month.
x-monthly-remainingRemaining requests in the UTC month.
Retry-AfterNonnegative 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."
}
}