> ## 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 spec > Shortcut function to get a card's population by its spec. Resolves the spec to its card and returns the card's full `population` block. Same population data as [`GET /v1/cards/{id}/population`](/api-reference/cards/get-population-for-a-card), reached from a spec instead of a GemRate ID. If the spec is known but its card mapping is still being built, you'll get a `202` — retry shortly. ## OpenAPI ````yaml /openapi.yaml get /v1/specs/{grader}/{spec_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/specs/{grader}/{spec_id}/population: get: tags: - Specs summary: Get population for a spec description: > Shortcut function to get a card's population by its spec. Resolves the spec to its card and returns the card's full `population` block. Same population data as [`GET /v1/cards/{id}/population`](/api-reference/cards/get-population-for-a-card), reached from a spec instead of a GemRate ID. If the spec is known but its card mapping is still being built, you'll get a `202` — retry shortly. operationId: getSpecPopulation parameters: - name: grader in: path required: true description: Only `psa` is supported for spec lookups. schema: type: string enum: - psa example: psa - name: spec_id in: path required: true description: >- The grading company's identifier for the card (PSA spec number, Beckett price-item id, etc.). schema: type: string example: '299576' - $ref: '#/components/parameters/AutoFlag' - $ref: '#/components/parameters/AllGradersFlag' - $ref: '#/components/parameters/ParsedDescriptionFlag' responses: '200': description: >- The card the spec maps to, with its full population (and a `spec` echo). content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/SpecPopulation' 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 grader: psa spec_id: '299576' 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: local '202': description: >- The spec is known but its card mapping is still being built — retry shortly. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: processing message: Still linking this spec to a card; retry shortly. meta: request_id: req_abc123 '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': description: No card maps to the given spec. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: card_not_found message: No card maps to the given spec. meta: request_id: req_abc123 '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/ServerError' components: parameters: 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 AllGradersFlag: name: all_graders in: query required: false description: > Defaults to `true` — the `population` block covers every grader the card has. Set `false` to restrict it to the grader that owns this cert/spec (the `{grader}` path segment): `by_grader` then holds only that grader and the top-level `total`/`gem_total`/`gem_rate` reflect it alone. Must be `true` or `false`; any other value returns `400 invalid_parameter`. schema: type: boolean default: true 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: SpecPopulation: description: > A spec resolved to its card — the identity triplet and the (normalized) `grader`/`spec_id` that resolved (mirroring the cert shape), then the full Card with population. allOf: - $ref: '#/components/schemas/CardIdentity' - type: object properties: grader: type: string enum: - psa description: Only `psa` is supported for spec lookups. example: psa spec_id: type: string required: - grader - spec_id 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 CardIdentity: type: object description: > A card's identity (the GemRate entity), without population. `description` is the human-readable name; pass `?parsed_description=true` for its components. 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 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 `universal_gemrate_id` (falling back to `gemrate_id`). parsed_description: allOf: - $ref: '#/components/schemas/ParsedDescription' description: Present only with `?parsed_description=true`. required: - description - universal_gemrate_id - gemrate_id - is_universal_match - gemrate_url 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 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 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 ````