# Tools

Planning tools that evaluate a hypothetical area or division made of existing clubs, to see how a regrouping would stand against the recognition goals.

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

## Evaluate a hypothetical area

`POST /api/tools/hypothetical-area`

Groups existing clubs into one new area and evaluates it as of the clubs' report date: paid, Distinguished and 20+ member clubs, average goals against the month's target, the educational ratio, Area Director visits, member payments, and the area's Distinguished status with the standard goals. Suspended clubs are listed but not counted.

**Request body (JSON)**

- `club_numbers` (array of strings, required): Club numbers; leading zeros are ignored and repeats are dropped.

**Returns**

- `success` (boolean)
- `data` (object)
  - `as_of` (date): The newest of the clubs' report dates.
  - `month` (string)
  - `month_target` (integer): Goals a club should have met by this month.
  - `clubs` (array of objects)
    - `club_number` (string)
    - `club_name` (string)
    - `district` (string)
    - `division` (string)
    - `area` (string): The club's current area.
    - `assigned_area` (string): Hypothetical division only: the new area the club was assigned to.
    - `club_status` (string)
    - `suspended` (boolean): Suspended clubs are listed but left out of every total.
    - `charter_date` (nullable string)
    - `active_members` (integer)
    - `member_base` (integer)
    - `goals_met` (integer)
    - `educational_awards` (integer)
    - `educational_ratio` (nullable number)
    - `officers_trained_round_1` (integer)
    - `officers_trained_round_2` (integer)
    - `october_renewals` (boolean)
    - `april_renewals` (boolean)
    - `nov_visit` (boolean)
    - `may_visit` (boolean)
    - `coaches` (integer)
    - `distinguished_status` (nullable enum) One of: `D`, `S`, `P`, `M`, `null`.
    - `member_payments` (object)
      - `late` (integer)
      - `oct_ren` (integer)
      - `apr_ren` (integer)
      - `total_ren` (integer)
      - `new` (integer)
      - `charter` (integer)
      - `total_new` (integer)
    - `latitude` (nullable number)
    - `longitude` (nullable number)
    - `location` (nullable string)
    - `address` (nullable string)
    - `feedback` (object): What the club still needs as of the report date.
      - `needs_attention` (boolean): Fewer than 20 members or fewer than 5 goals.
      - `members_needed` (integer): Members still needed to reach 20.
      - `needs_coach` (boolean): Fewer than 10 members and no coach assigned.
      - `officers_round_1_needed` (boolean)
      - `officers_round_2_needed` (boolean)
      - `nov_visit_needed` (boolean)
      - `may_visit_needed` (boolean)
  - `current_areas` (array of objects): Where the counted clubs are today, largest group first.
    - `district` (string)
    - `division` (string)
    - `area` (string)
    - `clubs` (integer)
  - `summary` (object)
    - `paid_clubs` (integer): Clubs that aren't suspended.
    - `total_members` (integer)
    - `member_base` (integer)
    - `distinguished_clubs` (integer)
    - `twenty_plus_member_clubs` (integer)
    - `on_track_clubs` (integer): Clubs with 20+ members and at least this month's target of goals.
    - `average_goals` (number)
    - `member_payments` (object)
      - `late` (integer)
      - `oct_ren` (integer)
      - `apr_ren` (integer)
      - `total_ren` (integer)
      - `new` (integer)
      - `charter` (integer)
      - `total_new` (integer)
    - `distinguished_pct` (number)
    - `twenty_plus_member_pct` (number)
    - `educational_awards` (integer)
    - `educational_ratio` (nullable number)
    - `visits` (object)
      - `goal` (integer): Clubs to visit in each round: 75% of paid clubs.
      - `nov` (object)
        - `visited` (integer)
        - `pct` (integer)
      - `may` (object)
        - `visited` (integer)
        - `pct` (integer)
    - `distinguished_status` (nullable enum): Derived with the standard goals once both visit rounds are met. One of: `D`, `S`, `P`, `null`.
  - `recognition_goals` (object): The standard recognition goals: paid clubs and Distinguished clubs for each level.
    - `distinguished` (object)
      - `paid_clubs` (integer)
      - `distinguished_clubs` (integer)
    - `select_distinguished` (object)
      - `paid_clubs` (integer)
      - `distinguished_clubs` (integer)
    - `presidents_distinguished` (object)
      - `paid_clubs` (integer)
      - `distinguished_clubs` (integer)
  - `not_found` (array of strings): Club numbers that weren't found.
- `timestamp` (timestamp)

**Errors**

- `400`: The request body is not valid JSON
- `422`: The body was read but a value in it is invalid
- `500`: Internal server error

**Example request**

```bash
curl -X POST "https://tm-api.devinpearson.me/api/tools/hypothetical-area" \
  -H "Content-Type: application/json" \
  -d '{"club_numbers":["113"]}'
```

**Example response**

```json
{
  "success": true,
  "data": {
    "as_of": "2026-11-19",
    "month": "string",
    "month_target": 0,
    "clubs": [
      {
        "club_number": "113",
        "club_name": "Example Toastmasters Club",
        "district": "74",
        "division": "A",
        "area": "01",
        "assigned_area": "string",
        "club_status": "string",
        "suspended": true,
        "charter_date": "string",
        "active_members": 0,
        "member_base": 0,
        "goals_met": 0,
        "educational_awards": 0,
        "educational_ratio": 0,
        "officers_trained_round_1": 0,
        "officers_trained_round_2": 0,
        "october_renewals": true,
        "april_renewals": true,
        "nov_visit": true,
        "may_visit": true,
        "coaches": 0,
        "distinguished_status": "D",
        "member_payments": {
          "late": 0,
          "oct_ren": 0,
          "apr_ren": 0,
          "total_ren": 0,
          "new": 0,
          "charter": 0,
          "total_new": 0
        },
        "latitude": 0,
        "longitude": 0,
        "location": "string",
        "address": "string",
        "feedback": {
          "needs_attention": true,
          "members_needed": 0,
          "needs_coach": true,
          "officers_round_1_needed": true,
          "officers_round_2_needed": true,
          "nov_visit_needed": true,
          "may_visit_needed": true
        }
      }
    ],
    "current_areas": [
      {
        "district": "74",
        "division": "A",
        "area": "01",
        "clubs": 0
      }
    ],
    "summary": {
      "paid_clubs": 0,
      "total_members": 0,
      "member_base": 0,
      "distinguished_clubs": 0,
      "twenty_plus_member_clubs": 0,
      "on_track_clubs": 0,
      "average_goals": 0,
      "member_payments": {
        "late": 0,
        "oct_ren": 0,
        "apr_ren": 0,
        "total_ren": 0,
        "new": 0,
        "charter": 0,
        "total_new": 0
      },
      "distinguished_pct": 0,
      "twenty_plus_member_pct": 0,
      "educational_awards": 0,
      "educational_ratio": 0,
      "visits": {
        "goal": 0,
        "nov": {
          "visited": 0,
          "pct": 0
        },
        "may": {
          "visited": 0,
          "pct": 0
        }
      },
      "distinguished_status": "D"
    },
    "recognition_goals": {
      "distinguished": {
        "paid_clubs": 0,
        "distinguished_clubs": 0
      },
      "select_distinguished": {
        "paid_clubs": 0,
        "distinguished_clubs": 0
      },
      "presidents_distinguished": {
        "paid_clubs": 0,
        "distinguished_clubs": 0
      }
    },
    "not_found": [
      "string"
    ]
  },
  "timestamp": "2026-11-19T04:30:00.000Z"
}
```

## Evaluate a hypothetical division

`POST /api/tools/hypothetical-division`

Groups existing clubs into new areas of one division and evaluates the division and each area as of the clubs' report date. Suspended clubs are listed but not counted.

**Request body (JSON)**

- `areas` (array of objects, required): The new areas; a club listed in two areas stays in the first.
  - `area` (string, required)
  - `club_numbers` (array of strings, required): Club numbers; leading zeros are ignored and repeats are dropped.

**Returns**

- `success` (boolean)
- `data` (object)
  - `as_of` (date): The newest of the clubs' report dates.
  - `month` (string)
  - `month_target` (integer): Goals a club should have met by this month.
  - `clubs` (array of objects)
    - `club_number` (string)
    - `club_name` (string)
    - `district` (string)
    - `division` (string)
    - `area` (string): The club's current area.
    - `assigned_area` (string): Hypothetical division only: the new area the club was assigned to.
    - `club_status` (string)
    - `suspended` (boolean): Suspended clubs are listed but left out of every total.
    - `charter_date` (nullable string)
    - `active_members` (integer)
    - `member_base` (integer)
    - `goals_met` (integer)
    - `educational_awards` (integer)
    - `educational_ratio` (nullable number)
    - `officers_trained_round_1` (integer)
    - `officers_trained_round_2` (integer)
    - `october_renewals` (boolean)
    - `april_renewals` (boolean)
    - `nov_visit` (boolean)
    - `may_visit` (boolean)
    - `coaches` (integer)
    - `distinguished_status` (nullable enum) One of: `D`, `S`, `P`, `M`, `null`.
    - `member_payments` (object)
      - `late` (integer)
      - `oct_ren` (integer)
      - `apr_ren` (integer)
      - `total_ren` (integer)
      - `new` (integer)
      - `charter` (integer)
      - `total_new` (integer)
    - `latitude` (nullable number)
    - `longitude` (nullable number)
    - `location` (nullable string)
    - `address` (nullable string)
    - `feedback` (object): What the club still needs as of the report date.
      - `needs_attention` (boolean): Fewer than 20 members or fewer than 5 goals.
      - `members_needed` (integer): Members still needed to reach 20.
      - `needs_coach` (boolean): Fewer than 10 members and no coach assigned.
      - `officers_round_1_needed` (boolean)
      - `officers_round_2_needed` (boolean)
      - `nov_visit_needed` (boolean)
      - `may_visit_needed` (boolean)
  - `areas` (array of objects)
    - `area` (string)
    - `paid_clubs` (integer)
    - `total_members` (integer)
    - `distinguished_clubs` (integer)
    - `twenty_plus_member_clubs` (integer)
    - `five_plus_goal_clubs` (integer)
    - `officers_round_1_clubs` (integer): Clubs with 4+ officers trained in round 1.
    - `officers_round_2_clubs` (integer)
    - `average_goals` (number)
  - `summary` (object)
    - `paid_clubs` (integer): Clubs that aren't suspended.
    - `total_members` (integer)
    - `member_base` (integer)
    - `distinguished_clubs` (integer)
    - `twenty_plus_member_clubs` (integer)
    - `on_track_clubs` (integer): Clubs with 20+ members and at least this month's target of goals.
    - `average_goals` (number)
    - `member_payments` (object)
      - `late` (integer)
      - `oct_ren` (integer)
      - `apr_ren` (integer)
      - `total_ren` (integer)
      - `new` (integer)
      - `charter` (integer)
      - `total_new` (integer)
  - `recognition_goals` (object): The standard recognition goals: paid clubs and Distinguished clubs for each level.
    - `distinguished` (object)
      - `paid_clubs` (integer)
      - `distinguished_clubs` (integer)
    - `select_distinguished` (object)
      - `paid_clubs` (integer)
      - `distinguished_clubs` (integer)
    - `presidents_distinguished` (object)
      - `paid_clubs` (integer)
      - `distinguished_clubs` (integer)
  - `not_found` (array of strings)
- `timestamp` (timestamp)

**Errors**

- `400`: The request body is not valid JSON
- `422`: The body was read but a value in it is invalid
- `500`: Internal server error

**Example request**

```bash
curl -X POST "https://tm-api.devinpearson.me/api/tools/hypothetical-division" \
  -H "Content-Type: application/json" \
  -d '{"areas":[{"area":"01","club_numbers":["113"]}]}'
```

**Example response**

```json
{
  "success": true,
  "data": {
    "as_of": "2026-11-19",
    "month": "string",
    "month_target": 0,
    "clubs": [
      {
        "club_number": "113",
        "club_name": "Example Toastmasters Club",
        "district": "74",
        "division": "A",
        "area": "01",
        "assigned_area": "string",
        "club_status": "string",
        "suspended": true,
        "charter_date": "string",
        "active_members": 0,
        "member_base": 0,
        "goals_met": 0,
        "educational_awards": 0,
        "educational_ratio": 0,
        "officers_trained_round_1": 0,
        "officers_trained_round_2": 0,
        "october_renewals": true,
        "april_renewals": true,
        "nov_visit": true,
        "may_visit": true,
        "coaches": 0,
        "distinguished_status": "D",
        "member_payments": {
          "late": 0,
          "oct_ren": 0,
          "apr_ren": 0,
          "total_ren": 0,
          "new": 0,
          "charter": 0,
          "total_new": 0
        },
        "latitude": 0,
        "longitude": 0,
        "location": "string",
        "address": "string",
        "feedback": {
          "needs_attention": true,
          "members_needed": 0,
          "needs_coach": true,
          "officers_round_1_needed": true,
          "officers_round_2_needed": true,
          "nov_visit_needed": true,
          "may_visit_needed": true
        }
      }
    ],
    "areas": [
      {
        "area": "01",
        "paid_clubs": 0,
        "total_members": 0,
        "distinguished_clubs": 0,
        "twenty_plus_member_clubs": 0,
        "five_plus_goal_clubs": 0,
        "officers_round_1_clubs": 0,
        "officers_round_2_clubs": 0,
        "average_goals": 0
      }
    ],
    "summary": {
      "paid_clubs": 0,
      "total_members": 0,
      "member_base": 0,
      "distinguished_clubs": 0,
      "twenty_plus_member_clubs": 0,
      "on_track_clubs": 0,
      "average_goals": 0,
      "member_payments": {
        "late": 0,
        "oct_ren": 0,
        "apr_ren": 0,
        "total_ren": 0,
        "new": 0,
        "charter": 0,
        "total_new": 0
      }
    },
    "recognition_goals": {
      "distinguished": {
        "paid_clubs": 0,
        "distinguished_clubs": 0
      },
      "select_distinguished": {
        "paid_clubs": 0,
        "distinguished_clubs": 0
      },
      "presidents_distinguished": {
        "paid_clubs": 0,
        "distinguished_clubs": 0
      }
    },
    "not_found": [
      "string"
    ]
  },
  "timestamp": "2026-11-19T04:30:00.000Z"
}
```
