Query syntax

The q parameter takes a Lucene-style query grammar: field:value terms, quoted phrases, AND/OR/NOT, - for exclusion, * and ? wildcards, and [a TO b] ranges. If you have written a Lucene, Elasticsearch or Solr query before, you already know most of it.

This page documents the whole grammar as we implement it — every construct, with the exact behaviour and the exact error. Every example is runnable against this API as written, and every example that is not explicitly marked as matching nothing was checked on 2026-08-27 to return rows.

curl -s -G "https://api.pokemontcgapi.com/v1/cards" \
  --data-urlencode 'q=name:charizard rarity:rare hp:[300 TO *]' \
  -H "X-Api-Key: $PTCG_API_KEY"

Two spellings, and only one of them is a query

This is the single trap on this page, so it comes before the grammar rather than after it.

Field names are matched case-insensitively within the query vocabulary, so set.releasedate and set.releaseDate resolve to the same field. What is not accepted is the response spelling: the underscore, not the capital letter, is what makes set_code unknown. An unknown field is 400 INVALID_QUERY with the token in details.field, its offset in details.position, and the complete accepted list in details.valid_fields — so you never have to hardcode the list below.

The grammar at a glance

Every construct the parser accepts, in one table. Each has its own section below with runnable examples.

Precedence is the standard one: NOT binds tightest, then AND, then OR. Parentheses override it.

Field terms

field:value is the basic unit. Text fields match on substring, case- and accent-insensitively.

Free text

A bare term with no field searches card names two ways at once: a full-text index for whole words and a trigram index for substrings. They are complementary — charizard is found by the first, zard only by the second.

Phrases

Double quotes group words into one term. Inside quotes, * and ? are literal characters rather than wildcards.

Escape a quote inside a phrase with a backslash: set.name:"the \"promo\" set". The parser accepts it; whether anything matches is a separate question.

Boolean operators

Implicit AND

Two adjacent clauses are ANDed. a b and a AND b compile to exactly the same query.

OR and grouping

OR (or ||) widens. Parentheses control precedence, which is the standard Lucene order: NOT binds tightest, then AND, then OR.

Negation

A leading - excludes. NOT does the same thing.

That last row is the subtle one. Negation is null-safe: a card with no rarity still matches -rarity:common. A plain SQL NOT would evaluate to unknown on a null column and drop those rows, which is not what "not common" means to anybody.

Exact match with !

A leading ! promotes a term from "contains" to "is exactly". It is not negation — - is negation — and it is the only way to tell apart values where one contains the other.

! cannot be combined with a range: !hp:[1 TO 100] returns 400 INVALID_QUERY with a message saying so.

Wildcards

* stands for any run of characters, ? for exactly one. Matching is per word, not against the whole field.

Ranges

Ranges work on numeric and date fields. Square brackets are inclusive, curly braces exclusive, and * is an open end.

A range on a text field is 400 QUERY_UNSUPPORTED; a non-integer or impossible date is 400 INVALID_QUERY. Both are deliberate: passing them through would be a database cast error, which is to say a 500 caused by a client mistake.

Nested fields

Dotted names reach into related records and into structured columns. Nothing about the dot is magic — they are ordinary field names.

Set fields

These are the nested fields that carry data across the whole catalogue.

set.id:sv3 matches sv3 and not sv3a: identifier fields always compare whole values, never substrings, even without !. Use a wildcard — set.id:sv3* — when you do want the family.

Legalities

The parser validates the value against legal, banned, restricted and rotated. The column itself is empty catalogue-wide, so rather than answering zero rows the whole field is rejected with 400 and an explanation: a query that silently matches nothing reads as "no card is Standard-legal", which is a different and wronger statement than "we do not hold legalities".

Fields that accept a query but match nothing

A grammar that accepts a field it can never satisfy is a trap, so here is the measurement rather than a promise. On 2026-09-03 we counted, over all 52,337 cards rather than a sample, how many rows carry a non-empty value in each column. The game text arrived that day and it is English, so it sits on the 20,725 Western printings and not on the Japanese and Chinese ones: divide by 20,725 instead of by 52,337 to read these as Western coverage, which for attacks is 83% rather than 33%.

Every searchable field

This is the list the API itself returns in details.valid_fields on a 400 INVALID_QUERY, reproduced verbatim as of 2026-08-27. Thirty-three fields, and nothing else is accepted.

Limits

A query that stops being a search and starts being a load test gets 400 QUERY_TOO_COMPLEX rather than a slow response:

If you are brushing against the clause limit, you are usually looking up a known list of ids — `/v1/cards/batch` does that in one request and one credit per 25 ids.

Worked examples

All five return rows against the live catalogue.

• q=set.code:bs -rarity:common — Base Set without the commons.
• q=rarity:"rare holo" artist:arita — one illustrator’s holos.
• q=(set.code:bs OR set.code:obf) hp:[100 TO *] — the big Pokémon of two sets, 1999 and 2023.
• q=!name:pikachu set.releaseDate:[1999-01-01 TO 2000-12-31] — cards named exactly Pikachu from the first two years.
• q=types:fire set.code:sv3 — where types is populated, it composes like any other field.