Skip to documentation
Developers
DOCUMENTATIONAPI referenceCardsIdentify a card
CARDS / V1

Identify a card

Resolve a Pokémon name and collector number into ranked product candidates. Add a set hint when the same card appears in multiple printings.

GET/v1/identify
Bearer key requiredJSON response

Always let a user confirm the exact printing before applying a market price.

Example requestv1
curl --request GET \  --url 'https://pokepos-market-api.vercel.app/v1/identify?q=Mew%20ex%2066&set=30th%20Celebration' \  --header 'Authorization: Bearer YOUR_API_KEY'
Response illustrative JSON
{  "source": "tcgplayer-public-site",  "query": "Mew ex 66",  "parsed": {    "name": "Mew ex",    "cardNumber": "66",    "setHint": "30th Celebration"  },  "matchedSet": {    "name": "30th Celebration",    "slug": "30th-celebration",    "count": 100  },  "searchedCount": 18,  "totalSearchResults": 18,  "truncated": false,  "candidates": [    {      "productId": 716465,      "name": "Mew ex - 066/128",      "cardNumber": "066/128",      "matchScore": 440    }  ]}
Example values can change with the source.
REQUEST

Parameters

Pass path parameters in the URL and query parameters after ?.

qstringrequiredquery

Card or product text to match. A collector number can be included. Up to 120 characters. Example: Mew ex 66.

setstringquery

Optional set name or slug to narrow the search to one release. Up to 80 characters. Example: 30th Celebration.

limitintegerquery

Maximum number of results to include in this response. Range: 1–24. Default: 12.

RESPONSE

Response object

Ranked candidate printings. The root schema is IdentifyResult.

sourcestring

Name of the market data source.

querystring

Original or normalized search text.

parsedobject

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

matchedSetSet | null

Set matched from the optional hint, if any.

searchedCountinteger

Number of products inspected while ranking matches.

totalSearchResultsinteger

Total catalog search hits before candidate ranking.

truncatedboolean

Whether candidate inspection stopped at its search cap.

candidatesProductSummary & object[]

Ranked exact-printing candidates.

SCHEMAS

Related objects

Expand a type to inspect its fields.

Set3 fields
namestring

Display name from the source catalog.

slugstring

URL-safe identifier for a category or set.

countinteger

Number of catalog products in the set.

ProductSummary11 fields
productIdinteger

Numeric ID for the exact catalog product.

namestring

Display name from the source catalog.

categorystring | null

Product line or category for this result.

setNamestring | null

Value returned by the market data source.

setIdinteger | null

Value returned by the market data source.

cardNumberstring | null

Collector number printed on the card.

raritystring | null

Rarity label reported by the catalog.

sealedboolean

Whether the product is sealed rather than a single card.

marketPricenumber | null

US dollars. Null means no observation is available.

lowestPricenumber | null

US dollars. Null means no observation is available.

listingCountinteger | null

Number of current listings, when reported.

HTTP

Status codes

200

Ranked candidate printings.

400

Invalid parameter or request body.

502

An upstream market source is unavailable.

Errors use the error.code and error.message shape. Keep the x-request-id response header for support and tracing.

NEXTIdentify from image