Getting Started

Population Reports

Overview

Population reports (or "pop reports") provide data on the number of cards graded by various grading companies. This information is crucial for understanding the rarity and supply of specific card grades in the market.

Including Population Reports

To include population reports in your API requests, use the include query parameter. You can combine it with other include options like prices.

[!IMPORTANT]
The pop_reports field on card variants will be empty or omitted unless include=pop_reports is explicitly specified in your request.

[!NOTE]
Population reports are only available on requests that fetch cards. They are not available when fetching expansions, sets, or other resources.

Example:
include=pop_reports
include=prices,pop_reports

Availability

Population reports exist at the card variant level. It is important to note that not every variant is guaranteed to have reports.

Currently, we support the following population reports:

Support Table

TCG	Company	Language
Pokémon	PSA	English

Webhooks

Webhooks are available for receiving real-time updates when population reports are updated. You can subscribe to these events to keep your local data in sync without constant polling.

For more information on how to set up and use webhooks, check out our Webhooks Documentation.

Payload Structure

company <string>

The grading company providing the report (e.g., PSA).

total <integer>
The total number of cards graded by this company for this variant.

grade_total <integer>
The total number of cards that received a numeric grade.

qualified_grade_total <integer>
The total number of cards with qualified grades (e.g., MC, OC).

half_grade_total <integer>
The total number of cards that received a half-grade (e.g., 8.5).

grades <array>
An array of individual grade counts. Each object contains:

grade <string>: The specific grade (e.g., 10, 9, auth).
count <integer>: The number of cards that received this grade.

Sample Population Report

"pop_reports": [
  {
    "company": "PSA",
    "total": 5445,
    "grade_total": 5211,
    "qualified_grade_total": 14,
    "half_grade_total": 220,
    "grades": [
      {
        "grade": "auth",
        "count": 46
      },
      {
        "grade": "1Q",
        "count": 2
      },
      {
        "grade": "1",
        "count": 203
      },
      {
        "grade": "1.5",
        "count": 49
      },
      {
        "grade": "2Q",
        "count": 1
      },
      {
        "grade": "2",
        "count": 228
      },
      {
        "grade": "2.5",
        "count": 5
      },
      {
        "grade": "3Q",
        "count": 2
      },
      {
        "grade": "3",
        "count": 417
      },
      {
        "grade": "3.5",
        "count": 4
      },
      {
        "grade": "4Q",
        "count": 3
      },
      {
        "grade": "4",
        "count": 578
      },
      {
        "grade": "4.5",
        "count": 6
      },
      {
        "grade": "5",
        "count": 745
      },
      {
        "grade": "5.5",
        "count": 5
      },
      {
        "grade": "6Q",
        "count": 1
      },
      {
        "grade": "6",
        "count": 832
      },
      {
        "grade": "6.5",
        "count": 29
      },
      {
        "grade": "7",
        "count": 598
      },
      {
        "grade": "7.5",
        "count": 30
      },
      {
        "grade": "8",
        "count": 710
      },
      {
        "grade": "8.5",
        "count": 92
      },
      {
        "grade": "9Q",
        "count": 5
      },
      {
        "grade": "9",
        "count": 729
      },
      {
        "grade": "10",
        "count": 125
      }
    ]
  }
]

Example Request

Lang:

curl -X GET 'https://api.scrydex.com/pokemon/v1/cards?include=pop_reports' \
-H 'X-Api-Key: YOUR_API_KEY' \
-H 'X-Team-ID: YOUR_TEAM_ID'

import requests

def get_card_with_pop_reports(card_id):
    url = f"https://api.scrydex.com/pokemon/v1/cards/{card_id}"
    params = {
        "include": "pop_reports"
    }
    headers = {
        "X-Api-Key": "YOUR_API_KEY"
    }
    response = requests.get(url, params=params, headers=headers)
    data = response.json()
    print(data['data']['variants'][0]['pop_reports'])

const axios = require('axios');

const getCardWithPopReports = async (cardId) => {
  try {
    const response = await axios.get(`https://api.scrydex.com/pokemon/v1/cards/${cardId}`, {
      params: {
        include: 'pop_reports'
      },
      headers: {
        'X-Api-Key': 'YOUR_API_KEY'
      }
    });
    console.log(response.data.data.variants[0].pop_reports);
  } catch (error) {
    console.error(error);
  }
};