# Get detailed DCP history analysis for a club

`GET /api/reports/dcp-history/analysis`

Retrieve comprehensive DCP performance analysis plus reusable completed-programme-year historical health analysis. Configuration 2.0 separates recent Distinguished-history class, benchmark-adjusted membership-risk trajectory, and diagnostic composite score. The existing 404 is retained when the club has no DCP-history rows.

**Query parameters**

- `clubNumber` (string, required): Club number (required). Leading zeros are automatically trimmed (e.g., "0113" becomes "113")

**Returns**

- `success` (boolean)
- `data` (array of objects)
  - `club_number` (string): Club number
  - `club_name` (string): Club name
  - `district` (string): District number
  - `area` (string): Area
  - `division` (string): Division
  - `fiscal_year` (string): Fiscal year (e.g., "24-25")
  - `memb_base_7_1` (integer): Membership count on July 1st (start of fiscal year)
  - `year_end_memb` (integer): Year-end membership count
  - `traditional_goal_1` (integer): CC progress count; Goal 1 is achieved at 2
  - `traditional_goal_2` (integer): Additional CC progress count; Goal 2 is achieved at 2
  - `traditional_goal_3` (integer): AC progress count; Goal 3 is achieved at 1
  - `traditional_goal_4` (integer): Additional AC progress count; Goal 4 is achieved at 1
  - `traditional_goal_5` (integer): CL/AL/DTM progress count; Goal 5 is achieved at 1
  - `traditional_goal_6` (integer): Additional CL/AL/DTM progress count; Goal 6 is achieved at 1
  - `pathways_goal_1` (integer): Level 1 progress count; Goal 1 is achieved at 4
  - `pathways_goal_2` (integer): Level 2 progress count; Goal 2 is achieved at 2
  - `pathways_goal_3` (integer): Additional Level 2 progress count; Goal 3 is achieved at 2
  - `pathways_goal_4` (integer): Level 3 progress count; Goal 4 is achieved at 2
  - `pathways_goal_5` (integer): Level 4/path completion/DTM progress count; Goal 5 is achieved at 1
  - `pathways_goal_6` (integer): Additional Level 4/path completion/DTM progress count; Goal 6 is achieved at 1
  - `goal_7_new_members` (integer): Goal 7 new-member progress count, capped at 4
  - `goal_8_add_new_members` (integer): Goal 8 uncapped overflow count; starts only after Goal 7 reaches 4 and is achieved at 4
  - `goal_9_jun_aug_training` (integer): June-August trained-officer count; one half of Goal 9
  - `goal_9_dec_feb_training` (integer): December-February trained-officer count; one half of Goal 9
  - `goal_10_renewals` (integer): Goal 10: Membership renewals achievement (0 or 1)
  - `goal_10_officer_lists` (integer): Goal 10: Officer list submission achievement (0 or 1)
  - `total_goals` (integer): Total goals achieved (out of 20)
  - `retention_rate` (number): Membership retention rate (percentage)
  - `award` (string): Award received (Distinguished, Select Distinguished, President's Distinguished, or "-" for no award)
  - `scraped_date` (date): Date when data was recorded
  - `data_source` (string): Source of the data (typically "mikeraffety.com")
- `analysis` (object)
  - `performance_trends` (array of objects)
    - `fiscal_year` (string)
    - `total_goals` (integer)
    - `retention_rate` (number)
    - `award` (string)
    - `membership_change` (integer)
  - `goal_patterns` (object)
    - `traditional` (object)
      - `total_achieved` (integer)
      - `average_per_year` (number)
    - `pathways` (object)
      - `total_achieved` (integer)
      - `average_per_year` (number)
    - `general` (object)
      - `total_achieved` (integer)
      - `average_per_year` (number)
  - `award_history` (array of objects)
    - `fiscal_year` (string)
    - `award` (string)
    - `total_goals` (integer)
    - `retention_rate` (number)
  - `membership_stability` (object)
    - `average_retention` (number)
    - `highest_retention` (number)
    - `lowest_retention` (number)
    - `average_membership` (number)
    - `membership_volatility` (number)
  - `years_analyzed` (integer)
  - `date_range` (object)
    - `earliest` (string)
    - `latest` (string)
- `historical_health_analysis` (object): Completed-programme-year historical health analysis. Unlike the dashboard, this endpoint returns 404 instead of a no_history DTO when no DCP-history rows exist.
  - `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_info` (object)
  - `club_number` (string)
  - `club_name` (string)
  - `district` (string)
  - `area` (string)
  - `division` (string)

**Errors**

- `404`: Not found - No DCP history found for the specified club
- `422`: clubNumber is missing or invalid
- `500`: Internal server error

**Example request**

```bash
curl "https://tm-api.devinpearson.me/api/reports/dcp-history/analysis?clubNumber=113"
```

**Example response**

```json
{
  "success": true,
  "data": [
    {
      "club_number": "113",
      "club_name": "Example Toastmasters Club",
      "district": "74",
      "area": "01",
      "division": "A",
      "fiscal_year": "2026-2027",
      "memb_base_7_1": 0,
      "year_end_memb": 0,
      "traditional_goal_1": 0,
      "traditional_goal_2": 0,
      "traditional_goal_3": 0,
      "traditional_goal_4": 0,
      "traditional_goal_5": 0,
      "traditional_goal_6": 0,
      "pathways_goal_1": 0,
      "pathways_goal_2": 0,
      "pathways_goal_3": 0,
      "pathways_goal_4": 0,
      "pathways_goal_5": 0,
      "pathways_goal_6": 0,
      "goal_7_new_members": 0,
      "goal_8_add_new_members": 0,
      "goal_9_jun_aug_training": 0,
      "goal_9_dec_feb_training": 0,
      "goal_10_renewals": 0,
      "goal_10_officer_lists": 0,
      "total_goals": 0,
      "retention_rate": 0,
      "award": "string",
      "scraped_date": "2026-11-19",
      "data_source": "string"
    }
  ],
  "analysis": {
    "performance_trends": [
      {
        "fiscal_year": "2026-2027",
        "total_goals": 0,
        "retention_rate": 0,
        "award": "string",
        "membership_change": 0
      }
    ],
    "goal_patterns": {
      "traditional": {
        "total_achieved": 0,
        "average_per_year": 0
      },
      "pathways": {
        "total_achieved": 0,
        "average_per_year": 0
      },
      "general": {
        "total_achieved": 0,
        "average_per_year": 0
      }
    },
    "award_history": [
      {
        "fiscal_year": "2026-2027",
        "award": "string",
        "total_goals": 0,
        "retention_rate": 0
      }
    ],
    "membership_stability": {
      "average_retention": 0,
      "highest_retention": 0,
      "lowest_retention": 0,
      "average_membership": 0,
      "membership_volatility": 0
    },
    "years_analyzed": 0,
    "date_range": {
      "earliest": "string",
      "latest": "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": [
        "string"
      ]
    },
    "trend": {
      "membership_change_percent_per_year": 0,
      "membership_volatility": 0,
      "latest_year_end_membership": 0
    },
    "yearly": [
      {
        "fiscal_year": "2026-2027",
        "year_end_membership": 0,
        "membership_change": 0,
        "membership_change_percent": 0,
        "at_or_above_20": true,
        "at_or_above_healthy_membership": true,
        "dcp_goals": 0,
        "distinguished_status": "string",
        "officer_training_round_1": 0,
        "officer_training_round_2": 0,
        "score": 0
      }
    ],
    "explainability": {
      "components": [
        {
          "key": "membership_sustainability",
          "configured_weight": 0,
          "effective_weight": 0,
          "score": 0,
          "contribution": 0,
          "observations": 0,
          "status": "scored",
          "formula": "string",
          "evidence": {}
        }
      ],
      "recent_award_classification": {
        "classification_window_fiscal_years": [
          "string"
        ],
        "window_size": 0,
        "required_frequency": 0,
        "known_years": 0,
        "high_distinguished_years": 0,
        "distinguished_years": 0,
        "selected_class_rule": "string"
      },
      "benchmark_adjusted_trajectory": {
        "healthy_membership_threshold": 0,
        "benchmark_adjusted_membership_series": [
          {
            "fiscal_year": "2026-2027",
            "membership": 0
          }
        ],
        "benchmark_adjusted_change_percent_per_year": 0,
        "benchmark_adjusted_membership_volatility": 0,
        "above_threshold_movements_neutralized": 0
      },
      "reasons": [
        "string"
      ]
    },
    "data_quality": {
      "confidence": "high",
      "excluded_years": [
        {
          "fiscal_year": "2026-2027",
          "reason": "string"
        }
      ],
      "missing_metrics": [
        "string"
      ],
      "warnings": [
        "string"
      ]
    }
  },
  "club_info": {
    "club_number": "113",
    "club_name": "Example Toastmasters Club",
    "district": "74",
    "area": "01",
    "division": "A"
  }
}
```
