Vergio

Public data endpoints

Every statistic published on Vergio Data is available as JSON and CSV. These endpoints are public: no API key, no workspace scope. The data is licensed CC BY 4.0, attribution to Vergio with a link.

Endpoints

  • GET /api/data/{slug}: the latest published month, every stat on that page.
  • GET /api/data/{slug}/{month}: one specific published month (YYYY-MM). Returns 404 for a month that was never published.
  • GET /api/data/{slug}/csv: the full monthly series as CSV, one row per metric, dimension, and month.

Valid {slug} values: shopify-stores, agentic-commerce, shopify-apps, shopify-advertising, shopify-trends, methodology.

Query strings are rejected: any request with a non-empty query string returns 404. This keeps the CDN cache key space bounded.

JSON shape

Both JSON endpoints return the same shape: schema_version (currently 1), slug, month, completed_at, license, and stats. Each stat carries id, metric_key, dimension, canonical_url, anchor, value, numerator, n, null_rate, suppressed, delta, definition, sentence, citation, month, and methodology_version. The schema_version field only changes on a breaking shape change, so a consumer can pin against it.

A suppressed stat (sample below the publication floor of 30 stores) serializes value, n, and numerator as null with suppressed: true. No published figure ever has n below 30.

CSV shape

Columns: metric_key, dimension, month, value, numerator, n, null_rate, suppressed, delta_value, delta_cohort_n, delta_suppressed, methodology_version. Cells are RFC 4180 quoted, and any text cell starting with =, +, -, or @ is prefixed with an apostrophe so spreadsheet apps read it as text, never as a formula. Plain numeric cells (including negative deltas) are never prefixed, so numeric columns stay numeric.

Caching

Responses carry Cache-Control: public, s-maxage=3600 plus ETag and Last-Modified. The JSON ETags derive from the underlying run; the CSV ETag reflects the file content itself, so a correction to any past month rotates it. Conditional requests with If-None-Match return 304. Data updates monthly, shortly after month end.

Related surfaces

  • Every /data page is also raw markdown at its .md URL, for example https://vergio.ai/data/shopify-stores.md.
  • Every published stat has a shareable PNG card, reachable via the image URL inside its embed snippet on the page.
  • https://vergio.ai/data/rss.xml announces each monthly release.
Is this page helpful?