> ## 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. # Search (Structured) > Full-text search across cards. Returns matches grouped by grading company. This endpoint is for structured data. For optimal results submit entries in the format: ` `. Use it when your queries come programmatically from a catalog or directly from a grader website. For user-submitted or loosely structured text (e.g. marketplace listings), use [`GET /v1/cards/search/simple`](/api-reference/cards/search-simple) instead. ## OpenAPI ````yaml /openapi.yaml get /v1/cards/search/structured 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/search/structured: get: tags: - Cards summary: Search (Structured) description: > Full-text search across cards. Returns matches grouped by grading company. This endpoint is for structured data. For optimal results submit entries in the format: ` `. Use it when your queries come programmatically from a catalog or directly from a grader website. For user-submitted or loosely structured text (e.g. marketplace listings), use [`GET /v1/cards/search/simple`](/api-reference/cards/search-simple) instead. operationId: searchCardsStructured parameters: - name: query in: query required: true description: >- The search text. Case-agnostic, no typo tolerance. Use the structured format for best results ` `. schema: type: string example: 1986 Fleer Michael Jordan 57 - name: grader in: query description: Restrict results to a single grading company. required: false schema: $ref: '#/components/schemas/Grader' responses: '200': description: Matching cards (possibly empty). content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/StructuredSearchResults' meta: $ref: '#/components/schemas/Meta' example: data: query: 1986 fleer michael jordan 57 graders_included: - psa - beckett - sgc - cgc results: psa: - description: 1986 Fleer Michael Jordan 57 gemrate_id: 25b4432f12a5d6ec29a6f00490200416d5dfa242 population: 30978 search_score: 146.3 - description: >- 2006 Fleer Buyback Michael Jordan 1986 Fleer-Autograph 57 gemrate_id: 31853ea7b52c551e817c3e5707f75f7d35de9559 population: 4 search_score: 128.4 - description: 1986 Fleer Sticker Michael Jordan 8 gemrate_id: f92c23d15fb6ee24539aeb34dd82a4a6bf61b876 population: 23762 search_score: 106.4 beckett: - description: 1986 Fleer Michael Jordan RC 57 gemrate_id: 7a70aeda7692bf7c24a1b8def12e5afed61c5761 population: 14971 search_score: 143.9 - description: 1986 Fleer Stickers Michael Jordan 8 gemrate_id: 1d9960d4834316c4f2c14dfbd95ac96384afd352 population: 7873 search_score: 103.7 sgc: - description: 1986 Fleer Michael Jordan 57 gemrate_id: 33a95ad34c7e119fd4a3fd6235019d1893feb630 population: 4517 search_score: 140.4 - description: 1986 Fleer Sticker Michael Jordan 8 gemrate_id: f0de396a7e167121df7151c33916737af6b8bdf6 population: 3383 search_score: 101 cgc: - description: 1986 Fleer Michael Jordan 57 gemrate_id: 408287c2bd6c833dde92eb99662064a9f65afbbf population: 191 search_score: 137.6 - description: 1986 Fleer Stickers Michael Jordan 8 gemrate_id: 082c6859af308d2709d5064266c4b6d54f2a039e population: 183 search_score: 98.9 meta: request_id: req_abc123 '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/ServerError' components: schemas: Grader: type: string description: | The grading company. enum: - psa - beckett - sgc - cgc example: psa StructuredSearchResults: type: object description: The result set for a structured search, grouped by grading company. properties: query: type: string description: The query as interpreted by the search engine. example: 1986 fleer michael jordan 57 graders_included: type: array description: The grading companies represented in `results`. items: $ref: '#/components/schemas/Grader' results: type: object description: > Matches keyed by grading company. Each value is a list of matches for that grader, ordered best-match first. additionalProperties: type: array items: $ref: '#/components/schemas/StructuredSearchMatch' required: - query - graders_included - results 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 StructuredSearchMatch: type: object description: A single card matched by a structured search. properties: description: type: string description: The card's canonical description. example: 1986 Fleer Michael Jordan 57 gemrate_id: type: string description: The card's GemRate id — use it with the card lookup endpoints. example: 25b4432f12a5d6ec29a6f00490200416d5dfa242 population: type: integer description: Total graded population for this card at this grader. example: 30978 search_score: type: number description: >- Relevance score for this match; higher is a closer match. These should not be used to compare listings across graders or across queries. example: 146.3 required: - description - gemrate_id - population - search_score 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 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 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 ````