# SARS-CoV-2 Variant Dashboard — API for LLMs

This site (`ukcovid`) exposes a read-only JSON API for monitoring SARS-CoV-2
variant (Pango lineage) composition and growth. It is intended for programmatic
use by assistants such as Claude. No authentication is required.

Base URL: use this page's origin. All paths below are relative to it
(e.g. `https://cpredict.cn/spectrum/api/variants`).

## `GET /spectrum/api/variants`

Returns the recent **share** (proportion) and **growth rate** of every lineage
over a trailing window of ISO weeks. Growth is estimated by weekly log-odds
regression (the same method as the /trends page): slope of
`log((count+0.5)/(total-count+0.5))` against week index, reported as
`(exp(slope)-1)*100` percent per week.

### Query parameters

| Param | Default | Range | Meaning |
|---|---|---|---|
| `weeks` | 8 | 3-52 | Number of trailing ISO weeks in the window |
| `min_samples` | 20 | >=1 | Minimum total count for a lineage to be included |
| `min_weekly_samples` | 10 | >=1 | Weeks with fewer total samples are dropped from the regression |
| `continent` | all | — | Filter, e.g. `Asia`, `Europe`. Repeat for multiple values: `continent=Asia&continent=Europe` |
| `country` | all | — | Filter, e.g. `China`, `USA`. Repeat for multiple values: `country=China&country=USA` |

### Response

```json
{
  "window_weeks": 8,
  "week_start": "2026-W05",
  "week_end": "2026-W12",
  "date_start": "2026-01-26",
  "date_end": "2026-03-22",
  "total_sequences_in_window": 12453,
  "params": { "min_samples": 20, "min_weekly_samples": 10, "continent": [], "country": [] },
  "variants": [
    {
      "lineage": "XFG.1.1",
      "clade": "26A",
      "recent_count": 2912,
      "recent_share": 0.2338,
      "growth_per_week_pct": 5.4,
      "growth_ci_low_pct": 2.1,
      "r_squared": 0.91,
      "qualified_weeks": 7,
      "trend": "growing"
    }
  ]
}
```

### Field meanings

- `recent_share`: fraction of window sequences assigned to this lineage
  (`recent_count / total_sequences_in_window`).
- `growth_per_week_pct`: approximate week-over-week percent growth from the
  regression. Positive = expanding, negative = contracting. `null` if fewer
  than 2 qualifying weeks.
- `growth_ci_low_pct`: lower 95% confidence bound on growth. `trend="growing"`
  requires this to be > 0 **and** `r_squared > 0.3`.
- `r_squared`: regression fit quality (0-1). Below ~0.3 means the trend is
  unreliable.
- `qualified_weeks`: number of weeks that passed the `min_weekly_samples`
  filter and fed the regression.
- `trend`: `"growing"` / `"declining"` / `"stable"`, derived from CI low and
  R2 (see above; "declining" needs `growth < -5%` and `R2 > 0.3`).

Variants are sorted by `recent_share` descending.

### Example (curl)

```bash
curl "/spectrum/api/variants?weeks=8&min_samples=50"
curl "/spectrum/api/variants?country=China&weeks=12"
curl "/spectrum/api/variants?country=China&country=USA"   # OR across repeated values
```

### Example (Python)

```python
import requests
r = requests.get("https://cpredict.cn/spectrum/api/variants", params={"weeks": 8})
for v in r.json()["variants"][:10]:
    print(v["lineage"], f'{v["recent_share"]*100:.1f}%', f'{v["growth_per_week_pct"]:+.1f}%/wk')
```

## `GET /spectrum/api/status`

Returns the overall row count and date range:

```json
{
  "min_collection": "2025-06-01",
  "max_collection": "2026-06-24",
  "count": 164600
}
```

Useful as a sanity check before calling `/spectrum/api/variants`.

## Notes

- Data is SARS-CoV-2 Pango lineages from GISAID, re-classified against the
  current Nextclade designation tree. Only sequences collected on or after
  2025-06-01 are retained.
- All responses are JSON; no API key is needed.
- Growth estimates are approximate and noisy for lineages with small counts
  or few qualifying weeks; weight by `recent_count` and `r_squared`.