Coverage & combinations

Coverage

There is no separate endpoint for the list of retailers or the list of categories — GET /v1/coverage is how you see what exists, and it returns one row per RCD combination: a retailer, a category, and the department that category sits under.

Field	Meaning
retailer	Retailer slug
department	Department slug
category	Category slug, scoped within department
rcd	retailer:category:department, ready to reuse as the rcd filter elsewhere
corpus_rows	Total rows this combination holds
matching_rows	Rows in this combination that also match any start_date/end_date you sent
earliest_date	Earliest crawl_date among the matching rows
latest_date	Most recent crawl_date among the matching rows

Call it with no filters and you get every combination your team can see — that's the full retailer/category/department vocabulary, since there's no dedicated endpoint for retailers or categories on their own anymore. Narrow it with retailer, category, department, or rcd to see just the combinations you care about.

rcd: the combination as one value

rcd is the shorthand for a combination: retailer:category:department, comma-separated when you mean more than one. It's exactly the string GET /v1/coverage gives back in each row's rcd field — copy it straight into /v1/sample, /v1/catalog, or /v1/coverage instead of naming retailer, category, and department separately:

GET /v1/coverage?rcd=home_depot:power_tools:tools,home_depot:hand_tools:tools

meta.coverage: coverage without a separate call

Every response from every endpoint — /v1/sample, /v1/catalog, and /v1/coverage itself — carries a coverage block in meta, summed across whatever combinations your filters matched:

{ "combinations": 1, "matching_rows": 6, "corpus_rows": 2361, "earliest_date": "2026-06-14", "latest_date": "2026-08-14" }

That's the same shape aggregated: combinations is how many RCD rows matched, matching_rows and corpus_rows are summed across them, and the dates span all of them. One request tells you both what you got and how much exists — see Requests.

Not a required first step

Coverage is useful before a large pull — it answers "does this window have enough rows before I spend a call finding out" — but nothing here gates anything else. /v1/sample and /v1/catalog work with filters you already know, with no coverage call in between. Guess wrong and you get valid_options naming the real values instead of a working result — that's the only vocabulary lookup this API needs, and it works from any of the three endpoints, not just this one. See Error handling.