Pokemon TCG API

Endpoint

Query Parameters

Rate Limiting

Grader-Specific Fields

Example Requests

Response Format

{
  "data": {
    "tcgPlayerId": "490294",
    "populationByGrader": {
      "PSA": {
        "g8": 1500,
        "g9": 8000,
        "g10": 2500,
        "auth": 50,
        "qualifiers": 25,
        "totalPopulation": 12075,
        "gemRate": 20.70
      },
      "BGS": {
        "g8": 200,
        "g9": 1000,
        "g9_5": 500,
        "g10": 100,
        "pristine": 25,
        "perfect": 5,
        "totalPopulation": 1830,
        "gemRate": 7.10
      },
      "CGC": {
        "g9": 400,
        "g9_5": 200,
        "g10": 50,
        "totalPopulation": 650,
        "gemRate": 7.69
      },
      "SGC": {
        "g9": 100,
        "g10": 30,
        "totalPopulation": 130,
        "gemRate": 23.08
      }
    },
    "totalPopulation": 14685,
    "totalGems": 2710,
    "combinedGemRate": 18.45,
    "gradersTracked": ["PSA", "BGS", "CGC", "SGC"],
    "combinedTotals": {
      "g8": 1700,
      "g9": 9500,
      "g10": 2685
    },
    "percentHigher": {
      "g8": 45.2,
      "g9": 19.3,
      "g10": 0
    },
    "matchConfidence": "high",
    "matchScore": 0.98,
    "lastFetchedDate": "2024-01-15T12:00:00Z",
    "updatedAt": "2024-01-15T12:00:00Z"
  },
  "metadata": {
    "total": 1,
    "count": 1,
    "limit": 1,
    "offset": 0,
    "hasMore": false,
    "language": "english",
    "apiCallsConsumed": {
      "total": 2,
      "breakdown": {
        "cards": 1,
        "population": 1
      },
      "costPerCard": 2
    }
  }
}

Response Fields

Response Headers

Error Responses

Use Cases

• Grading ROI Calculations: Use gem rates and percentHigher to estimate returns on grading investments
• Market Scarcity Assessment: Low population + high gem rate = rare high-grade copies
• Investment Research: Compare population across grading companies for arbitrage opportunities
• Portfolio Analysis: Track population changes over time for your collection
• BGS vs PSA Analysis: Compare pristine/perfect rates vs PSA 10 rates

Integration Notes

• Population data is sourced from GemRate and updated periodically
• Not all cards have population data - check gradersTracked array for available graders
• Use matchConfidence to assess data reliability - "high" confidence indicates strong card identification
• The percentHigher field shows what percentage of cards graded higher than each grade, useful for ROI calculations
• BGS has special grades: pristine (BGS 10 Pristine) and perfect (BGS 10 Black Label)
• Half grades (g9_5, etc.) are only available for BGS and CGC

Endpoint

Parameters

CSV Columns by Type

Response

Returns 302 Found redirecting to a gzip-compressed CSV file on Vercel Blob. The file is regenerated daily at 6:00 AM UTC. Download it directly from the Location header URL.

Error Responses

Examples

curl -L -H "Authorization: Bearer YOUR_API_KEY" \
  "https://www.pokemonpricetracker.com/api/v2/export?type=cards" \
  -o cards-latest.csv.gz

curl -L -H "Authorization: Bearer YOUR_API_KEY" \
  "https://www.pokemonpricetracker.com/api/v2/export?type=population" \
  -o population-latest.csv.gz

Best Practices

• Download once per day, not per request. The dump only changes once daily (regenerated at 6:00 AM UTC). Pull it after 6:00 AM UTC, cache it on your side, and serve all your reads from your own copy. You have 2 downloads/day — treat the second as a retry, not a polling loop.
• Use export for full-catalog syncs, the /cards endpoint for lookups. If you need the whole catalog (50,000+ cards) the export is one request instead of thousands of paginated calls and burns zero API credits. For looking up a handful of specific cards or live single-card prices, the regular endpoints are better.
• Follow the redirect. The endpoint returns 302 to a Vercel Blob URL — make sure your HTTP client follows redirects (curl -L, axios default, fetch default). Don't cache or hardcode the blob URL; it changes each day.
• Decompress the gzip stream. Files are served as .csv.gz. Pipe through gunzip (curl -L ... | gunzip > cards.csv) or decompress in code before parsing. All files are UTF-8 with a header row and RFC 4180 quoting.
• Join the four datasets on tcgPlayerId. Every dataset shares tcgPlayerId as the key. Download cards, ebay, and population separately and join them locally to build a complete per-card record.
• Handle 503 gracefully. Before 6:00 AM UTC the new dump may not exist yet. On 503, respect the Retry-After header (defaults to 1 hour) rather than retrying immediately — this does not count against your daily download quota.
• Check the freshness headers. Use X-Dump-Generated-At to confirm you got today's data, and X-Export-Downloads-Remaining to track your quota before scheduling the next pull.