# 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"
          ]
        }
      ]
    }
  }
}
```
