# Get DCP history for a club

`GET /api/reports/dcp-history`

Retrieve Distinguished Club Program (DCP) historical performance data for a specific club across multiple fiscal years

**Query parameters**

- `clubNumber` (string, required): Club number (required). Leading zeros are automatically trimmed (e.g., "0113" becomes "113")
- `fiscalYear` (string, optional): Filter by fiscal year in legacy YY-YY (e.g., "24-25") or normalized YYYY-YYYY form.
- `district` (string, optional): District to filter by: a district number, U (undistricted) or F (Founders)
- `area` (string, optional): Filter by area
- `division` (string, optional): Filter by division
- `award` (string, optional): Filter by award received (e.g., "Distinguished", "Select Distinguished", "President's Distinguished")
- `sortBy` (enum, optional, default fiscal_year): Field to sort by (default: "fiscal_year") One of: `fiscal_year`, `total_goals`, `retention_rate`, `memb_base_7_1`, `year_end_memb`.
- `sortOrder` (enum, optional, default desc): Sort order (default: "desc" for most recent first) One of: `asc`, `desc`.
- `limit` (integer, optional, default 1000): Maximum number of records to return
- `offset` (integer, optional, default 0): Number of records to skip

**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")
- `summary` (object)
  - `total_records` (integer)
  - `fiscal_years_covered` (integer)
  - `average_goals_achieved` (number)
  - `average_retention_rate` (number)
  - `awards_received` (integer)
  - `best_year` (object)
    - `fiscal_year` (string)
    - `total_goals` (integer)
    - `retention_rate` (number)
    - `award` (string)
  - `worst_year` (object)
    - `fiscal_year` (string)
    - `total_goals` (integer)
    - `retention_rate` (number)
    - `award` (string)
  - `goal_achievement_by_category` (object)
    - `traditional_goals` (integer)
    - `pathways_goals` (integer)
    - `general_goals` (integer)
    - `total_goals` (integer)
  - `membership_trends` (array of objects)
    - `fiscal_year` (string)
    - `memb_base_7_1` (integer)
    - `year_end_memb` (integer)
    - `retention_rate` (number)
  - `club_info` (object)
    - `club_number` (string)
    - `club_name` (string)
    - `district` (string)
    - `area` (string)
    - `division` (string)
- `pagination` (object): Pagination retained by specialized report endpoints. total_records is the total matching records.
  - `total_records` (integer): Total matching records
  - `limit` (integer): Number of records per page
  - `offset` (integer): Number of records to skip
- `sorting` (object)
  - `sort_by` (enum) One of: `fiscal_year`, `total_goals`, `retention_rate`, `memb_base_7_1`, `year_end_memb`.
  - `sort_order` (enum) One of: `asc`, `desc`.
  - `fiscal_years_in_result` (array of strings)
- `filters` (object)

**Errors**

- `422`: clubNumber is missing or invalid
- `500`: Internal server error

**Example request**

```bash
curl "https://tm-api.devinpearson.me/api/reports/dcp-history?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"
    }
  ],
  "summary": {
    "total_records": 0,
    "fiscal_years_covered": 0,
    "average_goals_achieved": 0,
    "average_retention_rate": 0,
    "awards_received": 0,
    "best_year": {
      "fiscal_year": "2026-2027",
      "total_goals": 0,
      "retention_rate": 0,
      "award": "string"
    },
    "worst_year": {
      "fiscal_year": "2026-2027",
      "total_goals": 0,
      "retention_rate": 0,
      "award": "string"
    },
    "goal_achievement_by_category": {
      "traditional_goals": 0,
      "pathways_goals": 0,
      "general_goals": 0,
      "total_goals": 0
    },
    "membership_trends": [
      {
        "fiscal_year": "2026-2027",
        "memb_base_7_1": 0,
        "year_end_memb": 0,
        "retention_rate": 0
      }
    ],
    "club_info": {
      "club_number": "113",
      "club_name": "Example Toastmasters Club",
      "district": "74",
      "area": "01",
      "division": "A"
    }
  },
  "pagination": {
    "total_records": 0,
    "limit": 0,
    "offset": 0
  },
  "sorting": {
    "sort_by": "fiscal_year",
    "sort_order": "asc",
    "fiscal_years_in_result": [
      "string"
    ]
  },
  "filters": {}
}
```
