> ## Documentation Index > Fetch the complete documentation index at: https://docs.gemrate.com/llms.txt > Use this file to discover all available pages before exploring further. # Get population for a card > Returns a card's metadata and its current population summary, identified by its [GemRate ID](/gemrate-id). The `population` block wraps `graders_included`, a per-grader `graders` identity object (each grader's `gemrate_id`/`spec_id`/`set_url`), and `population_data`. ## OpenAPI ````yaml /openapi.yaml get /v1/cards/{gemrate_id}/population openapi: 3.0.3 info: title: GemRate API version: '1.0' description: > The GemRate API gives you programmatic access to graded trading-card data: look up a specific cert, get population reports and their history, look up and search for cards, and download bulk catalogs. ## Quickstart 1. **Get an API key.** Contact the GemRate team to request one. 2. **Send it on every request** in the `x-api-key` header. 3. **Make a call:** ```bash curl https://api.gemrate.com/v1/certs/psa/47178561 \ -H "x-api-key: YOUR_API_KEY" ``` ```json { "data": { "description": "1986 Fleer Michael Jordan 57", "universal_gemrate_id": "25b4432f12a5d6ec29a6f00490200416d5dfa242", "gemrate_id": "25b4432f12a5d6ec29a6f00490200416d5dfa242", "is_universal_match": true, "gemrate_url": "https://gemrate.com/card/25b4432f12a5d6ec29a6f00490200416d5dfa242", "grader": "psa", "grader_data": { "cert": "47178561", "grade": "psa_5", "grade_label": "5", "set_url": "https://www.psacard.com/pop/basketball-cards/1986/fleer/36766", "population_context": { "grade_population": 2080, "population_higher": 22520, "total_population": 30810, "gem_total": 340, "gem_rate": 0.011 }, "spec_id": "299576" } }, "meta": { "request_id": "req_abc123" } } ``` Shared identity fields sit at the top level; everything specific to the grading company (grade, links, and grader-specific extras) is nested under `grader_data`. A cert is a specific graded copy of a card; the `gemrate_id` in the response points to that card, which you can then explore via the `/v1/cards` endpoints. ## Base URL All routes live under the `/v1` version prefix: ``` https://api.gemrate.com/v1 ``` All endpoints are served over HTTPS. Reads are `GET` requests. The contract evolves additive-only within `v1`; a genuinely incompatible change would ship as a parallel `/v2`. ## Authentication Pass your key in the `x-api-key` header on every request: ``` x-api-key: YOUR_API_KEY ``` - Missing or invalid key → `401`. - Valid key without access to a resource → `403`. ## Response shape Every successful response is an object with two top-level keys: - `data` — the result (an object, or an array for list endpoints). - `meta` — metadata, always including a `request_id` you can quote in support requests. ```json { "data": { }, "meta": { "request_id": "req_abc123" } } ``` ## Lean payloads and sub-resources Cert and spec lookups return a lean default payload (identity only). Heavier data lives on dedicated sub-resource endpoints — population and images each have their own URL: ```bash curl "https://api.gemrate.com/v1/certs/psa/47178561/population" \ -H "x-api-key: YOUR_API_KEY" ``` ## Errors Errors return a non-2xx status and a body with a stable, machine-readable `code` you can branch on (the `message` is for humans and may change): ```json { "error": { "code": "cert_not_found", "message": "No PSA cert found for cert 12345678.", "details": { "grader": "psa", "cert": "12345678" } }, "meta": { "request_id": "req_abc123" } } ``` | Status | When | |--------|------| | `200` | Success (including an empty list — `data: []`). | | `202` | Accepted, but still processing — retry shortly. | | `400` | Your request was malformed or invalid. | | `401` | Missing or invalid API key. | | `403` | Your key isn't allowed to access this resource. | | `404` | The specific item you asked for doesn't exist in our data. | | `429` | You've hit the rate limit — slow down. | | `500` | Something went wrong on our end. | ## Conventions - JSON field and query-parameter names use `snake_case`. - Dates are `YYYY-MM-DD`; timestamps are ISO-8601 UTC. - Booleans in the query string are the strings `true` / `false`. servers: - url: https://api.gemrate.com description: Production security: - ApiKeyAuth: [] tags: - name: Cards description: >- The card itself (one gemrate_id) — its population, history, search, and the population change feed. - name: Certs description: A specific graded copy of a card, identified by grader and cert number. - name: Specs description: A grading company's catalog entry for a card; resolves to the card. - name: Catalogs description: Bulk CSV downloads of graded-card data. - name: Grades description: The grade map — each grade's per-grader label keys and display names. paths: /v1/cards/{gemrate_id}/population: get: tags: - Cards summary: Get population for a card description: > Returns a card's metadata and its current population summary, identified by its [GemRate ID](/gemrate-id). The `population` block wraps `graders_included`, a per-grader `graders` identity object (each grader's `gemrate_id`/`spec_id`/`set_url`), and `population_data`. operationId: getCard parameters: - $ref: '#/components/parameters/GemrateId' - $ref: '#/components/parameters/AutoFlag' - $ref: '#/components/parameters/ParsedDescriptionFlag' - name: grader in: query required: false description: Return population data only for the specified grader. schema: $ref: '#/components/schemas/Grader' responses: '200': description: The card and its current population. content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/Card' meta: $ref: '#/components/schemas/Meta' example: data: description: 1986 Fleer Michael Jordan Base 57 universal_gemrate_id: 25b4432f12a5d6ec29a6f00490200416d5dfa242 gemrate_id: 25b4432f12a5d6ec29a6f00490200416d5dfa242 is_universal_match: true gemrate_url: >- https://gemrate.com/card/25b4432f12a5d6ec29a6f00490200416d5dfa242 population: graders_included: - psa - beckett - sgc - cgc graders: psa: gemrate_id: 25b4432f12a5d6ec29a6f00490200416d5dfa242 spec_id: '299576' set_url: >- https://www.psacard.com/pop/basketball-cards/1986/fleer/36766 beckett: gemrate_id: 7a70aeda7692bf7c24a1b8def12e5afed61c5761 set_url: https://www.beckett.com/grading/set_match/3022391 sgc: gemrate_id: 33a95ad34c7e119fd4a3fd6235019d1893feb630 set_url: >- https://gosgc.com/pop-report/result/1986-87%20Fleer/Basketball cgc: gemrate_id: 408287c2bd6c833dde92eb99662064a9f65afbbf set_url: >- https://www.cgccards.com/population-report/sports/basketball/3/1980s/32/1986-87-fleer/26933/ population_data: total: 50437 gem_total: 924 gem_rate: 0.0183 data_last_updated: '2026-06-24' last_population_change: '2026-06-24' by_grader: psa: total: 30810 gem_total: 340 gem_rate: 0.011 last_population_change: '2026-06-24' grades: psa_auth: 993 psa_1: 454 psa_1_5: 169 psa_2: 534 psa_2_5: 57 psa_3: 943 psa_3_5: 78 psa_4: 1722 psa_4_5: 126 psa_5: 2080 psa_5_5: 161 psa_6: 3244 psa_6_5: 217 psa_7: 5107 psa_7_5: 323 psa_8: 9336 psa_8_5: 713 psa_9: 3079 psa_10: 340 qualifiers: psa_q1: 13 psa_q1_5: 0 psa_q2: 4 psa_q3: 2 psa_q4: 9 psa_q5: 7 psa_q6: 8 psa_q7: 62 psa_q8: 635 psa_q9: 394 beckett: total: 14942 gem_total: 554 gem_rate: 0.0371 last_population_change: '2026-06-24' grades: beckett_1: 10 beckett_1_5: 42 beckett_2: 61 beckett_2_5: 91 beckett_3: 136 beckett_3_5: 180 beckett_4: 299 beckett_4_5: 262 beckett_5: 349 beckett_5_5: 405 beckett_6: 576 beckett_6_5: 818 beckett_7: 1279 beckett_7_5: 1902 beckett_8: 2724 beckett_8_5: 3310 beckett_9: 1944 beckett_9_5: 548 beckett_10_pristine: 6 beckett_10_black: 0 sgc: total: 4498 gem_total: 29 gem_rate: 0.0064 last_population_change: '2026-06-24' grades: sgc_auth: 740 sgc_1: 46 sgc_1_5: 29 sgc_2: 52 sgc_2_5: 39 sgc_3: 139 sgc_3_5: 43 sgc_4: 216 sgc_4_5: 126 sgc_5: 313 sgc_5_5: 182 sgc_6: 383 sgc_6_5: 192 sgc_7: 476 sgc_7_5: 312 sgc_8: 506 sgc_8_5: 406 sgc_9: 236 sgc_9_5: 33 sgc_10: 28 sgc_10_pristine: 1 cgc: total: 187 gem_total: 1 gem_rate: 0.0053 last_population_change: '2026-06-24' grades: cgc_auth_altered: 34 cgc_auth: 5 cgc_1: 4 cgc_1_5: 5 cgc_2: 2 cgc_2_5: 1 cgc_3: 7 cgc_3_5: 3 cgc_4: 6 cgc_4_5: 2 cgc_5: 14 cgc_5_5: 3 cgc_6: 16 cgc_6_5: 13 cgc_7: 12 cgc_7_5: 16 cgc_8: 18 cgc_8_5: 14 cgc_9: 9 cgc_9_5: 2 cgc_10: 1 cgc_10_pristine: 0 cgc_10_perfect: 0 meta: request_id: req_abc123 '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': description: We have no card for this [GemRate ID](/gemrate-id). content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: card_not_found message: No card found for the requested gemrate_id. meta: request_id: req_abc123 '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/ServerError' components: parameters: GemrateId: name: gemrate_id in: path required: true description: >- GemRate's universal identifier for a card (returned by cert and spec lookups). schema: type: string example: 25b4432f12a5d6ec29a6f00490200416d5dfa242 AutoFlag: name: auto_split in: query required: false description: > When true, adds a PSA-only auto_split object ({auto, non_auto} breakdowns) to the PSA `population_data.by_grader.psa` block. Its sub-blocks are zero-filled when the card has no PSA autographed grades (the object itself is always present when the flag is set). Must be `true` or `false`; any other value returns `400 invalid_parameter`. schema: type: boolean ParsedDescriptionFlag: name: parsed_description in: query required: false description: > When `true`, adds a `parsed_description` object that breaks the card's `description` into its catalog components for each grader (category, year, set_name, name, card_number, parallel, subset). Must be `true` or `false`; any other value returns `400 invalid_parameter`. schema: type: boolean schemas: Grader: type: string description: | The grading company. enum: - psa - beckett - sgc - cgc example: psa Card: type: object description: > A card (the GemRate entity) and its current population. At the top level, it carries identity information for the card. All additional data is in the `population` block. properties: description: type: string universal_gemrate_id: type: string nullable: true description: >- The universal card id; always present, `null` if the card is not universally matched. gemrate_id: type: string nullable: false description: >- The card id passed to the endpoint; sometimes matching the `universal_gemrate_id`. is_universal_match: type: boolean description: >- Whether the card is universally matched (equivalent to `universal_gemrate_id` being non-null). gemrate_url: type: string description: >- Link to the card's page on gemrate.com, built from the card's `gemrate_id`. population: $ref: '#/components/schemas/CardPopulation' required: - description - universal_gemrate_id - gemrate_id - is_universal_match - gemrate_url - population Meta: type: object description: Metadata attached to every response. properties: request_id: type: string description: A unique ID for this request; quote it in support requests. example: req_abc123 required: - request_id Error: type: object properties: error: type: object properties: code: $ref: '#/components/schemas/ErrorCode' message: type: string description: A human-readable description. May change; don't parse it. details: type: object description: Optional structured context about the error. additionalProperties: true required: - code - message meta: $ref: '#/components/schemas/Meta' required: - error CardPopulation: type: object description: > The `population` block, shared by the card, spec-population, and cert-population endpoints. Wraps `graders_included`, a per-grader `graders` identity object, and the `population_data` counts payload. properties: graders_included: type: array items: $ref: '#/components/schemas/Grader' description: The graders present in `graders` / `population_data.by_grader`. graders: type: object description: > Static per-grader identity keyed by grader id — each grader's `gemrate_id`, `spec_id`, `set_url`, and (with `?parsed_description=true`) its own `parsed_description`. additionalProperties: $ref: '#/components/schemas/GraderMeta' population_data: $ref: '#/components/schemas/PopulationData' required: - graders_included - graders - population_data ErrorCode: type: string description: >- A stable, machine-readable error code. Branch on this. Tolerate new values. enum: - invalid_grader - invalid_cert - invalid_parameter - invalid_date_range - cert_not_found - card_not_found - spec_not_found - unauthorized - forbidden - rate_limited - processing - internal_error GraderMeta: type: object description: > Static identity for one grader's series — the non-count fields the population endpoint carries per grader. `gemrate_id` is the grader's own id (its universal-member id on a universal card). properties: gemrate_id: type: string spec_id: type: string nullable: true set_url: type: string format: uri nullable: true parsed_description: allOf: - $ref: '#/components/schemas/ParsedDescription' description: > Present only with `?parsed_description=true` — this grader's own descriptor broken into catalog components. required: - gemrate_id - spec_id - set_url PopulationData: type: object description: > The counts payload inside a `population` block. `total`/`gem_total`/`gem_rate` are scalar sums across all graders; the per-grade breakdown lives under each `by_grader` entry, keyed by that grader's own label keys. Per-grader identity (`spec_id`/`set_url`/…) lives in the sibling `graders` object, not here. properties: total: type: integer gem_total: type: integer gem_rate: type: number data_last_updated: type: string nullable: true description: > The dataset's global last-updated marker — the newest `last_population_change` across the whole population collection. The same for every card; distinct from this card's own `last_population_change`. last_population_change: type: string nullable: true by_grader: type: object description: >- Per-grader counts keyed by grader id (`psa`, `beckett`, `sgc`, `cgc`). additionalProperties: $ref: '#/components/schemas/GraderBreakdown' required: - total - gem_total - gem_rate - by_grader ParsedDescription: type: object description: > A card's `description` broken into its catalog components. Returned only when `?parsed_description=true`. properties: category: type: string nullable: true year: type: string nullable: true set_name: type: string nullable: true name: type: string nullable: true card_number: type: string nullable: true parallel: type: string nullable: true subset: type: string nullable: true GraderBreakdown: description: > One grader's counts inside `population_data.by_grader` — a `PopulationBreakdown` plus that grader's own `last_population_change`. Counts only; identity lives in the sibling `graders` object. allOf: - type: object properties: total: type: integer gem_total: type: integer gem_rate: type: number last_population_change: type: string nullable: true grades: $ref: '#/components/schemas/GradeCounts' qualifiers: $ref: '#/components/schemas/Qualifiers' auto_split: type: object description: > **PSA only.** Autographed/non-autographed split of this grader's counts, added to the `by_grader.psa` entry with `?auto_split=true`. Both sub-blocks are zero-filled when the card has no autographed grades (the object itself is always present when the flag is set). Absent for other graders and when the flag is not set. properties: auto: allOf: - $ref: '#/components/schemas/PopulationBreakdown' description: Autographed copies' breakdown. non_auto: allOf: - $ref: '#/components/schemas/PopulationBreakdown' description: Non-autographed copies' breakdown. GradeCounts: type: object description: > Population counts keyed by the grader's **label keys** (`{grader}_{grade}`, e.g. `psa_8`, `psa_10`, `beckett_9_5`, `cgc_10_perfect`). additionalProperties: type: integer example: psa_8: 21073 psa_9: 50741 psa_10: 156 Qualifiers: type: object nullable: true description: > PSA-only qualifier counts keyed by the grader's qualifier label keys (`psa_q1`, `psa_q1_5`, `psa_q2`…`psa_q9`). `null` for graders with no qualifier axis (beckett, sgc, cgc). additionalProperties: type: integer example: psa_q8: 30 psa_q9: 75 PopulationBreakdown: type: object description: >- A population breakdown keyed by a grader's label keys (the PSA `auto_split` sub-blocks share this shape). properties: total: type: integer gem_total: type: integer description: Count at this grader's gem tiers (gem mint and above). gem_rate: type: number grades: $ref: '#/components/schemas/GradeCounts' qualifiers: $ref: '#/components/schemas/Qualifiers' responses: BadRequest: description: Your request was malformed or invalid. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: invalid_grader message: Unknown grader 'foo'. meta: request_id: req_abc123 Unauthorized: description: Missing or invalid API key. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: unauthorized message: Missing or invalid API key. meta: request_id: req_abc123 Forbidden: description: Your key isn't allowed to access this resource. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: forbidden message: Your key does not have access to this resource. meta: request_id: req_abc123 RateLimited: description: You've hit the rate limit — slow down. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: rate_limited message: Too many requests. meta: request_id: req_abc123 ServerError: description: Something went wrong on our end. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: internal_error message: Something went wrong. meta: request_id: req_abc123 securitySchemes: ApiKeyAuth: type: apiKey in: header name: x-api-key ````