# Area

An area is a small group of clubs within a division, led by an Area Director. It is identified by its district, its division's letter and its own number, for example district 74, division A, area 01.

The area dashboard reports the area's totals, its clubs, its progress towards Distinguished Area recognition and the Area Director's club visits. The changelog groups what changed across the area's clubs.

Base URL: `https://tm-api.devinpearson.me`

## Get aggregated area changelog

`GET /api/district/{district}/area/{division}/{area}/changelog`

Groups normalized club changelog events by metric across the selected period. Each metric contains its total numeric delta and affected clubs with names, club totals, and dated source changes. Lifecycle groups are included and use null numeric totals.

**Path parameters**

- `district` (string, required)
- `division` (string, required)
- `area` (string, required)

**Query parameters**

- `fiscalYear` (string, optional): Toastmasters fiscal year. Defaults to the current fiscal year.
- `fiscalMonth` (integer, optional)
- `date` (date, optional)
- `startDate` (date, optional)
- `endDate` (date, optional)
- `category` (enum, optional) One of: `lifecycle`, `membership`, `education`, `status`, `renewals`.
- `metric` (string, optional)
- `limit` (integer, optional, default 1000): Maximum number of records to return
- `offset` (integer, optional, default 0): Number of records to skip
- `sortOrder` (enum, optional, default desc) One of: `asc`, `desc`.
- `view` (enum, optional): day: the daily timeline. Each group is one metric on one day, payment totals that a more specific change explains are left out, each group has member_removal (the October/April removal of unpaid members, or null), and pages count day groups. One of: `day`.

**Returns**

- `success` (boolean)
- `area` (object)
  - `district` (string)
  - `division` (string)
  - `area` (string)
- `data` (array of objects)
  - `category` (enum) One of: `lifecycle`, `membership`, `education`, `status`, `renewals`.
  - `metric` (string)
  - `event_count` (integer)
  - `clubs_affected` (integer)
  - `total_delta` (nullable number): Sum of numeric deltas across the selected area and period; null when the metric is non-numeric.
  - `first_comparison_date` (date)
  - `last_comparison_date` (date)
  - `clubs` (array of objects)
    - `club_number` (string)
    - `club_name` (nullable string)
    - `division` (nullable string)
    - `area` (nullable string)
    - `event_count` (integer)
    - `total_delta` (nullable number): Sum of numeric event deltas for this club; null for non-numeric metrics such as lifecycle events.
    - `first_comparison_date` (date)
    - `last_comparison_date` (date)
    - `changes` (array of objects)
      - `comparison_date` (date)
      - `previous_date` (date)
      - `change_type` (enum) One of: `increased`, `decreased`, `changed`, `club_added`, `club_removed`.
      - `old_value` (nullable string)
      - `new_value` (nullable string)
      - `old_value_numeric` (nullable number)
      - `new_value_numeric` (nullable number)
      - `delta_numeric` (nullable number)
  - `member_removal` (nullable object): view=day only: members removed for unpaid dues, when this is an October or April active-member drop; otherwise null.
    - `period` (enum) One of: `October`, `April`.
    - `removed` (integer): Members removed (the drop in active members).
    - `clubs` (integer): Clubs whose active members fell.
- `pagination` (object): Pagination returned by member-payments endpoints. total is the total matching records.
  - `total` (integer): Total matching records
  - `limit` (integer): Number of records per page
  - `offset` (integer): Number of records to skip
  - `has_more` (boolean): Whether there are more records available
- `filters` (object)
- `timestamp` (timestamp)

**Errors**

- `422`: Invalid area changelog query
- `500`: Internal server error

**Example request**

```bash
curl "https://tm-api.devinpearson.me/api/district/74/area/A/01/changelog"
```

**Example response**

```json
{
  "success": true,
  "area": {
    "district": "74",
    "division": "A",
    "area": "01"
  },
  "data": [
    {
      "category": "lifecycle",
      "metric": "string",
      "event_count": 1,
      "clubs_affected": 1,
      "total_delta": 0,
      "first_comparison_date": "2026-11-19",
      "last_comparison_date": "2026-11-19",
      "clubs": [
        {
          "club_number": "113",
          "club_name": "Example Toastmasters Club",
          "division": "A",
          "area": "01",
          "event_count": 1,
          "total_delta": 0,
          "first_comparison_date": "2026-11-19",
          "last_comparison_date": "2026-11-19",
          "changes": [
            {}
          ]
        }
      ],
      "member_removal": {
        "period": "October",
        "removed": 0,
        "clubs": 0
      }
    }
  ],
  "pagination": {
    "total": 0,
    "limit": 0,
    "offset": 0,
    "has_more": true
  },
  "filters": {},
  "timestamp": "2026-11-19T04:30:00.000Z"
}
```

## Get area data

`GET /api/district/{district}/area/{division}/{area}`

Retrieve area-level data. Club ratios use authoritative award totals divided by mem_base. Area goal and educational benchmarks are unweighted arithmetic club means; undefined ratios and empty averages are null.

**Path parameters**

- `district` (string, required)
- `division` (string, required)
- `area` (string, required)

**Query parameters**

- `fiscalYear` (string, optional): Fiscal year (YYYY-YYYY); defaults to the current fiscal year
- `date` (date, optional): Specific date to filter by (YYYY-MM-DD)
- `startDate` (date, optional): First report date to include (YYYY-MM-DD)
- `endDate` (date, optional): Last report date to include (YYYY-MM-DD); on or after startDate
- `latest` (enum, optional): true skips the cached response and sends Cache-Control: no-store One of: `true`, `false`.
- `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` (object)
  - `area` (object)
    - `area_average_goals_met` (nullable number)
    - `area_educational_ratio` (nullable number)
  - `division_metrics` (object): Compatibility object containing area-level benchmarks; these are not division-wide metrics.
    - `area_average_goals_met` (nullable number)
    - `area_educational_ratio` (nullable number)
  - `clubs` (array of objects)
    - `club_number` (string)
    - `club_name` (string)
    - `club_outlook` (object): Area responses only: the club's outlook, as on the club dashboard.
      - `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)
    - `educational_awards` (number): Sum of level_1s, level_2s, add_level_2s, level_3s, level_4s_path_completions_or_dtm_awards, and add_level_4s_path_completions_or_dtm_award.
    - `educational_ratio` (nullable number): Educational awards divided by mem_base; null when mem_base is zero.
    - `average_goals_met` (nullable number): Compatibility field on division responses containing this club's own goals_met value.
    - `nov_visit_award` (nullable number): 1 when the club's first-round (July–November) area director visit is recorded, otherwise 0.
    - `may_visit_award` (nullable number): 1 when the club's second-round (December–May) area director visit is recorded, otherwise 0.
    - `area_average_goals_met` (nullable number): Arithmetic mean of goals_met across clubs in the selected area.
    - `area_average_educational_ratio` (nullable number): Arithmetic mean of defined club educational ratios in the selected area.
    - `goals_vs_area_average` (nullable enum) One of: `above`, `below`, `at`.
    - `educational_ratio_vs_area_average` (nullable enum) One of: `above`, `below`, `at`.
    - `july_officer_list` (array of objects): July officer list entries for the club in the selected fiscal year
      - `list_status` (nullable string)
      - `election_type` (nullable string)
      - `date` (nullable date)
    - `july_officer_list_status` (boolean): True when latest July officer list status indicates Received, else false
  - `insights` (nullable object): Toastmasters rules evaluated for the area as of the report date (src/domain): the Area Director's next actions, the area's Distinguished status, the visit and officer-training rounds, and each club's milestone and reminders. Null when the area has no club rows with a date.
    - `as_of` (date): Report date: the newest club row in the area.
    - `month` (string)
    - `month_target` (integer): Goals a club should have met by this month.
    - `distinguished_status` (nullable enum) One of: `D`, `S`, `P`, `null`.
    - `next_actions` (array of objects): Most time-sensitive first.
      - `code` (string): Stable identifier: good-standing, nov-visits, may-visits, training-round-2, small-clubs, csp or distinguished-area.
      - `key` (string): Same as code.
      - `title` (string)
      - `hint` (string)
      - `when` (string): When it's due, e.g. "due 30 Nov".
    - `on_track_clubs` (integer): Clubs with 20+ members and at least this month's target of goals.
    - `visits` (object)
      - `nov` (object)
        - `clubs_visited` (integer)
        - `clubs_required` (integer): 75% of the area's club base, rounded up (its clubs when it has no base).
        - `visited_pct` (integer): Visited share of the club base.
        - `status` (object)
          - `state` (enum) One of: `met`, `notDue`, `missed`.
          - `dueLabel` (string)
        - `window_open` (boolean)
      - `may` (object)
        - `clubs_visited` (integer)
        - `clubs_required` (integer): 75% of the area's club base, rounded up (its clubs when it has no base).
        - `visited_pct` (integer): Visited share of the club base.
        - `status` (object)
          - `state` (enum) One of: `met`, `notDue`, `missed`.
          - `dueLabel` (string)
        - `window_open` (boolean)
    - `officer_training` (object)
      - `round_1` (object)
        - `clubs_counted` (integer): Clubs that count for the round: not suspended, and for round 1 chartered by 31 August.
        - `officers_trained` (integer)
        - `officers_possible` (integer): 7 officers per counted club.
        - `trained_pct` (nullable integer)
        - `window_open` (boolean)
      - `round_2` (object)
        - `clubs_counted` (integer): Clubs that count for the round: not suspended, and for round 1 chartered by 31 August.
        - `officers_trained` (integer)
        - `officers_possible` (integer): 7 officers per counted club.
        - `trained_pct` (nullable integer)
        - `window_open` (boolean)
    - `clubs` (array of objects)
      - `club_number` (string)
      - `club_name` (string)
      - `progress` (object): Distinguished level achieved and what the next needs.
      - `milestone` (object)
        - `achieved` (nullable string)
        - `next` (nullable string)
      - `below_month_target` (boolean)
      - `needs` (object): Reminders that apply now: an open window and a requirement not yet met.
        - `officers_round_1` (boolean)
        - `officers_round_2` (boolean)
        - `nov_visit` (boolean)
        - `may_visit` (boolean)
        - `club_success_plan` (boolean)
        - `club_coach` (boolean)
      - `officers_round_2_due` (object)
        - `state` (enum) One of: `met`, `notDue`, `missed`.
        - `dueLabel` (string)
      - `nov_visit_due` (object)
        - `state` (enum) One of: `met`, `notDue`, `missed`.
        - `dueLabel` (string)
      - `may_visit_due` (object)
        - `state` (enum) One of: `met`, `notDue`, `missed`.
        - `dueLabel` (string)
  - `month_change` (object or nullable enum): The area's totals against the fiscal month before, with each club's change in parts; null when no clubs were reported for the month.
    - `fiscal_year` (string)
    - `fiscal_month` (integer): Fiscal month (1 = July) of the figures.
    - `previous_fiscal_month` (nullable integer): The fiscal month compared with; null in July, which starts the fiscal year.
    - `current` (object): A scope'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)
      - `active_members` (integer)
      - `goals_met` (integer): DCP goals met, summed over the clubs.
      - `educational_awards` (integer)
      - `new_members` (integer): New and additional new members counted for the DCP.
    - `previous` (object or nullable enum): Last month's totals; null in July or when no clubs were reported last month.
      - `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)
      - `active_members` (integer)
      - `goals_met` (integer): DCP goals met, summed over the clubs.
      - `educational_awards` (integer)
      - `new_members` (integer): New and additional new members counted for the DCP.
    - `change` (object or nullable enum): This month's totals minus last month'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)
      - `active_members` (integer)
      - `goals_met` (integer): DCP goals met, summed over the clubs.
      - `educational_awards` (integer)
      - `new_members` (integer): New and additional new members counted for the DCP.
    - `clubs_added` (array of strings): Clubs here this month but not last month: chartered or moved in.
    - `clubs_removed` (array of strings): Clubs here last month but not this month: moved out or no longer reported.
    - `parts` (array of objects)
      - `key` (string): The division letter, area number or club number.
      - `current` (object): A scope'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)
        - `active_members` (integer)
        - `goals_met` (integer): DCP goals met, summed over the clubs.
        - `educational_awards` (integer)
        - `new_members` (integer): New and additional new members counted for the DCP.
      - `previous` (object or nullable enum): Last month's totals; null in July or when no clubs were reported last month.
        - `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)
        - `active_members` (integer)
        - `goals_met` (integer): DCP goals met, summed over the clubs.
        - `educational_awards` (integer)
        - `new_members` (integer): New and additional new members counted for the DCP.
      - `change` (object or nullable enum): This month's totals minus last month'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)
        - `active_members` (integer)
        - `goals_met` (integer): DCP goals met, summed over the clubs.
        - `educational_awards` (integer)
        - `new_members` (integer): New and additional new members counted for the DCP.
      - `clubs_added` (array of strings): Clubs here this month but not last month: chartered or moved in.
      - `clubs_removed` (array of strings): Clubs here last month but not this month: moved out or no longer reported.

**Errors**

- `422`: A path or query parameter has an invalid value
- `500`: Internal server error

**Example request**

```bash
curl "https://tm-api.devinpearson.me/api/district/74/area/A/01"
```

**Example response**

```json
{
  "success": true,
  "data": {
    "area": {
      "area_average_goals_met": 0,
      "area_educational_ratio": 0
    },
    "division_metrics": {
      "area_average_goals_met": 0,
      "area_educational_ratio": 0
    },
    "clubs": [
      {
        "club_number": "113",
        "club_name": "Example Toastmasters Club",
        "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": [
            {}
          ]
        },
        "educational_awards": 0,
        "educational_ratio": 0,
        "average_goals_met": 0,
        "nov_visit_award": 0,
        "may_visit_award": 0,
        "area_average_goals_met": 0,
        "area_average_educational_ratio": 0,
        "goals_vs_area_average": "above",
        "educational_ratio_vs_area_average": "above",
        "july_officer_list": [
          {
            "list_status": "string",
            "election_type": "string",
            "date": "2026-11-19"
          }
        ],
        "july_officer_list_status": true
      }
    ],
    "insights": {
      "as_of": "2026-11-19",
      "month": "string",
      "month_target": 0,
      "distinguished_status": "D",
      "next_actions": [
        {
          "code": "string",
          "key": "string",
          "title": "string",
          "hint": "string",
          "when": "string"
        }
      ],
      "on_track_clubs": 0,
      "visits": {
        "nov": {
          "clubs_visited": 0,
          "clubs_required": 0,
          "visited_pct": 0,
          "status": {
            "state": "met",
            "dueLabel": "string"
          },
          "window_open": true
        },
        "may": {
          "clubs_visited": 0,
          "clubs_required": 0,
          "visited_pct": 0,
          "status": {
            "state": "met",
            "dueLabel": "string"
          },
          "window_open": true
        }
      },
      "officer_training": {
        "round_1": {
          "clubs_counted": 0,
          "officers_trained": 0,
          "officers_possible": 0,
          "trained_pct": 0,
          "window_open": true
        },
        "round_2": {
          "clubs_counted": 0,
          "officers_trained": 0,
          "officers_possible": 0,
          "trained_pct": 0,
          "window_open": true
        }
      },
      "clubs": [
        {
          "club_number": "113",
          "club_name": "Example Toastmasters Club",
          "progress": {},
          "milestone": {
            "achieved": "string",
            "next": "string"
          },
          "below_month_target": true,
          "needs": {
            "officers_round_1": true,
            "officers_round_2": true,
            "nov_visit": true,
            "may_visit": true,
            "club_success_plan": true,
            "club_coach": true
          },
          "officers_round_2_due": {
            "state": "met",
            "dueLabel": "string"
          },
          "nov_visit_due": {
            "state": "met",
            "dueLabel": "string"
          },
          "may_visit_due": {
            "state": "met",
            "dueLabel": "string"
          }
        }
      ]
    },
    "month_change": {
      "fiscal_year": "2026-2027",
      "fiscal_month": 5,
      "previous_fiscal_month": 1,
      "current": {
        "clubs": 0,
        "suspended_clubs": 0,
        "paid_clubs": 0,
        "distinguished_clubs": 0,
        "active_members": 0,
        "goals_met": 0,
        "educational_awards": 0,
        "new_members": 0
      },
      "previous": {
        "clubs": 0,
        "suspended_clubs": 0,
        "paid_clubs": 0,
        "distinguished_clubs": 0,
        "active_members": 0,
        "goals_met": 0,
        "educational_awards": 0,
        "new_members": 0
      },
      "change": {
        "clubs": 0,
        "suspended_clubs": 0,
        "paid_clubs": 0,
        "distinguished_clubs": 0,
        "active_members": 0,
        "goals_met": 0,
        "educational_awards": 0,
        "new_members": 0
      },
      "clubs_added": [
        "string"
      ],
      "clubs_removed": [
        "string"
      ],
      "parts": [
        {
          "key": "string",
          "current": {
            "clubs": 0,
            "suspended_clubs": 0,
            "paid_clubs": 0,
            "distinguished_clubs": 0,
            "active_members": 0,
            "goals_met": 0,
            "educational_awards": 0,
            "new_members": 0
          },
          "previous": {
            "clubs": 0,
            "suspended_clubs": 0,
            "paid_clubs": 0,
            "distinguished_clubs": 0,
            "active_members": 0,
            "goals_met": 0,
            "educational_awards": 0,
            "new_members": 0
          },
          "change": {
            "clubs": 0,
            "suspended_clubs": 0,
            "paid_clubs": 0,
            "distinguished_clubs": 0,
            "active_members": 0,
            "goals_met": 0,
            "educational_awards": 0,
            "new_members": 0
          },
          "clubs_added": [
            "string"
          ],
          "clubs_removed": [
            "string"
          ]
        }
      ]
    }
  }
}
```
