Skip to main content

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. Requests decide what we add.