{
  "datasetVersion": "1.0.0",
  "datasetId": "verification-coverage",
  "title": "Cosmeds clinic verification coverage",
  "summary": "Published, verified and regulator-registered clinic listing counts for the whole directory, by city and by regulator, plus watchdog stories for the last complete quarter. Counts only — no listing, business or person is identified.",
  "licence": {
    "name": "Creative Commons Attribution 4.0 International (CC BY 4.0)",
    "url": "https://creativecommons.org/licenses/by/4.0/",
    "attribution": "Cosmeds platform open data",
    "statement": "Free to reuse, republish and build on, including commercially, provided the dataset is credited and linked. Credit the source and link to the dataset page."
  },
  "page": "/open-data",
  "catalogue": "/api/open-data/catalogue.json",
  "endpoints": {
    "json": "/api/open-data/verification-coverage.json",
    "schema": "/api/open-data/verification-coverage/schema.json",
    "citiesCsv": "/api/open-data/verification-coverage/cities.csv",
    "regulatorsCsv": "/api/open-data/verification-coverage/regulators.csv",
    "watchdogCsv": "/api/open-data/verification-coverage/watchdog-stories.csv"
  },
  "missingData": {
    "note": "A section that could not be computed is serialised as null and named in unavailableSections; its CSV answers 503. A null section is NOT a zero, and a null percentage means there was nothing to divide."
  },
  "jsonDocument": {
    "endpoint": "/api/open-data/verification-coverage.json",
    "topLevelFields": {
      "datasetVersion": "Semantic version of this shape. A breaking column change bumps the major.",
      "asOf": "ISO timestamp the snapshot was computed.",
      "provenance": "What is counted, over what window, when it was computed, the source tables, and what is excluded.",
      "totals": "Platform-wide counts across every published listing, including cities and regulators outside the caps.",
      "byCity": "Per-city counts, capped at the busiest cities. Null when the section could not be computed.",
      "byRegulator": "Published listings per regulator code recorded at import. Null when unavailable.",
      "watchdogStories": "Published watchdog stories for the last complete calendar quarter, by geography.",
      "caps": "The row caps applied to the city and regulator tables.",
      "derivations": "Plain-language formula for every derived figure.",
      "limitations": "What this dataset is not, stated before anyone cites it.",
      "unavailableSections": "Sections that could not be computed. A named section is unavailable, NOT zero.",
      "emptyReason": "Why the dataset is empty, when it is. Null otherwise.",
      "sourceLicences": "Upstream data licences for register-derived rows. Present only when a regulator in byRegulator is sourced under a researched licence — today the Care Quality Commission register under the Open Government Licence v3.0. The top-level licence covers our derived dataset; this names the source it derives from. Absent when no such regulator is present."
    }
  },
  "tables": {
    "cities": {
      "endpoint": "/api/open-data/verification-coverage/cities.csv",
      "grain": "One row per city, ordered by published listing count.",
      "columns": {
        "city": "City name as recorded on the listing.",
        "region": "Region or county, empty where we hold none.",
        "publishedListings": "Published listings in the city.",
        "verifiedListings": "Of those, listings we have verified.",
        "unverifiedListings": "published minus verified. Not a safety judgement.",
        "regulatedListings": "Of those, listings whose business holds a current green regulator credential.",
        "regulatorCoveragePct": "regulatedListings ÷ publishedListings, one decimal. Empty when there is nothing to divide."
      }
    },
    "regulators": {
      "endpoint": "/api/open-data/verification-coverage/regulators.csv",
      "grain": "One row per regulator code recorded against a listing at import.",
      "note": "The regulator provenance recorded here is derived from each regulator's public register. Rows sourced from a register published under the Open Government Licence v3.0 (today, the Care Quality Commission) carry that licence — see sourceLicences in the JSON document and the second Link: rel=\"license\" header this CSV serves.",
      "columns": {
        "regulatorCode": "Regulator code.",
        "regulatorName": "Canonical regulator name, empty where we hold no contract for the code.",
        "publishedListings": "Published listings carrying this regulator as their import provenance."
      }
    },
    "watchdogStories": {
      "endpoint": "/api/open-data/verification-coverage/watchdog-stories.csv",
      "grain": "One row per geography for the last complete calendar quarter. A headers-only file means the section WAS computed and no stories were published in that quarter — a genuine zero. A section that could not be computed answers 503 instead, and the quarter it covers is named in the JSON document.",
      "columns": {
        "quarterLabel": "The complete quarter counted, e.g. Q2 2026.",
        "geo": "Story geography tag: UK, EUROPE or USA.",
        "count": "Published stories dated inside the quarter."
      }
    }
  }
}