> ## Documentation Index
> Fetch the complete documentation index at: https://syntalic.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Coverage

> Which retailers, which countries, and how fresh the data is.

## Geography

United States and Canada. Pick the market with the `country` parameter (`us` or `ca`, default `us`). Social data isn't split by country.

## Retailers

The catalog includes major retail chains and independent online stores, including Shopify storefronts. Use the free discovery routes below for current counts. Some entries, such as Shopify, are platforms that cover many independent stores rather than a single merchant.

Coverage differs by retailer, country and category. Check before you spend:

* `GET /v1/public/stats`: catalog totals and update time. Free.
* `GET /v1/public/retailers`: platform coverage, listing counts, countries and freshness. Free; paginate with `limit` and `offset`.
* `GET /v1/public/search?q=olipop`: free catalog search before choosing a paid query.
* `GET /v1/public/brands?q=`: check a brand name is in the catalog before a paid query. Free.
* `GET /v1/public/categories`: browse the category tree with listing counts. Free.
* `GET /v1/public/coverage`: where the catalog is deep or thin, per retailer, country and category. Free.
* `measure_coverage` (or `GET /v1/measures/coverage`): how much evidence stands behind one brand, shelf or product, and which retailers were scanned. \$0.01. Treat a missing listing as evidence only within the scanned scope; it does not prove that a retailer does not sell the product.

## Freshness

Retailers are read on different schedules, so freshness varies by retailer and by product. Offer-level fields, where present, mean:

* `last_read_at` and `age_days` on every offer: when its price was last read.
* `current`: `false` when the offer was last read out of stock and that reading is old (a few sources are exempt from this rule). An in-stock reading stays `current` even when it is old, so check `age_days` and `fresh` too.
* `fresh`: whether the listing was read within its freshness window. Neither flag guarantees live stock or today's checkout price.
* `price_suspect`: a price-quality warning; do not treat flagged prices as reliable bargains.
* `X-Data-Freshness-Hours` on successful responses built from observations: the age in hours of the newest observation behind the answer, or `unknown` when it can't be determined. `X-Data-Stale: true` means that data is older than the endpoint's usual refresh target. Taxonomy and ontology routes report the vocabulary release they used instead (`X-GPC-Release`, `X-Map-Version` or `X-Taxonomy-Release`).

For `best-price`, offers that are not flagged `price_suspect` and are `current`, in stock and `fresh` rank ahead of cheaper offers that aren't. `coverage.reason: no_fresh_in_stock_offer` means the headline is a last-seen price, not one confirmed as buyable now. `retailers_compared: 1` means only one retailer's offer was compared, so this isn't a cross-retailer comparison. A `retailer` value such as `shopify` is a platform, not a single shop; use `store` or `seller`, where present, to identify the merchant. `per_unit` gives a price per unit only when enough of the compared offers state their pack size; the headline `best_price` is always the pack price.

## Interpreting coverage

Shelf share counts observed products, not units sold or revenue. Social mention shares describe the tracked corpus, not the whole platform or consumer population. Check `coverage.sufficient` and `coverage.reason` on responses that include them; empty or unpublished data is not proof of zero activity.

## What's not covered

* Per-store inventory. Stock is reported per listing as in stock or not, not as a count per store.
* Auction-style listings with no fixed price.
* B2B and wholesale pricing.
* Markets outside the US and Canada.

If a retailer or market matters for your use, [tell us](mailto:support@syntalic.com). Requests decide what we add.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.