# Get ranked district club historical health

`GET /api/district/{district}/clubs/historical-health`

Returns one complete, single district club-roster snapshot, ordered by finite historical-health score descending. Equal scores are ordered by canonical club number ascending and receive unique 1-based ordinal ranks; null scores are last and unranked. fiscalYear and fiscalMonth select only the current roster snapshot and never filter, cap, or otherwise alter the completed history selected by each reusable analysis. A known district snapshot with no clubs returns 200 and an empty clubs list. Only fiscalYear and fiscalMonth are supported query parameters; latest and unknown query parameters are rejected.

**Path parameters**

- `district` (string, required): District number/code.

**Query parameters**

- `fiscalYear` (string, optional): Roster snapshot fiscal year. Defaults using the district fiscal-year selection rules.
- `fiscalMonth` (integer, optional): Roster snapshot fiscal month. When omitted, the latest eligible month in the resolved fiscal year is selected.

**Returns**

- `success` (enum) One of: `true`.
- `fiscal_year` (string): Fiscal year of the one resolved district roster snapshot.
- `fiscal_month` (integer): Fiscal month of the one resolved district roster snapshot.
- `data` (object)
  - `district` (string)
  - `region` (nullable string)
  - `clubs` (array of objects): Complete resolved roster, including clubs with missing history. A known district snapshot with no clubs returns an empty array.
    - `rank` (nullable integer): Unique 1-based ordinal rank for a finite analysis score; null for unranked null-score clubs.
    - `club_number` (string): Canonical club number without leading zeroes.
    - `club_name` (nullable string)
    - `division` (nullable string)
    - `area` (nullable string)
    - `club_status` (nullable string)
    - `active_members` (nullable number)
    - `distinguished_status` (nullable string)
    - `historical_health_analysis` (object): Reusable completed-programme-year health analysis. It excludes the current and future fiscal years, considers at most five eligible years, and never changes the current club_health_score. The weighted score, recent Distinguished-history class, and membership-risk trajectory answer separate questions.
      - `schema_version` (enum) One of: `1.0`.
      - `config_version` (string): Version of the historical-health calculation configuration. Configuration 2.0 uses a 25-member default sustainability threshold and independent recent-award classification.
      - `status` (enum): `no_history` is the deterministic empty DTO. `insufficient_data` lacks the required scored-component coverage. One of: `available`, `limited_history`, `insufficient_data`, `no_history`.
      - `score` (nullable number): Explainable weighted five-year diagnostic score. It does not determine historical_class and can therefore be lower for a club classified A from recent Distinguished outcomes. Null for no history or insufficient component coverage.
      - `historical_class` (nullable enum): Recent Distinguished-performance class, independent of the weighted score. It is derived from the latest up-to-three completed programme years with recognized award semantics: A is regularly President's/Smedley Distinguished, B is frequently Distinguished or better, C is occasional Distinguished, and D is rare/never Distinguished. Null only when the classification window has insufficient recognized award evidence. One of: `A`, `B`, `C`, `D`.
      - `trajectory` (nullable enum): Membership-risk trajectory. Classification uses actual year-end memberships capped at the configured 25-member sustainability threshold, so changes wholly above that threshold are neutral; raw, uncapped trend metrics remain in trend. Null until at least two observed memberships exist. One of: `Growing`, `Stable`, `Declining`, `Recovering`, `Volatile`.
      - `profile` (nullable enum): Combined independently derived historical class and benchmark-adjusted trajectory; it does not depend on score. Null when either historical_class or trajectory is unavailable. One of: `Healthy & Growing`, `Healthy & Stable`, `Strong but Declining`, `Recovering`, `Volatile`, `Long-Term At Risk`.
      - `years_analyzed` (integer)
      - `period` (object)
        - `requested_max_years` (enum) One of: `5`.
        - `completed_through` (string): Most recent eligible completed fiscal year.
        - `earliest` (nullable string)
        - `latest` (nullable string)
        - `missing_years` (array of strings): Gaps between selected observed fiscal years; no data is inferred for them.
      - `trend` (object)
        - `membership_change_percent_per_year` (nullable number): Raw annualized year-end membership change percentage using actual, uncapped memberships. This metric is context only and is not the trajectory-classification rate.
        - `membership_volatility` (nullable number): Raw coefficient of variation of observed actual, uncapped year-end membership. The benchmark-adjusted volatility used for trajectory classification is exposed in explainability evidence.
        - `latest_year_end_membership` (nullable number): Latest actual, uncapped year-end membership.
      - `yearly` (array of objects)
        - `fiscal_year` (string)
        - `year_end_membership` (nullable number): Actual reported year-end membership; this value is never capped.
        - `membership_change` (nullable number): Actual year-end minus membership base; this raw value is never benchmark-adjusted.
        - `membership_change_percent` (nullable number): Actual raw membership change percentage; this value is never benchmark-adjusted.
        - `at_or_above_20` (nullable boolean, deprecated): Legacy compatibility flag for the former 20-member threshold. Use at_or_above_healthy_membership for the configured sustainability threshold.
        - `at_or_above_healthy_membership` (nullable boolean): Sustainability flag: whether actual year-end membership meets the configured healthy-membership threshold (25 by default in configuration 2.0).
        - `dcp_goals` (nullable number)
        - `distinguished_status` (nullable string)
        - `officer_training_round_1` (nullable number)
        - `officer_training_round_2` (nullable number)
        - `score` (nullable number): Per-year score when at least three scored components including membership sustainability are available.
      - `explainability` (object)
        - `components` (array of objects): Stable component-key detail supporting the diagnostic score. Recent-award classification and benchmark-adjusted trajectory evidence are top-level explainability fields.
          - `key` (enum) One of: `membership_sustainability`, `growth`, `dcp_goals`, `distinguished_status`, `officer_training`.
          - `configured_weight` (number): Configured percentage weight.
          - `effective_weight` (number): Percentage weight after redistribution across observed components.
          - `score` (nullable number): Component score from 0 through 100; null when no usable observations exist.
          - `contribution` (number): Weighted contribution to the historical score, or zero when missing.
          - `observations` (integer)
          - `status` (enum) One of: `scored`, `missing`.
          - `formula` (string)
          - `evidence` (object): Component-specific primitive evidence used by the diagnostic-score calculation, such as the configured sustainability threshold and safe membership declines neutralized for growth scoring. Each value is a number, string, boolean, or null. Recent-award classification and benchmark-adjusted trajectory evidence are separate top-level explainability fields.
        - `recent_award_classification` (object): Top-level evidence for the independent historical_class calculation from recent recognized awards.
          - `classification_window_fiscal_years` (array of strings): Fiscal years in the most recent up-to-three completed-programme-year classification window, ordered oldest to newest.
          - `window_size` (integer): Number of completed programme years in the classification window.
          - `required_frequency` (integer): Recognized award values required to classify the window: ceil(window_size * 2 / 3).
          - `known_years` (integer): Years in the classification window with recognized award semantics, including explicit no-award values.
          - `high_distinguished_years` (integer): Recognized President's Distinguished or Smedley Distinguished years in the classification window.
          - `distinguished_years` (integer): Recognized Distinguished-or-better years in the classification window.
          - `selected_class_rule` (nullable string): Rule that selected the A-D historical class; null when recognized award evidence is insufficient.
        - `benchmark_adjusted_trajectory` (object): Top-level evidence for membership-risk trajectory classification using the benchmark-adjusted membership series.
          - `healthy_membership_threshold` (number): Configured healthy-membership threshold used to cap memberships for trajectory classification.
          - `benchmark_adjusted_membership_series` (array of objects): Observed completed-year memberships after capping each value at healthy_membership_threshold, ordered oldest to newest.
            - `fiscal_year` (string): Completed programme year for this trajectory observation.
            - `membership` (number): Year-end membership capped at healthy_membership_threshold for trajectory classification.
          - `benchmark_adjusted_change_percent_per_year` (nullable number): Average gap-aware annualized change percentage calculated from the benchmark-adjusted membership series; null when no valid transition exists.
          - `benchmark_adjusted_membership_volatility` (nullable number): Coefficient of variation of the benchmark-adjusted membership series; null when it cannot be calculated.
          - `above_threshold_movements_neutralized` (integer): Count of adjacent observed movements whose actual endpoints both met the healthy-membership threshold and therefore become neutral after capping.
        - `reasons` (array of strings): Human-readable calculation disclosures, including why score and historical class may differ, benchmark-adjusted trajectory inputs, and safe declines neutralized at or above the sustainability threshold.
      - `data_quality` (object)
        - `confidence` (enum) One of: `high`, `medium`, `low`, `none`.
        - `excluded_years` (array of objects)
          - `fiscal_year` (string)
          - `reason` (string)
        - `missing_metrics` (array of strings)
        - `warnings` (array of strings)
    - `club_outlook` (object): Which of five groups the club is in: doing_well, improving, steady, declining or definite_worry. From October the current paid count decides first: under 8 paid members is definite_worry, and keeping under 60% of last June's members is declining. Otherwise the 0-100 health score for the last completed programme year decides: 70+ is doing_well; a score up 10+ on the two years before, or more paid members than last June, is improving; anything else is steady. Before October, a score under 40 is definite_worry. Back-tested on October 2024 and 2025: closed or under 8 members by the next June was 1% for doing_well, 8% improving, 8% steady, 6% declining (median -6 members) and 55% definite_worry.
      - `version` (enum) One of: `1`.
      - `category` (nullable enum): Null when the club has no completed year and isn't under 8 paid members after October. One of: `doing_well`, `improving`, `steady`, `declining`, `definite_worry`, `null`.
      - `label` (nullable string)
      - `basis` (enum): renewals once October renewals are in; history before that. One of: `renewals`, `history`.
      - `health_score` (nullable number): 100 minus points for the last completed programme year.
      - `health_score_change` (nullable number): Health score minus the average of the two programme years before it.
      - `scored_year` (nullable string)
      - `paid_members` (nullable number)
      - `last_year_end_members` (nullable number)
      - `retention` (nullable number): Paid members now as a share of last year end's, from October.
      - `reasons` (array of strings): Why the club is in its group, most important first.
      - `points` (array of objects): Points taken off 100 for the scored year, largest first.
        - `key` (enum) One of: `members`, `dcp_goals`, `new_members`, `officer_training`, `renewals`, `members_lost`, `distinguished`.
        - `points` (number)
        - `reason` (string)
- `summary` (object)
  - `total_clubs` (integer)
  - `ranked_clubs` (integer)
  - `unranked_clubs` (integer)
  - `analysis_status_counts` (object)
    - `available` (integer)
    - `limited_history` (integer)
    - `insufficient_data` (integer)
    - `no_history` (integer)
- `metadata` (object)
  - `analysis_current_fiscal_year` (string): Current fiscal year passed to each completed-programme-year analysis; it is independent of the roster snapshot filters.
  - `ranking` (object): Finite scores sort descending. Equal scores use canonical club number ascending, then receive unique ordinal ranks. Null scores sort last and are unranked.
    - `key` (enum) One of: `historical_health_analysis.score`.
    - `direction` (enum) One of: `desc`.
    - `nulls` (enum) One of: `last_unranked`.
    - `tie_breaker` (enum) One of: `normalized_club_number_asc`.
    - `rank_style` (enum) One of: `ordinal`.
- `filters` (object)
  - `district` (string)
  - `fiscalYear` (string)
  - `fiscalMonth` (integer)
- `timestamp` (timestamp)

**Errors**

- `404`: No district snapshot exists for the resolved fiscal year and month.
- `422`: Invalid district, fiscalYear, fiscalMonth, or unsupported query parameter such as latest.
- `500`: Internal server error

**Example request**

```bash
curl "https://tm-api.devinpearson.me/api/district/74/clubs/historical-health"
```

**Example response**

```json
{
  "success": true,
  "fiscal_year": "2026-2027",
  "fiscal_month": 5,
  "data": {
    "district": "74",
    "region": "11",
    "clubs": [
      {
        "rank": 1,
        "club_number": "113",
        "club_name": "Example Toastmasters Club",
        "division": "A",
        "area": "01",
        "club_status": "string",
        "active_members": 0,
        "distinguished_status": "string",
        "historical_health_analysis": {
          "schema_version": "1.0",
          "config_version": "string",
          "status": "available",
          "score": 0,
          "historical_class": "A",
          "trajectory": "Growing",
          "profile": "Healthy & Growing",
          "years_analyzed": 0,
          "period": {
            "requested_max_years": 5,
            "completed_through": "string",
            "earliest": "string",
            "latest": "string",
            "missing_years": []
          },
          "trend": {
            "membership_change_percent_per_year": 0,
            "membership_volatility": 0,
            "latest_year_end_membership": 0
          },
          "yearly": [
            {}
          ],
          "explainability": {
            "components": [],
            "recent_award_classification": {},
            "benchmark_adjusted_trajectory": {},
            "reasons": []
          },
          "data_quality": {
            "confidence": "high",
            "excluded_years": [],
            "missing_metrics": [],
            "warnings": []
          }
        },
        "club_outlook": {
          "version": "1",
          "category": "doing_well",
          "label": "Definite worry",
          "basis": "renewals",
          "health_score": 0,
          "health_score_change": 0,
          "scored_year": "2025-2026",
          "paid_members": 0,
          "last_year_end_members": 0,
          "retention": 0,
          "reasons": [
            "string"
          ],
          "points": [
            {}
          ]
        }
      }
    ]
  },
  "summary": {
    "total_clubs": 0,
    "ranked_clubs": 0,
    "unranked_clubs": 0,
    "analysis_status_counts": {
      "available": 0,
      "limited_history": 0,
      "insufficient_data": 0,
      "no_history": 0
    }
  },
  "metadata": {
    "analysis_current_fiscal_year": "string",
    "ranking": {
      "key": "historical_health_analysis.score",
      "direction": "desc",
      "nulls": "last_unranked",
      "tie_breaker": "normalized_club_number_asc",
      "rank_style": "ordinal"
    }
  },
  "filters": {
    "district": "74",
    "fiscalYear": "2026-2027",
    "fiscalMonth": 5
  },
  "timestamp": "2026-11-19T04:30:00.000Z"
}
```
