Docs
API referenceCards

Suggest prints for free text

Autocomplete over prints: the prints that best match what the user typed, best first. It tolerates a misspelled name, reads `printed_name`, and understands the collector number as the card prints it. Words can be combined, as in `pikachu 58/102` or `charizard base`: a print that more words match ranks higher. Prints with the same score are ordered by `id`, so the same request always returns the same body. With several games, prints that match more words in full come first, from any game. Among prints that match as many words in full, the games take turns: the best print of each game, then the second of each game, and so on. A full match in one game therefore ranks above a misspelling in another. The response is the list envelope of `GET /v1/cards` with whole cards, and never has a next page: `has_more` is always false. Use `GET /v1/cards` to page through a catalogue. An unknown query parameter returns 400 (`unknown_parameter`).

Autocomplete over prints: the prints that best match what the user typed, best first. It tolerates a misspelled name, reads printed_name, and understands the collector number as the card prints it. Words can be combined, as in pikachu 58/102 or charizard base: a print that more words match ranks higher. Prints with the same score are ordered by id, so the same request always returns the same body.

With several games, prints that match more words in full come first, from any game. Among prints that match as many words in full, the games take turns: the best print of each game, then the second of each game, and so on. A full match in one game therefore ranks above a misspelling in another.

The response is the list envelope of GET /v1/cards with whole cards, and never has a next page: has_more is always false. Use GET /v1/cards to page through a catalogue. An unknown query parameter returns 400 (unknown_parameter).

Authorization

ApiKey
headerAuthorizationBearer <rar_live_*>

Send Authorization: Bearer rar_live_..., or use rar_test_... for a test key. Both lanes currently read the same catalogue. Without a key you stay in the anonymous lane: 30 requests/minute and 1,000/day, against 60/minute per key and 2,000/day per organization with one on the Free plan. Sending a key that is malformed, revoked or unknown is a 401; sending none is not.

Query Parameters

q*string

What the user is typing: free text, not the query language of GET /v1/cards. Words are separated by spaces. Each word can match the start of a word of the name, any part of printed_name, a misspelled name, the collector number as printed, or the set by code or by a whole word of its name. A word of one character matches only a whole word of the name, as the V of pikachu v. A repeated word counts once.

Numbers ignore case and the leading zeros of each group of digits: 4/102 matches 004/102, sv1 matches SV001. A word with a slash must match the total after it too.

At most 20 words and 512 characters; exceeding either returns 400.

Match^[^\u0000-\u001f\u007f-\u009f]*[^\u0000-\u001f\u007f-\u009f\s][^\u0000-\u001f\u007f-\u009f]*$
Lengthlength <= 512
game*array<>

Game code, as returned in a card's game. Repeatable, to suggest from several games in one call: ?game=pokemon&game=one_piece. The order of the values and their repeats do not change the answer. A game without prints answers nothing.

Items1 <= items <= 10
lang?string

Language of the print. Omit it to suggest prints in every language.

Match^[^\u0000-\u001f\u007f-\u009f]*[^\u0000-\u001f\u007f-\u009f\s][^\u0000-\u001f\u007f-\u009f]*$
limit?integer

Prints to return. Safe integers are clamped to 1-20, not rejected.

Range-9007199254740991 <= value <= 9007199254740991
Default10

Response Body

The best matches. Zero matches = 200 with data: [].

application/json
  1. response

List envelope. Zero results is a 200 with data: [], never a 404.

object*string
data*array<>
has_more*boolean

The only end-of-pagination signal.

next_cursor*|

Present and non-null if and only if has_more is true.

total?|

An estimate. Never use it as a termination signal.

warnings?array<string>

Non-fatal channel: query terms that were ignored.

Example Request
cURL
curl -X GET 'https://api.rarity.dev/v1/cards/suggest?q=charizrd&game=one_piece' \  -A 'my-app/1.0 (you@example.com)'
Example Response
{  "object": "list",  "data": [    {      "object": "card",      "id": "string",      "oracle_id": "string",      "illustration_id": "string",      "external_ids": {        "tcgplayer": 610429,        "cardmarket": 801001      },      "lang": "string",      "layout": "string",      "uri": "http://example.com",      "livemode": true,      "updated_at": "2019-08-24T14:15:22Z",      "name": "string",      "text": "string",      "colors": [        "string"      ],      "types": [        "string"      ],      "legalities": [        {          "format": "string",          "status": "string",          "since": "string"        }      ],      "faces": [        {          "face_type": "string",          "name": "string",          "text": "string",          "image": "http://example.com",          "illustration_id": "string",          "attributes": {            "property1": null,            "property2": null          }        }      ],      "printed_name": "リザードンex",      "set": "string",      "collector_number": "string",      "rarity": "sr",      "category": "string",      "illustrator": "string",      "products": [        "string"      ],      "variant": {        "type": "string",        "of": "string",        "treatment": [          "string"        ]      },      "image": "http://example.com",      "image_status": "missing",      "prices": {        "cardmarket": {          "currency": "eur",          "updated_at": "2019-08-24T14:15:22Z",          "finishes": {            "property1": {              "trend": -9007199254740991,              "avg": -9007199254740991,              "low": -9007199254740991,              "avg1": -9007199254740991,              "avg7": -9007199254740991,              "avg30": -9007199254740991            },            "property2": {              "trend": -9007199254740991,              "avg": -9007199254740991,              "low": -9007199254740991,              "avg1": -9007199254740991,              "avg7": -9007199254740991,              "avg30": -9007199254740991            }          }        },        "tcgplayer": {          "currency": "usd",          "updated_at": "2019-08-24T14:15:22Z",          "finishes": {            "property1": {              "market": -9007199254740991,              "low": -9007199254740991,              "mid": -9007199254740991,              "high": -9007199254740991,              "direct_low": -9007199254740991            },            "property2": {              "market": -9007199254740991,              "low": -9007199254740991,              "mid": -9007199254740991,              "high": -9007199254740991,              "direct_low": -9007199254740991            }          }        },        "pricecharting": {          "currency": "usd",          "updated_at": "2019-08-24T14:15:22Z",          "grades": {            "1": -9007199254740991,            "2": -9007199254740991,            "3": -9007199254740991,            "4": -9007199254740991,            "5": -9007199254740991,            "6": -9007199254740991,            "7": -9007199254740991,            "8": -9007199254740991,            "9": -9007199254740991,            "ungraded": -9007199254740991,            "9.5": -9007199254740991,            "psa_10": -9007199254740991,            "bgs_10": -9007199254740991,            "cgc_10": -9007199254740991,            "sgc_10": -9007199254740991,            "cgc_10_pristine": -9007199254740991,            "bgs_10_black": -9007199254740991,            "tag_10": -9007199254740991,            "ace_10": -9007199254740991          }        }      },      "source_url": "http://example.com",      "game": "dragon_ball_fusion_world",      "attributes": {        "property1": null,        "property2": null,        "counter": "string",        "attributes": [          "string"        ],        "block": "string",        "trigger": "string",        "upgrade_power": "string",        "upgrade_hp": "string",        "subtitle": "string",        "unique": true,        "arenas": [          "string"        ],        "keywords": [          "string"        ],        "unit_type": "string",        "deploy_box": "string",        "epic_action": "string",        "dmg": "string",        "life": "string",        "hp": "string",        "type": "string",        "stage": "string",        "attacks": [          {            "cost": "string",            "name": "string",            "damage": "string",            "text": "string"          }        ],        "abilities": [          {            "kind": "string",            "name": "string",            "text": "string"          }        ],        "weakness": "string",        "resistance": "string",        "retreat_cost": "string",        "card_type": "string",        "colors": [          "string"        ],        "cost": "string",        "specified_cost": "string",        "power": "string",        "combo_power": "string",        "traits": [          "string"        ]      }    }  ],  "total": -9007199254740991,  "warnings": [    "string"  ],  "has_more": true,  "next_cursor": "string"}

Search cards GET

Cursor-paginated search. Zero results is a 200, not a 404. Filters combine with AND across parameters. Within one parameter, `set`, `rarity` and `category` match any of the values given, while `color` and `type` require all of them. `rarity`, `color` and `type` have a vocabulary that belongs to a single game: send `game` with them, or the answer is narrower than it looks and costs a scan of every other game.

Retrieve a game GET

Returns the game's policy, formats and `attributes` JSON Schema. Generic clients can read `attributes_schema` to build game-specific filters without hardcoding publisher fields.