Skip to main content

Use-case guides

EDITED maintains a public repo of runnable, reusable example code for common build patterns: edited-api-use-case-guides. Each guide is a short, self-contained project — a README that explains the pattern and a Python runner you can clone, configure, and adapt — so you start from something that already works instead of a blank file.

Today's guides target the Query and Jobs APIs. The repo is the home for reusable builder code and grows over time, so treat it as a living reference rather than a fixed set.

What's in the repo​

  • Brand Watchlist — tracks product lifecycle events (new-in, removed, and so on) by brand and category over a time window, from a saved filterset. (Query API.)
  • Colour Trend Tracker — tracks total and newly introduced colours by retailer, gender, product category, and predominant colour. (Query API.)
  • Historical Options — downloads large historical option- and SKU-level datasets (NDJSON.gz) for a filterset across a date range, using the async submit → poll → download job workflow. (Jobs API.)
  • Job Output → Products CSV — turns Jobs API output files into a CSV that mirrors the Products tab of a standard EDITED UI list export. (Jobs API.)
  • Tariff Tracker — tracks pricing and discount architecture (percentiles, buckets, advertised vs. actual) over time by retailer and category — the iterate-and-scale counterpart to EDITED's public Tariff Tracker. (Query API.)

Shared helpers​

All five guides share an editedapi/ package that handles the plumbing you'd otherwise rewrite each time: loading credentials and config, fetching a filterset or schema, submitting and polling a job, running stats queries, and rewinding date ranges. Reuse it as the starting point for your own scripts.

Using a guide​

  1. Clone the repo.
  2. Add your access key to the repo's config.ini (see Authentication). Some guides also read settings like a filterset_id from there — each guide's README lists what it needs.
  3. Run the guide's runner script, then adapt it — they're built to be copied and modified for a different lens (brand, gender, other aggregates).
Keep your access key private

Your key goes in config.ini, which is tracked in the repo — so take care not to commit it back with your key filled in. Treat it like a password; see Authentication.

For the surface mechanics behind these — submitting jobs, paginating results, resolving filter values — see the Query API quickstart and the Jobs API quickstart.