# Compare a district's fiscal month with the same month last year

`GET /api/district/{district}/year-comparison`

Returns the district summary figures, totals over the clubs for the district and each division, and every club's figures for a fiscal month and for the same fiscal month of the previous fiscal year. Both sides are monthly snapshots: last year's is that month's final report, this year's the latest report so far.

**Path parameters**

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

**Query parameters**

- `fiscalYear` (string, optional): Fiscal year to compare. Defaults to the district's latest reported fiscal year.
- `fiscalMonth` (integer, optional): Fiscal month (1 = July) to compare. Defaults to the latest reported month in the fiscal year.

**Returns**

- `success` (enum) One of: `true`.
- `data` (object): A district's reported fiscal month against the same fiscal month last year, from the monthly snapshots. Last year's side is that month's final report; this year's is the latest report so far, so report_date says which day each side reflects.
  - `district` (string)
  - `fiscal_year` (string)
  - `fiscal_month` (integer): Fiscal month (1 = July).
  - `previous_fiscal_year` (string)
  - `report_date` (nullable date): The report day this year's figures reflect.
  - `previous_report_date` (nullable date): The report day last year's figures reflect; null when no clubs were reported then.
  - `summary` (object or nullable enum): District summary figures; null without a district summary this month.
    - `current` (object): The district summary figures for one fiscal month.
      - `paid_clubs` (integer)
      - `paid_club_base` (integer)
      - `active_clubs` (integer)
      - `payments_to_date` (integer)
      - `payment_base` (integer)
      - `october_payments` (integer)
      - `april_payments` (integer)
      - `new_payments` (integer)
      - `late_payments` (integer)
      - `charter_payments` (integer)
      - `distinguished_clubs` (integer)
    - `previous` (object or nullable enum): The same month last year; null when no district summary was reported then.
      - `paid_clubs` (integer)
      - `paid_club_base` (integer)
      - `active_clubs` (integer)
      - `payments_to_date` (integer)
      - `payment_base` (integer)
      - `october_payments` (integer)
      - `april_payments` (integer)
      - `new_payments` (integer)
      - `late_payments` (integer)
      - `charter_payments` (integer)
      - `distinguished_clubs` (integer)
    - `change` (object or nullable enum): This year's figures minus last year's; null when previous is.
      - `paid_clubs` (integer)
      - `paid_club_base` (integer)
      - `active_clubs` (integer)
      - `payments_to_date` (integer)
      - `payment_base` (integer)
      - `october_payments` (integer)
      - `april_payments` (integer)
      - `new_payments` (integer)
      - `late_payments` (integer)
      - `charter_payments` (integer)
      - `distinguished_clubs` (integer)
  - `clubs` (object)
    - `current` (object): A district's or division's totals over its clubs for one fiscal month. Suspended clubs count only as suspended.
      - `clubs` (integer): Clubs that aren't suspended.
      - `suspended_clubs` (integer)
      - `paid_clubs` (integer): Clubs that aren't suspended with an October or April renewal on record.
      - `distinguished_clubs` (integer)
      - `member_base` (integer): Membership base, summed over the clubs.
      - `active_members` (integer)
      - `net_growth` (integer): active_members minus member_base.
      - `clubs_under_8_members` (integer): Clubs below the 8 members needed for good standing.
      - `clubs_at_or_above_base` (integer): Clubs with at least max(base, 8) members.
      - `goals_met` (integer): DCP goals met, summed over the clubs.
      - `clubs_with_no_goals` (integer)
      - `clubs_with_5_plus_goals` (integer)
      - `level_1s` (integer)
      - `level_2s` (integer): Level 2s plus additional Level 2s.
      - `level_3s` (integer)
      - `level_4s` (integer): Level 4s, path completions and DTMs, plus additional ones.
      - `educational_awards` (integer)
      - `new_members` (integer): New and additional new members counted for the DCP.
      - `clubs_with_4_officers_trained_round_1` (integer)
      - `csp_submitted` (integer): Clubs that submitted a Club Success Plan.
    - `previous` (object or nullable enum): The same month last year; null when no club was reported then.
      - `clubs` (integer): Clubs that aren't suspended.
      - `suspended_clubs` (integer)
      - `paid_clubs` (integer): Clubs that aren't suspended with an October or April renewal on record.
      - `distinguished_clubs` (integer)
      - `member_base` (integer): Membership base, summed over the clubs.
      - `active_members` (integer)
      - `net_growth` (integer): active_members minus member_base.
      - `clubs_under_8_members` (integer): Clubs below the 8 members needed for good standing.
      - `clubs_at_or_above_base` (integer): Clubs with at least max(base, 8) members.
      - `goals_met` (integer): DCP goals met, summed over the clubs.
      - `clubs_with_no_goals` (integer)
      - `clubs_with_5_plus_goals` (integer)
      - `level_1s` (integer)
      - `level_2s` (integer): Level 2s plus additional Level 2s.
      - `level_3s` (integer)
      - `level_4s` (integer): Level 4s, path completions and DTMs, plus additional ones.
      - `educational_awards` (integer)
      - `new_members` (integer): New and additional new members counted for the DCP.
      - `clubs_with_4_officers_trained_round_1` (integer)
      - `csp_submitted` (integer): Clubs that submitted a Club Success Plan.
    - `change` (object or nullable enum): This year's figures minus last year's; null when previous is.
      - `clubs` (integer): Clubs that aren't suspended.
      - `suspended_clubs` (integer)
      - `paid_clubs` (integer): Clubs that aren't suspended with an October or April renewal on record.
      - `distinguished_clubs` (integer)
      - `member_base` (integer): Membership base, summed over the clubs.
      - `active_members` (integer)
      - `net_growth` (integer): active_members minus member_base.
      - `clubs_under_8_members` (integer): Clubs below the 8 members needed for good standing.
      - `clubs_at_or_above_base` (integer): Clubs with at least max(base, 8) members.
      - `goals_met` (integer): DCP goals met, summed over the clubs.
      - `clubs_with_no_goals` (integer)
      - `clubs_with_5_plus_goals` (integer)
      - `level_1s` (integer)
      - `level_2s` (integer): Level 2s plus additional Level 2s.
      - `level_3s` (integer)
      - `level_4s` (integer): Level 4s, path completions and DTMs, plus additional ones.
      - `educational_awards` (integer)
      - `new_members` (integer): New and additional new members counted for the DCP.
      - `clubs_with_4_officers_trained_round_1` (integer)
      - `csp_submitted` (integer): Clubs that submitted a Club Success Plan.
  - `divisions` (array of objects)
    - `key` (string): Division letter.
    - `current` (object): A district's or division's totals over its clubs for one fiscal month. Suspended clubs count only as suspended.
      - `clubs` (integer): Clubs that aren't suspended.
      - `suspended_clubs` (integer)
      - `paid_clubs` (integer): Clubs that aren't suspended with an October or April renewal on record.
      - `distinguished_clubs` (integer)
      - `member_base` (integer): Membership base, summed over the clubs.
      - `active_members` (integer)
      - `net_growth` (integer): active_members minus member_base.
      - `clubs_under_8_members` (integer): Clubs below the 8 members needed for good standing.
      - `clubs_at_or_above_base` (integer): Clubs with at least max(base, 8) members.
      - `goals_met` (integer): DCP goals met, summed over the clubs.
      - `clubs_with_no_goals` (integer)
      - `clubs_with_5_plus_goals` (integer)
      - `level_1s` (integer)
      - `level_2s` (integer): Level 2s plus additional Level 2s.
      - `level_3s` (integer)
      - `level_4s` (integer): Level 4s, path completions and DTMs, plus additional ones.
      - `educational_awards` (integer)
      - `new_members` (integer): New and additional new members counted for the DCP.
      - `clubs_with_4_officers_trained_round_1` (integer)
      - `csp_submitted` (integer): Clubs that submitted a Club Success Plan.
    - `previous` (object or nullable enum): The same month last year; null when no club was reported then.
      - `clubs` (integer): Clubs that aren't suspended.
      - `suspended_clubs` (integer)
      - `paid_clubs` (integer): Clubs that aren't suspended with an October or April renewal on record.
      - `distinguished_clubs` (integer)
      - `member_base` (integer): Membership base, summed over the clubs.
      - `active_members` (integer)
      - `net_growth` (integer): active_members minus member_base.
      - `clubs_under_8_members` (integer): Clubs below the 8 members needed for good standing.
      - `clubs_at_or_above_base` (integer): Clubs with at least max(base, 8) members.
      - `goals_met` (integer): DCP goals met, summed over the clubs.
      - `clubs_with_no_goals` (integer)
      - `clubs_with_5_plus_goals` (integer)
      - `level_1s` (integer)
      - `level_2s` (integer): Level 2s plus additional Level 2s.
      - `level_3s` (integer)
      - `level_4s` (integer): Level 4s, path completions and DTMs, plus additional ones.
      - `educational_awards` (integer)
      - `new_members` (integer): New and additional new members counted for the DCP.
      - `clubs_with_4_officers_trained_round_1` (integer)
      - `csp_submitted` (integer): Clubs that submitted a Club Success Plan.
    - `change` (object or nullable enum): This year's figures minus last year's; null when previous is.
      - `clubs` (integer): Clubs that aren't suspended.
      - `suspended_clubs` (integer)
      - `paid_clubs` (integer): Clubs that aren't suspended with an October or April renewal on record.
      - `distinguished_clubs` (integer)
      - `member_base` (integer): Membership base, summed over the clubs.
      - `active_members` (integer)
      - `net_growth` (integer): active_members minus member_base.
      - `clubs_under_8_members` (integer): Clubs below the 8 members needed for good standing.
      - `clubs_at_or_above_base` (integer): Clubs with at least max(base, 8) members.
      - `goals_met` (integer): DCP goals met, summed over the clubs.
      - `clubs_with_no_goals` (integer)
      - `clubs_with_5_plus_goals` (integer)
      - `level_1s` (integer)
      - `level_2s` (integer): Level 2s plus additional Level 2s.
      - `level_3s` (integer)
      - `level_4s` (integer): Level 4s, path completions and DTMs, plus additional ones.
      - `educational_awards` (integer)
      - `new_members` (integer): New and additional new members counted for the DCP.
      - `clubs_with_4_officers_trained_round_1` (integer)
      - `csp_submitted` (integer): Clubs that submitted a Club Success Plan.
  - `club_list` (array of objects): Every club reported in either year.
    - `club_number` (string): Canonical club number, without leading zeros.
    - `club_name` (nullable string)
    - `current` (nullable object): A club's figures for the month in one year.
      - `division` (nullable string)
      - `area` (nullable string)
      - `club_status` (nullable string)
      - `member_base` (integer)
      - `active_members` (integer)
      - `goals_met` (integer)
      - `educational_awards` (integer)
    - `previous` (nullable object): A club's figures for the month in one year.
      - `division` (nullable string)
      - `area` (nullable string)
      - `club_status` (nullable string)
      - `member_base` (integer)
      - `active_members` (integer)
      - `goals_met` (integer)
      - `educational_awards` (integer)
- `timestamp` (timestamp)

**Errors**

- `404`: No clubs reported for the district in that month.
- `422`: Invalid district, fiscalYear, fiscalMonth, or an unsupported query parameter.
- `500`: Internal server error

**Example request**

```bash
curl "https://tm-api.devinpearson.me/api/district/74/year-comparison"
```

**Example response**

```json
{
  "success": true,
  "data": {
    "district": "74",
    "fiscal_year": "2026-2027",
    "fiscal_month": 5,
    "previous_fiscal_year": "2025-2026",
    "report_date": "2026-11-19",
    "previous_report_date": "2026-11-19",
    "summary": {
      "current": {
        "paid_clubs": 0,
        "paid_club_base": 0,
        "active_clubs": 0,
        "payments_to_date": 0,
        "payment_base": 0,
        "october_payments": 0,
        "april_payments": 0,
        "new_payments": 0,
        "late_payments": 0,
        "charter_payments": 0,
        "distinguished_clubs": 0
      },
      "previous": {
        "paid_clubs": 0,
        "paid_club_base": 0,
        "active_clubs": 0,
        "payments_to_date": 0,
        "payment_base": 0,
        "october_payments": 0,
        "april_payments": 0,
        "new_payments": 0,
        "late_payments": 0,
        "charter_payments": 0,
        "distinguished_clubs": 0
      },
      "change": {
        "paid_clubs": 0,
        "paid_club_base": 0,
        "active_clubs": 0,
        "payments_to_date": 0,
        "payment_base": 0,
        "october_payments": 0,
        "april_payments": 0,
        "new_payments": 0,
        "late_payments": 0,
        "charter_payments": 0,
        "distinguished_clubs": 0
      }
    },
    "clubs": {
      "current": {
        "clubs": 0,
        "suspended_clubs": 0,
        "paid_clubs": 0,
        "distinguished_clubs": 0,
        "member_base": 0,
        "active_members": 0,
        "net_growth": 0,
        "clubs_under_8_members": 0,
        "clubs_at_or_above_base": 0,
        "goals_met": 0,
        "clubs_with_no_goals": 0,
        "clubs_with_5_plus_goals": 0,
        "level_1s": 0,
        "level_2s": 0,
        "level_3s": 0,
        "level_4s": 0,
        "educational_awards": 0,
        "new_members": 0,
        "clubs_with_4_officers_trained_round_1": 0,
        "csp_submitted": 0
      },
      "previous": {
        "clubs": 0,
        "suspended_clubs": 0,
        "paid_clubs": 0,
        "distinguished_clubs": 0,
        "member_base": 0,
        "active_members": 0,
        "net_growth": 0,
        "clubs_under_8_members": 0,
        "clubs_at_or_above_base": 0,
        "goals_met": 0,
        "clubs_with_no_goals": 0,
        "clubs_with_5_plus_goals": 0,
        "level_1s": 0,
        "level_2s": 0,
        "level_3s": 0,
        "level_4s": 0,
        "educational_awards": 0,
        "new_members": 0,
        "clubs_with_4_officers_trained_round_1": 0,
        "csp_submitted": 0
      },
      "change": {
        "clubs": 0,
        "suspended_clubs": 0,
        "paid_clubs": 0,
        "distinguished_clubs": 0,
        "member_base": 0,
        "active_members": 0,
        "net_growth": 0,
        "clubs_under_8_members": 0,
        "clubs_at_or_above_base": 0,
        "goals_met": 0,
        "clubs_with_no_goals": 0,
        "clubs_with_5_plus_goals": 0,
        "level_1s": 0,
        "level_2s": 0,
        "level_3s": 0,
        "level_4s": 0,
        "educational_awards": 0,
        "new_members": 0,
        "clubs_with_4_officers_trained_round_1": 0,
        "csp_submitted": 0
      }
    },
    "divisions": [
      {
        "key": "string",
        "current": {
          "clubs": 0,
          "suspended_clubs": 0,
          "paid_clubs": 0,
          "distinguished_clubs": 0,
          "member_base": 0,
          "active_members": 0,
          "net_growth": 0,
          "clubs_under_8_members": 0,
          "clubs_at_or_above_base": 0,
          "goals_met": 0,
          "clubs_with_no_goals": 0,
          "clubs_with_5_plus_goals": 0,
          "level_1s": 0,
          "level_2s": 0,
          "level_3s": 0,
          "level_4s": 0,
          "educational_awards": 0,
          "new_members": 0,
          "clubs_with_4_officers_trained_round_1": 0,
          "csp_submitted": 0
        },
        "previous": {
          "clubs": 0,
          "suspended_clubs": 0,
          "paid_clubs": 0,
          "distinguished_clubs": 0,
          "member_base": 0,
          "active_members": 0,
          "net_growth": 0,
          "clubs_under_8_members": 0,
          "clubs_at_or_above_base": 0,
          "goals_met": 0,
          "clubs_with_no_goals": 0,
          "clubs_with_5_plus_goals": 0,
          "level_1s": 0,
          "level_2s": 0,
          "level_3s": 0,
          "level_4s": 0,
          "educational_awards": 0,
          "new_members": 0,
          "clubs_with_4_officers_trained_round_1": 0,
          "csp_submitted": 0
        },
        "change": {
          "clubs": 0,
          "suspended_clubs": 0,
          "paid_clubs": 0,
          "distinguished_clubs": 0,
          "member_base": 0,
          "active_members": 0,
          "net_growth": 0,
          "clubs_under_8_members": 0,
          "clubs_at_or_above_base": 0,
          "goals_met": 0,
          "clubs_with_no_goals": 0,
          "clubs_with_5_plus_goals": 0,
          "level_1s": 0,
          "level_2s": 0,
          "level_3s": 0,
          "level_4s": 0,
          "educational_awards": 0,
          "new_members": 0,
          "clubs_with_4_officers_trained_round_1": 0,
          "csp_submitted": 0
        }
      }
    ],
    "club_list": [
      {
        "club_number": "113",
        "club_name": "Example Toastmasters Club",
        "current": {
          "division": "A",
          "area": "01",
          "club_status": "string",
          "member_base": 0,
          "active_members": 0,
          "goals_met": 0,
          "educational_awards": 0
        },
        "previous": {
          "division": "A",
          "area": "01",
          "club_status": "string",
          "member_base": 0,
          "active_members": 0,
          "goals_met": 0,
          "educational_awards": 0
        }
      }
    ]
  },
  "timestamp": "2026-11-19T04:30:00.000Z"
}
```
