GET /v1/statistics/top

Le classement des valeurs les plus représentées sur une dimension — quelles faiblesses, quels éditeurs, quels produits, quelles autorités d’assignation dominent une période donnée.

La même route sert le top all-time et le top d’une semaine précise : seule la fenêtre change.

Scope requis : stats-global

Requête

GET /api/v1/statistics/top
Authorization: Bearer twa_votre_cle_ici

Paramètres de requête

Paramètre	Type	Défaut	Description
`dimension`	`string`	`cwe`	`cwe`, `vendor`, `product`, `cna`
`period`	`string`	—	`2026`, `2026-Q1`, `2026-03`, `2026-W12`, `2026-03-15`
`from`	`date`	`1999-01-01`	Borne de début, ignorée si `period` est fourni
`to`	`date`	demain	Borne de fin, ignorée si `period` est fourni
`limit`	`integer`	`15`	1 à 100
`sort`	`string`	`total`	`total`, `critical`, `high`, `kev`, `poc`
`kev_only`	`boolean`	`false`	Ne compter que les CVE du catalogue KEV

Sans period ni from/to, le classement porte sur tout l’historique.

La dimension cna expose l’autorité qui a assigné l’identifiant (CVE Numbering Authority) — utile pour voir quels éditeurs et organismes publient le plus.

Réponse `200 OK`

{
  "dimension": "cwe",
  "label": "Type de faiblesse (CWE)",
  "period": "2026-W12",
  "from": "2026-03-16",
  "to": "2026-03-22",
  "kev_only": false,
  "sort": "total",
  "grand_total": 1184,
  "distinct_values": 97,
  "items": [
    {
      "rank": 1,
      "value": "CWE-79",
      "label": "CWE-79",
      "total": 213,
      "critical": 4,
      "high": 61,
      "kev": 1,
      "poc": 28,
      "avg_cvss": 6.12,
      "avg_epss": 1.884,
      "share_pct": 17.99
    }
  ]
}

Champs

Champ	Type	Description
`grand_total`	`integer`	Somme sur toute la dimension, base de calcul des `share_pct`
`distinct_values`	`integer`	Nombre de valeurs distinctes sur la fenêtre
`value`	`string`	Clé de regroupement (minuscules pour `vendor`, `product`, `cna`)
`label`	`string`	Forme d’origine, à afficher
`share_pct`	`float`	Part dans `grand_total`

En mode kev_only, sort=total trie sur le total KEV : le classement porte toujours sur ce qui est affiché.

Évolution d’un classement

GET /api/v1/statistics/top-trend

Suit les N premières valeurs période par période, pour tracer une courbe par valeur.

Paramètre	Type	Défaut	Description
`dimension`	`string`	`cwe`	`cwe`, `vendor`, `product`, `cna`
`granularity`	`string`	`year`	`day`, `week`, `month`, `quarter`, `year`
`period` / `from` / `to`	—	—	Même fonctionnement que ci-dessus
`limit`	`integer`	`8`	1 à 25

Le top est établi une seule fois sur toute la fenêtre, puis ces mêmes valeurs sont suivies sur chaque période. C’est délibéré : recalculer le top à chaque période ferait changer les séries de sujet d’un point à l’autre, et la courbe deviendrait illisible.

{
  "dimension": "cwe",
  "granularity": "year",
  "from": "2020-01-01",
  "to": "2026-09-11",
  "series": [
    { "value": "CWE-79", "label": "CWE-79", "total": 41203 }
  ],
  "points": [
    { "period": "2020-01-01", "CWE-79": 5120, "CWE-89": 2044 }
  ]
}

Chaque objet de points porte une clé par valeur suivie, listée dans series. Les combinaisons absentes valent 0, pour que les séries restent continues.

Erreurs

Code	Détail	Cause
`422`	`Dimension inconnue…`	Valeur hors de `cwe`, `vendor`, `product`, `cna`
`422`	`Tri inconnu…`	`sort` hors de la liste autorisée
`422`	`Période « … » non reconnue`	Format de `period` invalide

Exemples

Le top CWE d’une semaine précise :

curl -s \
  -H "Authorization: Bearer twa_votre_cle_ici" \
  "https://app.techwatchalert.com/api/v1/statistics/top?dimension=cwe&period=2026-W12&limit=10" \
  | jq '.items | map({rang: .rank, cwe: .value, total, part: .share_pct})'

Les éditeurs les plus présents au catalogue KEV, tous temps confondus :

curl -s \
  -H "Authorization: Bearer twa_votre_cle_ici" \
  "https://app.techwatchalert.com/api/v1/statistics/top?dimension=vendor&kev_only=true&limit=15" \
  | jq '.items | map({editeur: .label, kev: .total})'