{"openapi":"3.0.0","info":{"title":"Toastmasters API","version":"1.0.0","description":"Toastmasters reporting data for the Region → District → Division → Area → Club hierarchy, built from Toastmasters' daily reports. Fiscal years run July–June and are written YYYY-YYYY; fiscal month 1 is July. Dates are YYYY-MM-DD. Errors are RFC 9457 problem details, sent as application/problem+json. A request with an invalid value is answered 422; 400 means the request could not be read at all, such as a body that is not valid JSON."},"servers":[{"url":"https://tm-api.devinpearson.me","description":"Production"},{"url":"http://localhost:3000","description":"Local development"}],"tags":[{"name":"Club","description":"A Toastmasters club, identified by its club number. Club numbers are returned without leading zeros, and a request may send them either way.\n\nA club belongs to an area, which belongs to a division, which belongs to a district. The club dashboard reports the club's membership, its progress on the 10 Distinguished Club Program goals, dues renewals, officer training and recognition status as of a report date, with insights such as good standing and the next actions for its officers. The changelog lists what changed in the club's figures from one report to the next."},{"name":"Area","description":"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.\n\nThe 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."},{"name":"Division","description":"A division is a group of areas within a district, led by a Division Director. It is identified by its district and a letter, for example district 74, division A.\n\nThe division dashboard reports the division's totals, its areas and their clubs, and its progress towards Distinguished Division recognition. The changelog groups what changed across every area in the division."},{"name":"District","description":"A district is a group of divisions, led by a District Director. It is identified by a number, except F for Founders District and U for clubs that belong to no district.\n\nThe district dashboard reports the district's totals and recognition goals, its divisions with their areas and clubs, its history month by month and its prospective clubs. Other endpoints compare a district with the same month last year and rank its clubs by their history."},{"name":"Region","description":"A region is a group of districts, supported by a Region Advisor. It is identified by its number.\n\nThe region endpoint reports each district in the region with its payments, club counts and recognition figures."},{"name":"Global","description":"Every district and region together: each district's payments, recognition counts and goals, each region's totals, and the worldwide totals for a fiscal year."},{"name":"DCP History","description":"A club's Distinguished Club Program results for each completed fiscal year: the goals it met, its membership at the start and end of the year and the recognition it earned. The fiscal year in progress is not included."},{"name":"Club Performance","description":"Rankings of clubs across a district, such as the clubs with the most educational awards for their size."},{"name":"Dropdown","description":"Lists of the regions, districts, divisions and areas that exist in the current fiscal year, and the fiscal years, months and report dates that have data. They are meant for building filters and menus."},{"name":"Tools","description":"Planning tools that evaluate a hypothetical area or division made of existing clubs, to see how a regrouping would stand against the recognition goals."},{"name":"Health","description":"Health, readiness and liveness probes for monitoring the service. They report a status word in plain JSON, not problem details."},{"name":"API","description":"The route index: the API's route groups and where its documentation is."}],"paths":{"/api/reports/top-educational-awards-ratio":{"get":{"summary":"Get top clubs by educational awards ratio","description":"Retrieve clubs with the highest ratio of educational awards to members","tags":["Club Performance"],"parameters":[{"name":"district","in":"query","required":false,"description":"District to rank; defaults to 74","schema":{"type":"string","default":"74"}},{"$ref":"#/components/parameters/FiscalYear"},{"name":"date","in":"query","required":false,"description":"Rank as of the fiscal month this date falls in (YYYY-MM-DD)","schema":{"type":"string","format":"date"}},{"name":"division","in":"query","required":false,"description":"Only clubs in this division","schema":{"type":"string"}},{"name":"area","in":"query","required":false,"description":"Only clubs in this area","schema":{"type":"string"}},{"name":"minBase","in":"query","required":false,"description":"Smallest July 1 member base a club needs to be ranked","schema":{"type":"integer","minimum":0,"default":1}},{"name":"minAwards","in":"query","required":false,"description":"Fewest educational awards a club needs to be ranked","schema":{"type":"integer","minimum":0,"default":1}},{"name":"limit","in":"query","description":"Number of top clubs to return (default: 10)","required":false,"schema":{"type":"integer","default":10,"minimum":1,"maximum":1000}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"rank":{"type":"integer"},"club_number":{"type":"string"},"club_name":{"type":"string"},"division":{"type":"string"},"area":{"type":"string"},"educational_awards":{"type":"integer"},"july_1_base":{"type":"number"},"ratio":{"type":"number"},"awards_breakdown":{"type":"object","properties":{"level_1s":{"type":"number"},"level_2s":{"type":"number"},"additional_level_2s":{"type":"number"},"level_3s":{"type":"number"},"level_4s":{"type":"number"},"additional_level_4s":{"type":"number"}}}}}},"summary":{"type":"object","properties":{"total_clubs_analyzed":{"type":"integer"},"total_clubs_returned":{"type":"integer"},"analysis_date":{"type":"string","format":"date"},"overall_statistics":{"type":"object"},"top_performer":{"type":"object","nullable":true},"division_summary":{"type":"array","items":{"type":"object"}}}},"filters":{"type":"object"},"timestamp":{"type":"string","format":"date-time"}}}}}},"422":{"description":"A path or query parameter has an invalid value","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}},"500":{"description":"Internal server error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/reports/dcp-history":{"get":{"summary":"Get DCP history for a club","description":"Retrieve Distinguished Club Program (DCP) historical performance data for a specific club across multiple fiscal years","tags":["DCP History"],"parameters":[{"name":"clubNumber","in":"query","description":"Club number (required). Leading zeros are automatically trimmed (e.g., \"0113\" becomes \"113\")","required":true,"schema":{"type":"string"}},{"name":"fiscalYear","in":"query","description":"Filter by fiscal year in legacy YY-YY (e.g., \"24-25\") or normalized YYYY-YYYY form.","required":false,"schema":{"type":"string","pattern":"^(?:[0-9]{2}-[0-9]{2}|[0-9]{4}-[0-9]{4})$"}},{"$ref":"#/components/parameters/District"},{"name":"area","in":"query","description":"Filter by area","required":false,"schema":{"type":"string"}},{"name":"division","in":"query","description":"Filter by division","required":false,"schema":{"type":"string"}},{"name":"award","in":"query","description":"Filter by award received (e.g., \"Distinguished\", \"Select Distinguished\", \"President's Distinguished\")","required":false,"schema":{"type":"string"}},{"name":"sortBy","in":"query","description":"Field to sort by (default: \"fiscal_year\")","required":false,"schema":{"type":"string","enum":["fiscal_year","total_goals","retention_rate","memb_base_7_1","year_end_memb"],"default":"fiscal_year"}},{"name":"sortOrder","in":"query","description":"Sort order (default: \"desc\" for most recent first)","required":false,"schema":{"type":"string","enum":["asc","desc"],"default":"desc"}},{"$ref":"#/components/parameters/Limit"},{"$ref":"#/components/parameters/Offset"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"array","items":{"$ref":"#/components/schemas/DCPHistory"}},"summary":{"type":"object","properties":{"total_records":{"type":"integer"},"fiscal_years_covered":{"type":"integer"},"average_goals_achieved":{"type":"number"},"average_retention_rate":{"type":"number"},"awards_received":{"type":"integer"},"best_year":{"type":"object","properties":{"fiscal_year":{"type":"string"},"total_goals":{"type":"integer"},"retention_rate":{"type":"number"},"award":{"type":"string"}}},"worst_year":{"type":"object","properties":{"fiscal_year":{"type":"string"},"total_goals":{"type":"integer"},"retention_rate":{"type":"number"},"award":{"type":"string"}}},"goal_achievement_by_category":{"type":"object","properties":{"traditional_goals":{"type":"integer"},"pathways_goals":{"type":"integer"},"general_goals":{"type":"integer"},"total_goals":{"type":"integer"}}},"membership_trends":{"type":"array","items":{"type":"object","properties":{"fiscal_year":{"type":"string"},"memb_base_7_1":{"type":"integer"},"year_end_memb":{"type":"integer"},"retention_rate":{"type":"number"}}}},"club_info":{"type":"object","properties":{"club_number":{"type":"string"},"club_name":{"type":"string"},"district":{"type":"string"},"area":{"type":"string"},"division":{"type":"string"}}}}},"pagination":{"$ref":"#/components/schemas/RecordCountPagination"},"sorting":{"type":"object","required":["sort_by","sort_order","fiscal_years_in_result"],"properties":{"sort_by":{"type":"string","enum":["fiscal_year","total_goals","retention_rate","memb_base_7_1","year_end_memb"]},"sort_order":{"type":"string","enum":["asc","desc"]},"fiscal_years_in_result":{"type":"array","items":{"type":"string"}}}},"filters":{"type":"object"}}}}}},"422":{"description":"clubNumber is missing or invalid","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/reports/dcp-history/analysis":{"get":{"summary":"Get detailed DCP history analysis for a club","description":"Retrieve comprehensive DCP performance analysis plus reusable completed-programme-year historical health analysis. Configuration 2.0 separates recent Distinguished-history class, benchmark-adjusted membership-risk trajectory, and diagnostic composite score. The existing 404 is retained when the club has no DCP-history rows.","tags":["DCP History"],"parameters":[{"name":"clubNumber","in":"query","description":"Club number (required). Leading zeros are automatically trimmed (e.g., \"0113\" becomes \"113\")","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"array","items":{"$ref":"#/components/schemas/DCPHistory"}},"analysis":{"type":"object","properties":{"performance_trends":{"type":"array","items":{"type":"object","properties":{"fiscal_year":{"type":"string"},"total_goals":{"type":"integer"},"retention_rate":{"type":"number"},"award":{"type":"string"},"membership_change":{"type":"integer"}}}},"goal_patterns":{"type":"object","properties":{"traditional":{"type":"object","properties":{"total_achieved":{"type":"integer"},"average_per_year":{"type":"number"}}},"pathways":{"type":"object","properties":{"total_achieved":{"type":"integer"},"average_per_year":{"type":"number"}}},"general":{"type":"object","properties":{"total_achieved":{"type":"integer"},"average_per_year":{"type":"number"}}}}},"award_history":{"type":"array","items":{"type":"object","properties":{"fiscal_year":{"type":"string"},"award":{"type":"string"},"total_goals":{"type":"integer"},"retention_rate":{"type":"number"}}}},"membership_stability":{"type":"object","properties":{"average_retention":{"type":"number"},"highest_retention":{"type":"number"},"lowest_retention":{"type":"number"},"average_membership":{"type":"number"},"membership_volatility":{"type":"number"}}},"years_analyzed":{"type":"integer"},"date_range":{"type":"object","properties":{"earliest":{"type":"string"},"latest":{"type":"string"}}}}},"historical_health_analysis":{"$ref":"#/components/schemas/ClubHistoricalHealthAnalysis","description":"Completed-programme-year historical health analysis. Unlike the dashboard, this endpoint returns 404 instead of a no_history DTO when no DCP-history rows exist."},"club_info":{"type":"object","properties":{"club_number":{"type":"string"},"club_name":{"type":"string"},"district":{"type":"string"},"area":{"type":"string"},"division":{"type":"string"}}}}}}}},"404":{"description":"Not found - No DCP history found for the specified club","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"clubNumber is missing or invalid","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/health":{"get":{"summary":"Health check","description":"Public readiness summary. Detailed diagnostics are available only to authorized operators. The health endpoints report failures in their own format, with a status string, not as problem details.","tags":["Health"],"responses":{"200":{"description":"Service healthy","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HealthStatus"}}}},"500":{"description":"The health check itself failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HealthStatus"}}}},"503":{"description":"Service unhealthy (e.g. database disconnected)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HealthStatus"}}}}}}},"/api/health/detailed":{"get":{"summary":"Detailed health check","description":"Detailed diagnostics with database, cache, memory, and disk checks. In production, send X-Health-Diagnostics-Token matching HEALTH_DIAGNOSTICS_TOKEN; omitted or invalid tokens intentionally receive 404. Authorization is not required outside production.","tags":["Health"],"security":[{"HealthDiagnosticsToken":[]}],"responses":{"200":{"description":"All checks healthy","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DetailedHealth"}}}},"404":{"description":"Not found when NODE_ENV is production and X-Health-Diagnostics-Token is missing or invalid","content":{"application/json":{"schema":{"type":"object","required":["status"],"properties":{"status":{"type":"string","enum":["not found"]}}}}}},"500":{"description":"The health check itself failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DetailedHealthFailure"}}}},"503":{"description":"One or more checks unhealthy","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DetailedHealth"}}}}}}},"/api/health/ready":{"get":{"summary":"Readiness probe","description":"Kubernetes/Docker readiness probe; returns 200 when database is connected","tags":["Health"],"responses":{"200":{"description":"Ready to accept traffic","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReadinessStatus"}}}},"503":{"description":"Not ready (e.g. database not connected)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReadinessStatus"}}}}}}},"/api/health/live":{"get":{"summary":"Liveness probe","description":"Kubernetes/Docker liveness probe; returns 200 if process is alive","tags":["Health"],"responses":{"200":{"description":"Process is alive","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LivenessStatus"}}}}}}},"/api/club/numbers":{"get":{"summary":"List club numbers","description":"Every club with a performance row in the current fiscal year, as canonical club numbers (no leading zeros), sorted. For building the dashboard's sitemap.","tags":["Club"],"responses":{"200":{"description":"Club numbers","content":{"application/json":{"schema":{"type":"object","required":["success","fiscal_year","data","total","timestamp"],"properties":{"success":{"type":"boolean"},"fiscal_year":{"type":"string","example":"2026-2027"},"data":{"type":"array","items":{"type":"string"},"example":["113","1150","28675613"]},"total":{"type":"integer"},"timestamp":{"type":"string","format":"date-time"}}}}}},"422":{"description":"A path or query parameter has an invalid value","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}},"500":{"description":"Internal server error"}}}},"/api/club/search":{"get":{"summary":"Search clubs by name","description":"Case-insensitive partial match on club name against the most recently imported monthly club snapshot of the current fiscal year. Results are ordered by club name.","tags":["Club"],"parameters":[{"name":"q","in":"query","required":true,"description":"Part of the club name (2-100 characters)","schema":{"type":"string","minLength":2,"maxLength":100}},{"name":"district","in":"query","description":"Only return clubs in this district","schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":50,"default":20}},{"$ref":"#/components/parameters/Offset"}],"responses":{"200":{"description":"Matching clubs","content":{"application/json":{"schema":{"type":"object","required":["success","data","pagination","filters","timestamp"],"properties":{"success":{"type":"boolean"},"data":{"type":"array","items":{"$ref":"#/components/schemas/ClubSearchResult"}},"pagination":{"$ref":"#/components/schemas/SnakeCaseTotalPagination"},"filters":{"type":"object"},"timestamp":{"type":"string","format":"date-time"}}}}}},"422":{"description":"Invalid search query","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}},"500":{"description":"Internal server error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/club/{clubNumber}/changelog":{"get":{"summary":"Get club changelog events","description":"Retrieve normalized, paginated metric changes for a club. Events are ordered by comparison date and metric.","tags":["Club"],"parameters":[{"name":"clubNumber","in":"path","required":true,"description":"Club number (e.g. 8-digit identifier)","schema":{"type":"string"}},{"name":"fiscalYear","in":"query","description":"Toastmasters fiscal year (July-June). Defaults to the current fiscal year.","schema":{"type":"string","pattern":"^\\d{4}-\\d{4}$"}},{"name":"fiscalMonth","in":"query","schema":{"type":"integer","minimum":1,"maximum":12}},{"name":"date","in":"query","schema":{"type":"string","format":"date"}},{"name":"startDate","in":"query","schema":{"type":"string","format":"date"}},{"name":"endDate","in":"query","schema":{"type":"string","format":"date"}},{"name":"category","in":"query","schema":{"type":"string","enum":["lifecycle","membership","education","status","renewals"]}},{"name":"metric","in":"query","schema":{"type":"string"}},{"$ref":"#/components/parameters/Limit"},{"$ref":"#/components/parameters/Offset"},{"name":"sortOrder","in":"query","schema":{"type":"string","enum":["asc","desc"],"default":"desc"}},{"name":"view","in":"query","description":"day: also return days, this page's events grouped by day with report glitches removed (a year-to-date count falling, or members falling outside the October/April removals) and memberRemoval on removal days.","schema":{"type":"string","enum":["day"]}}],"responses":{"200":{"description":"Paginated club changelog events","content":{"application/json":{"schema":{"type":"object","required":["success","club_number","data","pagination","filters","timestamp"],"properties":{"success":{"type":"boolean"},"club_number":{"type":"string"},"data":{"type":"array","items":{"$ref":"#/components/schemas/ClubChangelogEvent"}},"days":{"type":"array","description":"view=day only: the page's events without report glitches, grouped by day.","items":{"$ref":"#/components/schemas/ClubTimelineDay"}},"pagination":{"$ref":"#/components/schemas/SnakeCaseTotalPagination"},"filters":{"type":"object"},"timestamp":{"type":"string","format":"date-time"}}}}}},"422":{"description":"Invalid changelog query","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}},"500":{"description":"Internal server error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/club/{clubNumber}":{"get":{"summary":"Get club dashboard","description":"Retrieve dashboard data for a single club by club number. data.historical_health_analysis is always present and returns a deterministic no_history DTO when no eligible completed DCP-history rows exist. Its configuration-2.0 class reflects recent Distinguished outcomes independently of its diagnostic composite score.","tags":["Club"],"parameters":[{"name":"clubNumber","in":"path","required":true,"description":"Club number (e.g. 8-digit identifier)","schema":{"type":"string"}},{"$ref":"#/components/parameters/FiscalYear"},{"$ref":"#/components/parameters/StartDate"},{"$ref":"#/components/parameters/EndDate"},{"name":"includeHistory","in":"query","required":false,"description":"false leaves out the club's history of earlier snapshots","schema":{"type":"string","enum":["true","false"],"default":"true"}},{"$ref":"#/components/parameters/Latest"}],"responses":{"200":{"description":"Club dashboard data","content":{"application/json":{"schema":{"type":"object","required":["success","club_number","fiscal_year","fiscal_month","data","timestamp"],"properties":{"success":{"type":"boolean"},"club_number":{"type":"string"},"fiscal_year":{"type":"string","pattern":"^\\d{4}-\\d{4}$"},"fiscal_month":{"type":"integer","nullable":true,"minimum":1,"maximum":12,"description":"Fiscal month (1 = July) the figures are for: the requested month, else the month of the club's latest performance record. Early in a month this is still last month while Toastmasters processes it. Null when the club has no record for the fiscal year."},"data":{"$ref":"#/components/schemas/ClubDashboardResponse","description":"Dashboard payload, including historical_health_analysis for completed DCP history."},"timestamp":{"type":"string","format":"date-time"}}}}}},"422":{"description":"A path or query parameter has an invalid value","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}},"500":{"description":"Internal server error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/district/{district}/year-comparison":{"get":{"summary":"Compare a district's fiscal month with the same month last year","description":"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.","tags":["District"],"parameters":[{"name":"district","in":"path","required":true,"schema":{"type":"string"},"description":"District number/code."},{"name":"fiscalYear","in":"query","required":false,"schema":{"type":"string","pattern":"^\\d{4}-\\d{4}$"},"description":"Fiscal year to compare. Defaults to the district's latest reported fiscal year."},{"name":"fiscalMonth","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":12},"description":"Fiscal month (1 = July) to compare. Defaults to the latest reported month in the fiscal year."}],"responses":{"200":{"description":"The fiscal month against the same month last year.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DistrictYearComparisonResponse"}}}},"404":{"description":"No clubs reported for the district in that month.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Invalid district, fiscalYear, fiscalMonth, or an unsupported query parameter.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}},"500":{"description":"Internal server error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/district/{district}/clubs/historical-health":{"get":{"summary":"Get ranked district club historical health","description":"Returns one complete, single district club-roster snapshot, ordered by finite historical-health score descending. Equal scores are ordered by canonical club number ascending and receive unique 1-based ordinal ranks; null scores are last and unranked. fiscalYear and fiscalMonth select only the current roster snapshot and never filter, cap, or otherwise alter the completed history selected by each reusable analysis. A known district snapshot with no clubs returns 200 and an empty clubs list. Only fiscalYear and fiscalMonth are supported query parameters; latest and unknown query parameters are rejected.","tags":["District"],"parameters":[{"name":"district","in":"path","required":true,"schema":{"type":"string"},"description":"District number/code."},{"name":"fiscalYear","in":"query","required":false,"schema":{"type":"string","pattern":"^\\d{4}-\\d{4}$"},"description":"Roster snapshot fiscal year. Defaults using the district fiscal-year selection rules."},{"name":"fiscalMonth","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":12},"description":"Roster snapshot fiscal month. When omitted, the latest eligible month in the resolved fiscal year is selected."}],"responses":{"200":{"description":"A ranked complete roster from one resolved snapshot, or an empty club list when that snapshot has no clubs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DistrictClubHistoricalHealthResponse"}}}},"404":{"description":"No district snapshot exists for the resolved fiscal year and month.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Invalid district, fiscalYear, fiscalMonth, or unsupported query parameter such as latest.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}},"500":{"description":"Internal server error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/district/{district}/division/{division}":{"get":{"summary":"Get division data","description":"Retrieve division-level data. Area average_goals_met is the arithmetic club mean; area and division educational_ratio values are total awards divided by total mem_base. Division average_goals_met is club-weighted. Undefined ratios and empty averages are null.","tags":["Division"],"parameters":[{"name":"district","in":"path","required":true,"schema":{"type":"string"},"description":"District number/code"},{"name":"division","in":"path","required":true,"schema":{"type":"string"},"description":"Division identifier"},{"$ref":"#/components/parameters/FiscalYear"},{"name":"include","in":"query","required":false,"description":"Comma-separated extra blocks to include","schema":{"type":"string","pattern":"^(all|areas|divisionGoals|areaGoals)(,(all|areas|divisionGoals|areaGoals))*$"},"example":"areas,divisionGoals"},{"$ref":"#/components/parameters/Latest"}],"responses":{"200":{"description":"Division data","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"metadata":{"type":"object","description":"Payment targets are optional enrichment. partial_data is true when they are unavailable.","properties":{"partial_data":{"type":"boolean"},"partial_data_reasons":{"type":"array","items":{"type":"string"}},"payment_targets":{"type":"object","properties":{"available":{"type":"boolean"},"reason":{"type":"string"}}}}},"data":{"type":"object","properties":{"insights":{"$ref":"#/components/schemas/DivisionInsights"},"month_change":{"description":"The division's totals against the fiscal month before, with each area's change in parts; null when no clubs were reported for the month.","anyOf":[{"$ref":"#/components/schemas/MonthChange"},{"type":"object","nullable":true,"enum":[null]}]},"district":{"type":"string"},"division":{"type":"string","description":"Division identifier retained for compatibility."},"average_goals_met":{"type":"number","nullable":true},"educational_ratio":{"type":"number","nullable":true},"division_context":{"type":"object","description":"Division identifiers and division-wide metric benchmarks.","additionalProperties":true},"district_context":{"type":"object","description":"Actual district-wide benchmarks for the same fiscal scope.","additionalProperties":true},"areas":{"type":"array","items":{"type":"object","properties":{"average_goals_met":{"type":"number","nullable":true},"educational_ratio":{"type":"number","nullable":true},"clubs":{"type":"array","items":{"type":"object","properties":{"club_number":{"type":"string"},"club_name":{"type":"string"},"club_outlook":{"allOf":[{"$ref":"#/components/schemas/ClubOutlook"}],"description":"Area responses only: the club's outlook, as on the club dashboard."},"educational_awards":{"type":"number","description":"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":{"type":"number","nullable":true,"description":"Educational awards divided by mem_base; null when mem_base is zero."},"average_goals_met":{"type":"number","nullable":true,"description":"Compatibility field on division responses containing this club's own goals_met value."},"nov_visit_award":{"type":"number","nullable":true,"description":"1 when the club's first-round (July–November) area director visit is recorded, otherwise 0."},"may_visit_award":{"type":"number","nullable":true,"description":"1 when the club's second-round (December–May) area director visit is recorded, otherwise 0."},"area_average_goals_met":{"type":"number","nullable":true,"description":"Arithmetic mean of goals_met across clubs in the selected area."},"area_average_educational_ratio":{"type":"number","nullable":true,"description":"Arithmetic mean of defined club educational ratios in the selected area."},"goals_vs_area_average":{"type":"string","nullable":true,"enum":["above","below","at"]},"educational_ratio_vs_area_average":{"type":"string","nullable":true,"enum":["above","below","at"]},"july_officer_list":{"type":"array","description":"July officer list entries for the club in the selected fiscal year","items":{"type":"object","properties":{"list_status":{"type":"string","nullable":true},"election_type":{"type":"string","nullable":true},"date":{"type":"string","format":"date","nullable":true}},"additionalProperties":true}},"july_officer_list_status":{"type":"boolean","description":"True when latest July officer list status indicates Received, else false"}},"additionalProperties":true}}},"additionalProperties":true}}},"additionalProperties":true}},"additionalProperties":true}}}},"422":{"description":"A path or query parameter has an invalid value","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}},"500":{"description":"Internal server error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/district/{district}/division/{division}/changelog":{"get":{"summary":"Get aggregated division changelog","description":"Groups normalized club changelog events by metric across every area in the selected division and 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.","tags":["Division"],"parameters":[{"name":"district","in":"path","required":true,"schema":{"type":"string"}},{"name":"division","in":"path","required":true,"schema":{"type":"string"}},{"name":"fiscalYear","in":"query","description":"Toastmasters fiscal year. Defaults to the current fiscal year.","schema":{"type":"string","pattern":"^\\d{4}-\\d{4}$"}},{"name":"fiscalMonth","in":"query","schema":{"type":"integer","minimum":1,"maximum":12}},{"name":"date","in":"query","schema":{"type":"string","format":"date"}},{"name":"startDate","in":"query","schema":{"type":"string","format":"date"}},{"name":"endDate","in":"query","schema":{"type":"string","format":"date"}},{"name":"category","in":"query","schema":{"type":"string","enum":["lifecycle","membership","education","status","renewals"]}},{"name":"metric","in":"query","schema":{"type":"string"}},{"$ref":"#/components/parameters/Limit"},{"$ref":"#/components/parameters/Offset"},{"name":"sortOrder","in":"query","schema":{"type":"string","enum":["asc","desc"],"default":"desc"}},{"name":"view","in":"query","description":"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.","schema":{"type":"string","enum":["day"]}}],"responses":{"200":{"description":"Paginated metric aggregates for the selected division and period","content":{"application/json":{"schema":{"type":"object","required":["success","division","data","pagination","filters","timestamp"],"properties":{"success":{"type":"boolean"},"division":{"type":"object","required":["district","division"],"properties":{"district":{"type":"string"},"division":{"type":"string"}}},"data":{"type":"array","items":{"$ref":"#/components/schemas/AreaChangelogMetricAggregate"}},"pagination":{"$ref":"#/components/schemas/SnakeCaseTotalPagination"},"filters":{"type":"object"},"timestamp":{"type":"string","format":"date-time"}}}}}},"422":{"description":"Invalid division changelog query","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}},"500":{"description":"Internal server error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/district/{district}/area/{division}/{area}/changelog":{"get":{"summary":"Get aggregated area changelog","description":"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.","tags":["Area"],"parameters":[{"name":"district","in":"path","required":true,"schema":{"type":"string"}},{"name":"division","in":"path","required":true,"schema":{"type":"string"}},{"name":"area","in":"path","required":true,"schema":{"type":"string"}},{"name":"fiscalYear","in":"query","description":"Toastmasters fiscal year. Defaults to the current fiscal year.","schema":{"type":"string","pattern":"^\\d{4}-\\d{4}$"}},{"name":"fiscalMonth","in":"query","schema":{"type":"integer","minimum":1,"maximum":12}},{"name":"date","in":"query","schema":{"type":"string","format":"date"}},{"name":"startDate","in":"query","schema":{"type":"string","format":"date"}},{"name":"endDate","in":"query","schema":{"type":"string","format":"date"}},{"name":"category","in":"query","schema":{"type":"string","enum":["lifecycle","membership","education","status","renewals"]}},{"name":"metric","in":"query","schema":{"type":"string"}},{"$ref":"#/components/parameters/Limit"},{"$ref":"#/components/parameters/Offset"},{"name":"sortOrder","in":"query","schema":{"type":"string","enum":["asc","desc"],"default":"desc"}},{"name":"view","in":"query","description":"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.","schema":{"type":"string","enum":["day"]}}],"responses":{"200":{"description":"Paginated metric aggregates for the selected area and period","content":{"application/json":{"schema":{"type":"object","required":["success","area","data","pagination","filters","timestamp"],"properties":{"success":{"type":"boolean"},"area":{"type":"object","required":["district","division","area"],"properties":{"district":{"type":"string"},"division":{"type":"string"},"area":{"type":"string"}}},"data":{"type":"array","items":{"$ref":"#/components/schemas/AreaChangelogMetricAggregate"}},"pagination":{"$ref":"#/components/schemas/SnakeCaseTotalPagination"},"filters":{"type":"object"},"timestamp":{"type":"string","format":"date-time"}}}}}},"422":{"description":"Invalid area changelog query","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}},"500":{"description":"Internal server error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/district/{district}/area/{division}/{area}":{"get":{"summary":"Get area data","description":"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.","tags":["Area"],"parameters":[{"name":"district","in":"path","required":true,"schema":{"type":"string"}},{"name":"division","in":"path","required":true,"schema":{"type":"string"}},{"name":"area","in":"path","required":true,"schema":{"type":"string"}},{"$ref":"#/components/parameters/FiscalYear"},{"$ref":"#/components/parameters/Date"},{"$ref":"#/components/parameters/StartDate"},{"$ref":"#/components/parameters/EndDate"},{"$ref":"#/components/parameters/Latest"},{"$ref":"#/components/parameters/Limit"},{"$ref":"#/components/parameters/Offset"}],"responses":{"200":{"description":"Area data","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"area":{"type":"object","properties":{"area_average_goals_met":{"type":"number","nullable":true},"area_educational_ratio":{"type":"number","nullable":true}},"additionalProperties":true},"division_metrics":{"type":"object","description":"Compatibility object containing area-level benchmarks; these are not division-wide metrics.","properties":{"area_average_goals_met":{"type":"number","nullable":true},"area_educational_ratio":{"type":"number","nullable":true}}},"clubs":{"type":"array","items":{"type":"object","properties":{"club_number":{"type":"string"},"club_name":{"type":"string"},"club_outlook":{"allOf":[{"$ref":"#/components/schemas/ClubOutlook"}],"description":"Area responses only: the club's outlook, as on the club dashboard."},"educational_awards":{"type":"number","description":"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":{"type":"number","nullable":true,"description":"Educational awards divided by mem_base; null when mem_base is zero."},"average_goals_met":{"type":"number","nullable":true,"description":"Compatibility field on division responses containing this club's own goals_met value."},"nov_visit_award":{"type":"number","nullable":true,"description":"1 when the club's first-round (July–November) area director visit is recorded, otherwise 0."},"may_visit_award":{"type":"number","nullable":true,"description":"1 when the club's second-round (December–May) area director visit is recorded, otherwise 0."},"area_average_goals_met":{"type":"number","nullable":true,"description":"Arithmetic mean of goals_met across clubs in the selected area."},"area_average_educational_ratio":{"type":"number","nullable":true,"description":"Arithmetic mean of defined club educational ratios in the selected area."},"goals_vs_area_average":{"type":"string","nullable":true,"enum":["above","below","at"]},"educational_ratio_vs_area_average":{"type":"string","nullable":true,"enum":["above","below","at"]},"july_officer_list":{"type":"array","description":"July officer list entries for the club in the selected fiscal year","items":{"type":"object","properties":{"list_status":{"type":"string","nullable":true},"election_type":{"type":"string","nullable":true},"date":{"type":"string","format":"date","nullable":true}},"additionalProperties":true}},"july_officer_list_status":{"type":"boolean","description":"True when latest July officer list status indicates Received, else false"}},"additionalProperties":true}},"insights":{"$ref":"#/components/schemas/AreaInsights"},"month_change":{"description":"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.","anyOf":[{"$ref":"#/components/schemas/MonthChange"},{"type":"object","nullable":true,"enum":[null]}]}},"additionalProperties":true}},"additionalProperties":true}}}},"422":{"description":"A path or query parameter has an invalid value","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}},"500":{"description":"Internal server error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/district/{district}":{"get":{"summary":"Get the district dashboard","description":"The district's summary totals and recognition goals, its divisions with their areas and clubs, its monthly history, prospective clubs and insights, for the latest fiscal month of the fiscal year or the one requested. Division, area and district educational_ratio values are total awards divided by total member base; average_goals_met is the mean over clubs.","tags":["District"],"parameters":[{"name":"district","in":"path","required":true,"schema":{"type":"string"},"description":"District number/code"},{"name":"fiscalYear","in":"query","required":false,"schema":{"type":"string","pattern":"^[0-9]{4}-[0-9]{4}$"},"description":"Fiscal year (YYYY-YYYY); defaults to the latest fiscal year with dashboard data"},{"name":"fiscalMonth","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":12},"description":"Fiscal month (1 = July); defaults to the latest month with data"},{"name":"latest","in":"query","required":false,"schema":{"type":"boolean","default":true},"description":"Use each record's latest snapshot"}],"responses":{"200":{"description":"District dashboard","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DistrictDashboardResponse"}}}},"404":{"description":"No data for the district in the fiscal year","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Invalid fiscal year or fiscal month","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/region/{region}":{"get":{"summary":"Get region data","description":"Retrieve data for a region by region identifier","tags":["Region"],"parameters":[{"name":"region","in":"path","required":true,"schema":{"type":"string"},"description":"Region identifier"},{"$ref":"#/components/parameters/FiscalYear"},{"name":"fiscalMonth","in":"query","required":false,"description":"Fiscal month (1 = July); defaults to each district's latest month","schema":{"type":"integer","minimum":1,"maximum":12}},{"name":"latest","in":"query","required":false,"description":"false returns every monthly row instead of each district's latest month. true also skips the cached response.","schema":{"type":"string","enum":["true","false"],"default":"true"}}],"responses":{"200":{"description":"Region data","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"districts":{"type":"array","items":{"type":"object","properties":{"average_members_per_club":{"type":"number","description":"Average normalized active membership across all club rows in the district snapshot"},"average_new_members_per_club":{"type":"number","description":"Average normalized new_members plus add_new_members across all club rows in the district snapshot"},"potential_distinguished_clubs":{"type":"integer","minimum":0,"description":"Non-suspended clubs in the district snapshot with 20+ active members whose goals_met meets the monthly DCP target for the snapshot's fiscal month (Jul–Sep 1, Oct–Nov 2, Dec–Jan 3, Feb–Mar 4, Apr–Jun 5). Includes clubs that are already Distinguished."}},"additionalProperties":true}}}}}}}}},"422":{"description":"A path or query parameter has an invalid value","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}},"500":{"description":"Internal server error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/dropdown/dashboard-filters":{"get":{"summary":"Get dashboard filters","description":"Filter options for dashboard (districts, fiscal years, dates, etc.). Successful reads are shared-cacheable for approximately 60 seconds. Cache keys include the complete request URL and query string, and responses vary by Origin. Requests with latest=true and error responses use Cache-Control: no-store.","tags":["Dropdown"],"parameters":[{"name":"fiscalYear","in":"query","required":false,"description":"Fiscal year (YYYY-YYYY) whose months to list; defaults to the current fiscal year","schema":{"type":"string","pattern":"^[0-9]{4}-[0-9]{4}$"}},{"name":"fiscalMonth","in":"query","required":false,"description":"Fiscal month (1 = July). With fiscalYear, adds that month's report dates. Takes precedence over month.","schema":{"type":"integer","minimum":1,"maximum":12}},{"name":"month","in":"query","required":false,"description":"Calendar month (1 = January), as an alternative to fiscalMonth","schema":{"type":"integer","minimum":1,"maximum":12}}],"responses":{"200":{"description":"Dashboard filter options","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DashboardFiltersResponse"}}}},"422":{"description":"fiscalMonth is not between 1 and 12","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/dropdown/regions/table":{"get":{"summary":"Get regions table","description":"Regions derived from the districts table for dropdown/table display. Successful reads are shared-cacheable for approximately 60 seconds. Cache keys include the complete request URL and query string, and responses vary by Origin. Requests with latest=true and error responses use Cache-Control: no-store.","tags":["Dropdown"],"responses":{"200":{"description":"Regions of the current fiscal year","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DropdownRegionsResponse"}}}},"422":{"description":"A path or query parameter has an invalid value","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}},"500":{"description":"Internal server error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/dropdown/districts/table":{"get":{"summary":"Get districts table","description":"Districts from the districts table for dropdown/table display. Successful reads are shared-cacheable for approximately 60 seconds. Cache keys include the complete request URL and query string, and responses vary by Origin. Requests with latest=true and error responses use Cache-Control: no-store.","tags":["Dropdown"],"responses":{"200":{"description":"Districts of the current fiscal year","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DropdownDistrictsResponse"}}}},"422":{"description":"A path or query parameter has an invalid value","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}},"500":{"description":"Internal server error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/dropdown/divisions/table":{"get":{"summary":"Get divisions table","description":"Divisions from the divisions table for dropdown/table display. Successful reads are shared-cacheable for approximately 60 seconds. Cache keys include the complete request URL and query string, and responses vary by Origin. Requests with latest=true and error responses use Cache-Control: no-store.","tags":["Dropdown"],"parameters":[{"name":"district","in":"query","required":false,"description":"Only options in this district","schema":{"type":"string"}}],"responses":{"200":{"description":"Divisions of the current fiscal year","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DropdownDivisionsResponse"}}}},"422":{"description":"A path or query parameter has an invalid value","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}},"500":{"description":"Internal server error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/dropdown/areas/table":{"get":{"summary":"Get areas table","description":"Areas from the areas table for dropdown/table display. Successful reads are shared-cacheable for approximately 60 seconds. Cache keys include the complete request URL and query string, and responses vary by Origin. Requests with latest=true and error responses use Cache-Control: no-store.","tags":["Dropdown"],"parameters":[{"name":"district","in":"query","required":false,"description":"Only options in this district","schema":{"type":"string"}},{"name":"division","in":"query","required":false,"description":"Only areas in this division","schema":{"type":"string"}}],"responses":{"200":{"description":"Areas of the current fiscal year","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DropdownAreasResponse"}}}},"422":{"description":"A path or query parameter has an invalid value","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}},"500":{"description":"Internal server error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/global":{"get":{"summary":"Get the global district summary","description":"Every district's payments, recognition counts and goals, each region's totals, and the global totals and educational awards for the fiscal year. Complete responses are cached for 5 minutes per fiscalYear/fiscalMonth/latest combination; metadata.cached is true when a response is served from the cache.","tags":["Global"],"parameters":[{"name":"fiscalYear","in":"query","required":false,"schema":{"type":"string","pattern":"^[0-9]{4}-[0-9]{4}$"},"description":"Fiscal year (YYYY-YYYY); defaults to the current fiscal year"},{"name":"fiscalMonth","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":12},"description":"Fiscal month (1 = July); defaults to each district's latest month"},{"name":"latest","in":"query","required":false,"schema":{"type":"boolean","default":true},"description":"Use each district's latest snapshot for the division goals"}],"responses":{"200":{"description":"Global district summary","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GlobalSummaryResponse"}}}},"422":{"description":"Invalid fiscal year or fiscal month","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/tools/hypothetical-area":{"post":{"summary":"Evaluate a hypothetical area","description":"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.","tags":["Tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HypotheticalAreaRequest"}}}},"responses":{"200":{"description":"Evaluate a hypothetical area","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"$ref":"#/components/schemas/HypotheticalArea"},"timestamp":{"type":"string","format":"date-time"}}}}}},"400":{"description":"The request body is not valid JSON","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The body was read but a value in it is invalid","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}},"500":{"description":"Internal server error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/tools/hypothetical-division":{"post":{"summary":"Evaluate a hypothetical division","description":"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.","tags":["Tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HypotheticalDivisionRequest"}}}},"responses":{"200":{"description":"Evaluate a hypothetical division","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"$ref":"#/components/schemas/HypotheticalDivision"},"timestamp":{"type":"string","format":"date-time"}}}}}},"400":{"description":"The request body is not valid JSON","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The body was read but a value in it is invalid","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}},"500":{"description":"Internal server error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/":{"get":{"summary":"Get API route index","description":"Lists the public API route groups and documentation location.","tags":["API"],"responses":{"200":{"description":"Public API route index"}}}}},"components":{"schemas":{"Error":{"type":"object","description":"An error, as RFC 9457 problem details (application/problem+json). success, error, message and timestamp are extension members, kept from the error format that came before. Some errors add extension members of their own.","required":["type","title","status","instance","success","error","message","timestamp"],"properties":{"type":{"type":"string","enum":["about:blank"],"description":"URI of the problem type. Always about:blank: problems have no type of their own, and title is the HTTP status phrase."},"title":{"type":"string","description":"The HTTP status phrase","example":"Not Found"},"status":{"type":"integer","minimum":400,"maximum":599,"description":"The HTTP status code","example":404},"detail":{"type":"string","description":"What went wrong with this request. The same text as message."},"instance":{"type":"string","description":"The path and query of the request that failed","example":"/api/district/999"},"success":{"type":"boolean","enum":[false]},"error":{"type":"string","description":"A short name for the problem","example":"Not Found"},"message":{"type":"string","description":"What went wrong with this request"},"timestamp":{"type":"string","format":"date-time"}},"additionalProperties":true},"ValidationError":{"type":"object","description":"A request that was read but holds an invalid value (422), as RFC 9457 problem details (application/problem+json). details lists each problem found.","required":["type","title","status","instance","success","error","message","timestamp","detail","details"],"properties":{"type":{"type":"string","enum":["about:blank"],"description":"URI of the problem type. Always about:blank: problems have no type of their own, and title is the HTTP status phrase."},"title":{"type":"string","enum":["Unprocessable Entity"]},"status":{"type":"integer","enum":[422]},"detail":{"type":"string","description":"What went wrong with this request. The same text as message."},"instance":{"type":"string","description":"The path and query of the request that failed","example":"/api/district/999"},"success":{"type":"boolean","enum":[false]},"error":{"type":"string","enum":["Validation failed"]},"message":{"type":"string","enum":["Invalid request parameters"]},"timestamp":{"type":"string","format":"date-time"},"details":{"type":"array","items":{"type":"object","required":["location","path","message","code"],"properties":{"location":{"type":"string","enum":["query","params","body"]},"path":{"type":"string"},"message":{"type":"string"},"code":{"type":"string"}}}}}},"RecordCountPagination":{"type":"object","description":"Pagination retained by specialized report endpoints. total_records is the total matching records.","required":["total_records","limit","offset"],"properties":{"total_records":{"type":"integer","minimum":0,"description":"Total matching records"},"limit":{"type":"integer","description":"Number of records per page"},"offset":{"type":"integer","description":"Number of records to skip"}}},"SnakeCaseTotalPagination":{"type":"object","description":"Pagination returned by member-payments endpoints. total is the total matching records.","required":["total","limit","offset","has_more"],"properties":{"total":{"type":"integer","minimum":0,"description":"Total matching records"},"limit":{"type":"integer","description":"Number of records per page"},"offset":{"type":"integer","description":"Number of records to skip"},"has_more":{"type":"boolean","description":"Whether there are more records available"}}},"ClubSearchResult":{"type":"object","required":["club_number","club_name","district","division","area","club_status"],"properties":{"club_number":{"type":"string","description":"Club number without leading zeros"},"club_name":{"type":"string","nullable":true},"district":{"type":"string","nullable":true},"division":{"type":"string","nullable":true},"area":{"type":"string","nullable":true},"club_status":{"type":"string","nullable":true}}},"ClubChangelogEvent":{"type":"object","required":["club_number","club_name","district","division","area","comparison_date","previous_date","fiscal_year","fiscal_month","category","metric","change_type","old_value","new_value","old_value_numeric","new_value_numeric","delta_numeric"],"properties":{"club_number":{"type":"string"},"club_name":{"type":"string","nullable":true},"district":{"type":"string","nullable":true},"division":{"type":"string","nullable":true},"area":{"type":"string","nullable":true},"comparison_date":{"type":"string","format":"date"},"previous_date":{"type":"string","format":"date"},"fiscal_year":{"type":"string","pattern":"^\\d{4}-\\d{4}$"},"fiscal_month":{"type":"integer","minimum":1,"maximum":12},"category":{"type":"string","enum":["lifecycle","membership","education","status","renewals"]},"metric":{"type":"string"},"change_type":{"type":"string","enum":["increased","decreased","changed","club_added","club_removed"]},"old_value":{"type":"string","nullable":true},"new_value":{"type":"string","nullable":true},"old_value_numeric":{"type":"number","nullable":true},"new_value_numeric":{"type":"number","nullable":true},"delta_numeric":{"type":"number","nullable":true}}},"AreaChangelogChange":{"type":"object","required":["comparison_date","previous_date","change_type","old_value","new_value","old_value_numeric","new_value_numeric","delta_numeric"],"properties":{"comparison_date":{"type":"string","format":"date"},"previous_date":{"type":"string","format":"date"},"change_type":{"type":"string","enum":["increased","decreased","changed","club_added","club_removed"]},"old_value":{"type":"string","nullable":true},"new_value":{"type":"string","nullable":true},"old_value_numeric":{"type":"number","nullable":true},"new_value_numeric":{"type":"number","nullable":true},"delta_numeric":{"type":"number","nullable":true}}},"AreaChangelogClubAggregate":{"type":"object","required":["club_number","club_name","division","area","event_count","total_delta","first_comparison_date","last_comparison_date","changes"],"properties":{"club_number":{"type":"string"},"club_name":{"type":"string","nullable":true},"division":{"type":"string","nullable":true},"area":{"type":"string","nullable":true},"event_count":{"type":"integer","minimum":1},"total_delta":{"type":"number","nullable":true,"description":"Sum of numeric event deltas for this club; null for non-numeric metrics such as lifecycle events."},"first_comparison_date":{"type":"string","format":"date"},"last_comparison_date":{"type":"string","format":"date"},"changes":{"type":"array","items":{"$ref":"#/components/schemas/AreaChangelogChange"}}}},"AreaChangelogMetricAggregate":{"type":"object","required":["category","metric","event_count","clubs_affected","total_delta","first_comparison_date","last_comparison_date","clubs"],"properties":{"category":{"type":"string","enum":["lifecycle","membership","education","status","renewals"]},"metric":{"type":"string"},"event_count":{"type":"integer","minimum":1},"clubs_affected":{"type":"integer","minimum":1},"total_delta":{"type":"number","nullable":true,"description":"Sum of numeric deltas across the selected area and period; null when the metric is non-numeric."},"first_comparison_date":{"type":"string","format":"date"},"last_comparison_date":{"type":"string","format":"date"},"clubs":{"type":"array","items":{"$ref":"#/components/schemas/AreaChangelogClubAggregate"}},"member_removal":{"description":"view=day only: members removed for unpaid dues, when this is an October or April active-member drop; otherwise null.","type":"object","nullable":true,"required":["period","removed","clubs"],"properties":{"period":{"type":"string","enum":["October","April"]},"removed":{"type":"integer","description":"Members removed (the drop in active members)."},"clubs":{"type":"integer","description":"Clubs whose active members fell."}}}}},"ClubTimelineDay":{"type":"object","required":["date","events","memberRemoval"],"properties":{"date":{"type":"string","format":"date"},"events":{"type":"array","minItems":1,"items":{"$ref":"#/components/schemas/ClubChangelogEvent"}},"memberRemoval":{"type":"object","nullable":true,"description":"Set when active members fell during an October or April removal of unpaid members.","required":["period","removed","from","to"],"properties":{"period":{"type":"string","enum":["October","April"]},"removed":{"type":"integer"},"from":{"type":"integer"},"to":{"type":"integer"}}}}},"HistoricalHealthComponent":{"type":"object","description":"Explainable weighted composite-score component. The composite is diagnostic context and does not determine historical_class. Missing components have null score, zero effective weight, and status `missing`.","required":["key","configured_weight","effective_weight","score","contribution","observations","status","formula","evidence"],"properties":{"key":{"type":"string","enum":["membership_sustainability","growth","dcp_goals","distinguished_status","officer_training"]},"configured_weight":{"type":"number","description":"Configured percentage weight."},"effective_weight":{"type":"number","description":"Percentage weight after redistribution across observed components."},"score":{"type":"number","nullable":true,"description":"Component score from 0 through 100; null when no usable observations exist."},"contribution":{"type":"number","description":"Weighted contribution to the historical score, or zero when missing."},"observations":{"type":"integer","minimum":0},"status":{"type":"string","enum":["scored","missing"]},"formula":{"type":"string"},"evidence":{"type":"object","description":"Component-specific primitive evidence used by the diagnostic-score calculation, such as the configured sustainability threshold and safe membership declines neutralized for growth scoring. Each value is a number, string, boolean, or null. Recent-award classification and benchmark-adjusted trajectory evidence are separate top-level explainability fields.","additionalProperties":true}}},"HistoricalAwardClassificationEvidence":{"type":"object","description":"Top-level explainability evidence for the independent recent-award historical_class calculation; it is not diagnostic-score component evidence.","required":["classification_window_fiscal_years","window_size","required_frequency","known_years","high_distinguished_years","distinguished_years","selected_class_rule"],"properties":{"classification_window_fiscal_years":{"type":"array","maxItems":3,"description":"Fiscal years in the most recent up-to-three completed-programme-year classification window, ordered oldest to newest.","items":{"type":"string","pattern":"^\\d{4}-\\d{4}$"}},"window_size":{"type":"integer","minimum":0,"maximum":3,"description":"Number of completed programme years in the classification window."},"required_frequency":{"type":"integer","minimum":0,"maximum":2,"description":"Recognized award values required to classify the window: ceil(window_size * 2 / 3)."},"known_years":{"type":"integer","minimum":0,"maximum":3,"description":"Years in the classification window with recognized award semantics, including explicit no-award values."},"high_distinguished_years":{"type":"integer","minimum":0,"maximum":3,"description":"Recognized President's Distinguished or Smedley Distinguished years in the classification window."},"distinguished_years":{"type":"integer","minimum":0,"maximum":3,"description":"Recognized Distinguished-or-better years in the classification window."},"selected_class_rule":{"type":"string","nullable":true,"description":"Rule that selected the A-D historical class; null when recognized award evidence is insufficient."}}},"HistoricalBenchmarkAdjustedTrajectoryEvidence":{"type":"object","description":"Top-level explainability evidence for membership-risk trajectory classification after memberships are capped at the healthy-membership threshold; it is not diagnostic-score component evidence.","required":["healthy_membership_threshold","benchmark_adjusted_membership_series","benchmark_adjusted_change_percent_per_year","benchmark_adjusted_membership_volatility","above_threshold_movements_neutralized"],"properties":{"healthy_membership_threshold":{"type":"number","description":"Configured healthy-membership threshold used to cap memberships for trajectory classification."},"benchmark_adjusted_membership_series":{"type":"array","maxItems":5,"description":"Observed completed-year memberships after capping each value at healthy_membership_threshold, ordered oldest to newest.","items":{"type":"object","required":["fiscal_year","membership"],"properties":{"fiscal_year":{"type":"string","pattern":"^\\d{4}-\\d{4}$","description":"Completed programme year for this trajectory observation."},"membership":{"type":"number","description":"Year-end membership capped at healthy_membership_threshold for trajectory classification."}}}},"benchmark_adjusted_change_percent_per_year":{"type":"number","nullable":true,"description":"Average gap-aware annualized change percentage calculated from the benchmark-adjusted membership series; null when no valid transition exists."},"benchmark_adjusted_membership_volatility":{"type":"number","nullable":true,"description":"Coefficient of variation of the benchmark-adjusted membership series; null when it cannot be calculated."},"above_threshold_movements_neutralized":{"type":"integer","minimum":0,"description":"Count of adjacent observed movements whose actual endpoints both met the healthy-membership threshold and therefore become neutral after capping."}}},"ClubHistoricalHealthYear":{"type":"object","description":"One completed eligible programme year, ordered oldest to newest.","required":["fiscal_year","year_end_membership","membership_change","membership_change_percent","at_or_above_20","at_or_above_healthy_membership","dcp_goals","distinguished_status","officer_training_round_1","officer_training_round_2","score"],"properties":{"fiscal_year":{"type":"string","pattern":"^\\d{4}-\\d{4}$"},"year_end_membership":{"type":"number","nullable":true,"description":"Actual reported year-end membership; this value is never capped."},"membership_change":{"type":"number","nullable":true,"description":"Actual year-end minus membership base; this raw value is never benchmark-adjusted."},"membership_change_percent":{"type":"number","nullable":true,"description":"Actual raw membership change percentage; this value is never benchmark-adjusted."},"at_or_above_20":{"type":"boolean","nullable":true,"deprecated":true,"description":"Legacy compatibility flag for the former 20-member threshold. Use at_or_above_healthy_membership for the configured sustainability threshold."},"at_or_above_healthy_membership":{"type":"boolean","nullable":true,"description":"Sustainability flag: whether actual year-end membership meets the configured healthy-membership threshold (25 by default in configuration 2.0)."},"dcp_goals":{"type":"number","nullable":true},"distinguished_status":{"type":"string","nullable":true},"officer_training_round_1":{"type":"number","nullable":true},"officer_training_round_2":{"type":"number","nullable":true},"score":{"type":"number","nullable":true,"description":"Per-year score when at least three scored components including membership sustainability are available."}}},"ClubOutlook":{"type":"object","description":"Which of five groups the club is in: doing_well, improving, steady, declining or definite_worry. From October the current paid count decides first: under 8 paid members is definite_worry, and keeping under 60% of last June's members is declining. Otherwise the 0-100 health score for the last completed programme year decides: 70+ is doing_well; a score up 10+ on the two years before, or more paid members than last June, is improving; anything else is steady. Before October, a score under 40 is definite_worry. Back-tested on October 2024 and 2025: closed or under 8 members by the next June was 1% for doing_well, 8% improving, 8% steady, 6% declining (median -6 members) and 55% definite_worry.","required":["version","category","label","basis","health_score","health_score_change","scored_year","paid_members","last_year_end_members","retention","reasons","points"],"properties":{"version":{"type":"string","enum":["1"]},"category":{"type":"string","nullable":true,"enum":["doing_well","improving","steady","declining","definite_worry",null],"description":"Null when the club has no completed year and isn't under 8 paid members after October."},"label":{"type":"string","nullable":true,"example":"Definite worry"},"basis":{"type":"string","enum":["renewals","history"],"description":"renewals once October renewals are in; history before that."},"health_score":{"type":"number","nullable":true,"minimum":0,"maximum":100,"description":"100 minus points for the last completed programme year."},"health_score_change":{"type":"number","nullable":true,"description":"Health score minus the average of the two programme years before it."},"scored_year":{"type":"string","nullable":true,"example":"2025-2026"},"paid_members":{"type":"number","nullable":true},"last_year_end_members":{"type":"number","nullable":true},"retention":{"type":"number","nullable":true,"description":"Paid members now as a share of last year end's, from October."},"reasons":{"type":"array","items":{"type":"string"},"description":"Why the club is in its group, most important first."},"points":{"type":"array","description":"Points taken off 100 for the scored year, largest first.","items":{"type":"object","required":["key","points","reason"],"properties":{"key":{"type":"string","enum":["members","dcp_goals","new_members","officer_training","renewals","members_lost","distinguished"]},"points":{"type":"number"},"reason":{"type":"string"}}}}}},"ClubHistoricalHealthAnalysis":{"type":"object","description":"Reusable completed-programme-year health analysis. It excludes the current and future fiscal years, considers at most five eligible years, and never changes the current club_health_score. The weighted score, recent Distinguished-history class, and membership-risk trajectory answer separate questions.","required":["schema_version","config_version","status","score","historical_class","trajectory","profile","years_analyzed","period","trend","yearly","explainability","data_quality"],"properties":{"schema_version":{"type":"string","enum":["1.0"]},"config_version":{"type":"string","default":"2.0","description":"Version of the historical-health calculation configuration. Configuration 2.0 uses a 25-member default sustainability threshold and independent recent-award classification."},"status":{"type":"string","enum":["available","limited_history","insufficient_data","no_history"],"description":"`no_history` is the deterministic empty DTO. `insufficient_data` lacks the required scored-component coverage."},"score":{"type":"number","nullable":true,"minimum":0,"maximum":100,"description":"Explainable weighted five-year diagnostic score. It does not determine historical_class and can therefore be lower for a club classified A from recent Distinguished outcomes. Null for no history or insufficient component coverage."},"historical_class":{"type":"string","nullable":true,"enum":["A","B","C","D"],"description":"Recent Distinguished-performance class, independent of the weighted score. It is derived from the latest up-to-three completed programme years with recognized award semantics: A is regularly President's/Smedley Distinguished, B is frequently Distinguished or better, C is occasional Distinguished, and D is rare/never Distinguished. Null only when the classification window has insufficient recognized award evidence."},"trajectory":{"type":"string","nullable":true,"enum":["Growing","Stable","Declining","Recovering","Volatile"],"description":"Membership-risk trajectory. Classification uses actual year-end memberships capped at the configured 25-member sustainability threshold, so changes wholly above that threshold are neutral; raw, uncapped trend metrics remain in trend. Null until at least two observed memberships exist."},"profile":{"type":"string","nullable":true,"enum":["Healthy & Growing","Healthy & Stable","Strong but Declining","Recovering","Volatile","Long-Term At Risk"],"description":"Combined independently derived historical class and benchmark-adjusted trajectory; it does not depend on score. Null when either historical_class or trajectory is unavailable."},"years_analyzed":{"type":"integer","minimum":0,"maximum":5},"period":{"type":"object","required":["requested_max_years","completed_through","earliest","latest","missing_years"],"properties":{"requested_max_years":{"type":"integer","enum":[5]},"completed_through":{"type":"string","pattern":"^\\d{4}-\\d{4}$","description":"Most recent eligible completed fiscal year."},"earliest":{"type":"string","nullable":true,"pattern":"^\\d{4}-\\d{4}$"},"latest":{"type":"string","nullable":true,"pattern":"^\\d{4}-\\d{4}$"},"missing_years":{"type":"array","items":{"type":"string","pattern":"^\\d{4}-\\d{4}$"},"description":"Gaps between selected observed fiscal years; no data is inferred for them."}}},"trend":{"type":"object","required":["membership_change_percent_per_year","membership_volatility","latest_year_end_membership"],"properties":{"membership_change_percent_per_year":{"type":"number","nullable":true,"description":"Raw annualized year-end membership change percentage using actual, uncapped memberships. This metric is context only and is not the trajectory-classification rate."},"membership_volatility":{"type":"number","nullable":true,"description":"Raw coefficient of variation of observed actual, uncapped year-end membership. The benchmark-adjusted volatility used for trajectory classification is exposed in explainability evidence."},"latest_year_end_membership":{"type":"number","nullable":true,"description":"Latest actual, uncapped year-end membership."}}},"yearly":{"type":"array","maxItems":5,"items":{"$ref":"#/components/schemas/ClubHistoricalHealthYear"}},"explainability":{"type":"object","required":["components","recent_award_classification","benchmark_adjusted_trajectory","reasons"],"properties":{"components":{"type":"array","description":"Stable component-key detail supporting the diagnostic score. Recent-award classification and benchmark-adjusted trajectory evidence are top-level explainability fields.","items":{"$ref":"#/components/schemas/HistoricalHealthComponent"}},"recent_award_classification":{"$ref":"#/components/schemas/HistoricalAwardClassificationEvidence","description":"Top-level evidence for the independent historical_class calculation from recent recognized awards."},"benchmark_adjusted_trajectory":{"$ref":"#/components/schemas/HistoricalBenchmarkAdjustedTrajectoryEvidence","description":"Top-level evidence for membership-risk trajectory classification using the benchmark-adjusted membership series."},"reasons":{"type":"array","description":"Human-readable calculation disclosures, including why score and historical class may differ, benchmark-adjusted trajectory inputs, and safe declines neutralized at or above the sustainability threshold.","items":{"type":"string"}}}},"data_quality":{"type":"object","required":["confidence","excluded_years","missing_metrics","warnings"],"properties":{"confidence":{"type":"string","enum":["high","medium","low","none"]},"excluded_years":{"type":"array","items":{"type":"object","required":["fiscal_year","reason"],"properties":{"fiscal_year":{"type":"string"},"reason":{"type":"string"}}}},"missing_metrics":{"type":"array","items":{"type":"string"}},"warnings":{"type":"array","items":{"type":"string"}}}}}},"DistrictInsights":{"type":"object","nullable":true,"description":"Toastmasters rules evaluated for the district as of the report date (src/domain): the month's DCP target, the Distinguished status of every division and area by the same rules as the division insights, and each area's Area Director visit rounds. Temporary divisions and areas are left out. Null when the district has no club rows with an import date.","required":["as_of","month","month_target","show_potential_metrics","divisions"],"properties":{"as_of":{"type":"string","format":"date","description":"When the district's club rows for the reported fiscal month were last imported, no later than that month's end."},"month":{"type":"string"},"month_target":{"type":"integer","description":"Goals a club should have met by this month."},"show_potential_metrics":{"type":"boolean","description":"False in April – June, when clubs can become Distinguished outright."},"divisions":{"type":"array","items":{"type":"object","properties":{"division":{"type":"string"},"distinguished_status":{"type":"string","enum":["D","S","P",null],"nullable":true},"areas":{"type":"array","items":{"type":"object","properties":{"area":{"type":"string"},"distinguished_status":{"type":"string","enum":["D","S","P",null],"nullable":true},"visits":{"type":"object","nullable":true,"description":"The Area Director's club visits in each round (75% of the area's club base); null when the area has no clubs or any club lacks visit data.","properties":{"nov":{"type":"object","properties":{"clubs_visited":{"type":"integer"},"clubs_required":{"type":"integer","description":"75% of the area's club base, rounded up (its clubs when it has no base)."},"status":{"type":"object","properties":{"state":{"type":"string","enum":["met","notDue","missed"]},"dueLabel":{"type":"string"}},"required":["state","dueLabel"]}},"required":["clubs_visited","clubs_required","status"]},"may":{"type":"object","properties":{"clubs_visited":{"type":"integer"},"clubs_required":{"type":"integer","description":"75% of the area's club base, rounded up (its clubs when it has no base)."},"status":{"type":"object","properties":{"state":{"type":"string","enum":["met","notDue","missed"]},"dueLabel":{"type":"string"}},"required":["state","dueLabel"]}},"required":["clubs_visited","clubs_required","status"]}},"required":["nov","may"]}},"required":["area","distinguished_status","visits"]}}},"required":["division","distinguished_status","areas"]}}}},"DivisionInsights":{"type":"object","nullable":true,"description":"Toastmasters rules evaluated for the division as of the report date (src/domain): its Distinguished status, the area visit summary, officer training for the division and each area, and each area's Distinguished status. Null when the division has no club rows with an import date.","required":["as_of","month","month_target","show_potential_metrics","distinguished_status","on_track_clubs","visits","officer_training","areas"],"properties":{"as_of":{"type":"string","format":"date","description":"Report date: when the division's club rows were last imported, no later than the end of their fiscal month."},"month":{"type":"string"},"month_target":{"type":"integer","description":"Goals a club should have met by this month."},"show_potential_metrics":{"type":"boolean","description":"False in April – June, when clubs can become Distinguished outright."},"distinguished_status":{"type":"string","enum":["D","S","P",null],"nullable":true},"on_track_clubs":{"type":"integer","description":"Clubs with 20+ members and at least this month's target of goals."},"visits":{"type":"object","nullable":true,"description":"Area Director visits across the areas (75% of each area's clubs); null when any club lacks visit data.","properties":{"areaCount":{"type":"integer"},"julyOct":{"type":"object","properties":{"clubsVisited":{"type":"integer"},"clubsRequired":{"type":"integer"},"areasMet":{"type":"integer"}},"required":["clubsVisited","clubsRequired","areasMet"]},"janMay":{"type":"object","properties":{"clubsVisited":{"type":"integer"},"clubsRequired":{"type":"integer"},"areasMet":{"type":"integer"}},"required":["clubsVisited","clubsRequired","areasMet"]}},"required":["areaCount","julyOct","janMay"]},"officer_training":{"type":"object","properties":{"round_1":{"type":"object","properties":{"clubs_counted":{"type":"integer","description":"Clubs that count for the round: not suspended, and for round 1 chartered by 31 August."},"officers_trained":{"type":"integer","description":"The division's reported total when there is one, otherwise the counted clubs' sum."},"officers_possible":{"type":"integer","description":"7 officers per counted club."},"trained_pct":{"type":"integer","nullable":true},"window_open":{"type":"boolean"}},"required":["clubs_counted","officers_trained","officers_possible","trained_pct","window_open"]},"round_2":{"type":"object","properties":{"clubs_counted":{"type":"integer","description":"Clubs that count for the round: not suspended, and for round 1 chartered by 31 August."},"officers_trained":{"type":"integer","description":"The division's reported total when there is one, otherwise the counted clubs' sum."},"officers_possible":{"type":"integer","description":"7 officers per counted club."},"trained_pct":{"type":"integer","nullable":true},"window_open":{"type":"boolean"}},"required":["clubs_counted","officers_trained","officers_possible","trained_pct","window_open"]}},"required":["round_1","round_2"]},"areas":{"type":"array","items":{"type":"object","properties":{"area":{"type":"string"},"distinguished_status":{"type":"string","enum":["D","S","P",null],"nullable":true},"officers_round_1_pct":{"type":"integer"},"officers_round_2_pct":{"type":"integer"}},"required":["area","distinguished_status","officers_round_1_pct","officers_round_2_pct"]}}}},"AreaInsights":{"type":"object","nullable":true,"description":"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.","required":["as_of","month","month_target","distinguished_status","next_actions","on_track_clubs","visits","officer_training","clubs"],"properties":{"as_of":{"type":"string","format":"date","description":"Report date: the newest club row in the area."},"month":{"type":"string"},"month_target":{"type":"integer","description":"Goals a club should have met by this month."},"distinguished_status":{"type":"string","enum":["D","S","P",null],"nullable":true},"next_actions":{"type":"array","description":"Most time-sensitive first.","items":{"type":"object","required":["code","title","hint"],"properties":{"code":{"type":"string","description":"Stable identifier: good-standing, nov-visits, may-visits, training-round-2, small-clubs, csp or distinguished-area."},"key":{"type":"string","description":"Same as code."},"title":{"type":"string"},"hint":{"type":"string"},"when":{"type":"string","description":"When it's due, e.g. \"due 30 Nov\"."}}}},"on_track_clubs":{"type":"integer","description":"Clubs with 20+ members and at least this month's target of goals."},"visits":{"type":"object","properties":{"nov":{"type":"object","properties":{"clubs_visited":{"type":"integer"},"clubs_required":{"type":"integer","description":"75% of the area's club base, rounded up (its clubs when it has no base)."},"visited_pct":{"type":"integer","description":"Visited share of the club base."},"status":{"type":"object","properties":{"state":{"type":"string","enum":["met","notDue","missed"]},"dueLabel":{"type":"string"}},"required":["state","dueLabel"]},"window_open":{"type":"boolean"}},"required":["clubs_visited","clubs_required","visited_pct","status","window_open"]},"may":{"type":"object","properties":{"clubs_visited":{"type":"integer"},"clubs_required":{"type":"integer","description":"75% of the area's club base, rounded up (its clubs when it has no base)."},"visited_pct":{"type":"integer","description":"Visited share of the club base."},"status":{"type":"object","properties":{"state":{"type":"string","enum":["met","notDue","missed"]},"dueLabel":{"type":"string"}},"required":["state","dueLabel"]},"window_open":{"type":"boolean"}},"required":["clubs_visited","clubs_required","visited_pct","status","window_open"]}},"required":["nov","may"]},"officer_training":{"type":"object","properties":{"round_1":{"type":"object","properties":{"clubs_counted":{"type":"integer","description":"Clubs that count for the round: not suspended, and for round 1 chartered by 31 August."},"officers_trained":{"type":"integer"},"officers_possible":{"type":"integer","description":"7 officers per counted club."},"trained_pct":{"type":"integer","nullable":true},"window_open":{"type":"boolean"}},"required":["clubs_counted","officers_trained","officers_possible","trained_pct","window_open"]},"round_2":{"type":"object","properties":{"clubs_counted":{"type":"integer","description":"Clubs that count for the round: not suspended, and for round 1 chartered by 31 August."},"officers_trained":{"type":"integer"},"officers_possible":{"type":"integer","description":"7 officers per counted club."},"trained_pct":{"type":"integer","nullable":true},"window_open":{"type":"boolean"}},"required":["clubs_counted","officers_trained","officers_possible","trained_pct","window_open"]}},"required":["round_1","round_2"]},"clubs":{"type":"array","items":{"type":"object","properties":{"club_number":{"type":"string"},"club_name":{"type":"string"},"progress":{"type":"object","description":"Distinguished level achieved and what the next needs.","additionalProperties":true},"milestone":{"type":"object","properties":{"achieved":{"type":"string","nullable":true},"next":{"type":"string","nullable":true}},"required":["achieved","next"]},"below_month_target":{"type":"boolean"},"needs":{"type":"object","description":"Reminders that apply now: an open window and a requirement not yet met.","properties":{"officers_round_1":{"type":"boolean"},"officers_round_2":{"type":"boolean"},"nov_visit":{"type":"boolean"},"may_visit":{"type":"boolean"},"club_success_plan":{"type":"boolean"},"club_coach":{"type":"boolean"}},"required":["officers_round_1","officers_round_2","nov_visit","may_visit","club_success_plan","club_coach"]},"officers_round_2_due":{"type":"object","properties":{"state":{"type":"string","enum":["met","notDue","missed"]},"dueLabel":{"type":"string"}},"required":["state","dueLabel"]},"nov_visit_due":{"type":"object","properties":{"state":{"type":"string","enum":["met","notDue","missed"]},"dueLabel":{"type":"string"}},"required":["state","dueLabel"]},"may_visit_due":{"type":"object","properties":{"state":{"type":"string","enum":["met","notDue","missed"]},"dueLabel":{"type":"string"}},"required":["state","dueLabel"]}},"required":["club_number","club_name","progress","milestone","below_month_target","needs","officers_round_2_due","nov_visit_due","may_visit_due"]}}}},"ClubInsights":{"type":"object","nullable":true,"description":"Toastmasters rules evaluated for the club as of the report date (src/domain): good standing, the Club Success Plan deadline, Distinguished progress and ranked next actions. Null when the club has no performance record or no report date.","required":["as_of","good_standing","success_plan","distinguished_progress","next_actions"],"properties":{"as_of":{"type":"string","format":"date","description":"Report date the rules were evaluated for: the newest daily report or performance snapshot, capped at 30 June of a past fiscal year."},"good_standing":{"type":"object","nullable":true,"description":"Null when there is neither a club status nor a dues report to go on.","required":["state","period","paid_members","members_needed","in_club_base"],"properties":{"state":{"type":"string","enum":["good","low","ineligible","suspended"]},"period":{"type":"string","enum":["October","April"],"description":"Renewal period the state is for."},"paid_members":{"type":"integer"},"members_needed":{"type":"integer","description":"Paid members still needed for the 8-member minimum."},"in_club_base":{"type":"boolean","description":"Whether the club started the year in good standing."},"suspend_date":{"type":"string","nullable":true,"description":"Present only for a suspended club."},"charter":{"type":"object","description":"Present for a club chartered in the last 12 months with charter payments.","properties":{"date":{"type":"string","format":"date"},"members":{"type":"integer"}},"required":["date","members"]}}},"success_plan":{"type":"object","nullable":true,"description":"The 90-day Club Success Plan deadline for a new club or one that started outside the club base.","required":["reason","deadline","status"],"properties":{"reason":{"type":"string","enum":["new-club","outside-base"]},"deadline":{"type":"string","format":"date"},"status":{"type":"string","enum":["submitted","due","missed"]}}},"distinguished_progress":{"type":"object","required":["achieved","achieved_standing","next"],"properties":{"achieved":{"type":"string","nullable":true,"description":"Highest level whose goal and member requirements are met."},"achieved_standing":{"type":"string","nullable":true,"enum":["meets","ready","potential",null],"description":"How far the achieved level is. A club can only become Distinguished from April: before then it's \"ready\" once April renewals are paid, otherwise \"potential\". Null when no level is achieved."},"next":{"type":"object","nullable":true,"properties":{"level":{"type":"string"},"goals_needed":{"type":"integer"},"members_needed":{"type":"object","properties":{"needed":{"type":"integer"},"via":{"type":"string","enum":["members","netGrowth"]},"target":{"type":"integer"}},"required":["needed","via","target"]}},"required":["level","goals_needed","members_needed"]}}},"next_actions":{"type":"object","nullable":true,"description":"Null when the club has no DCP goal progress.","properties":{"month":{"type":"string"},"month_target":{"type":"integer","description":"Goals a club should have met by this month."},"goals_met":{"type":"integer"},"goals_behind":{"type":"integer"},"next_level":{"type":"object","nullable":true,"properties":{"level":{"type":"string"},"goals_needed":{"type":"integer"},"members_needed":{"type":"integer","nullable":true}},"required":["level","goals_needed","members_needed"]},"distinguished_out_of_reach":{"type":"boolean"},"actions":{"type":"array","description":"Every action, most urgent first; the dashboard shows the first three.","items":{"type":"object","required":["code","title","hint","owner"],"properties":{"code":{"type":"string","description":"Stable identifier, e.g. good-standing, membership, dues, success-plan, reinstate or a DCP goal key such as 7_new_members."},"goal_number":{"type":"integer","description":"DCP goal this action earns."},"label":{"type":"string","description":"Tag for actions that are not numbered goals."},"title":{"type":"string"},"hint":{"type":"string"},"owner":{"type":"string"}}}}},"required":["month","month_target","goals_met","goals_behind","next_level","distinguished_out_of_reach","actions"]}}},"ClubDashboardResponse":{"type":"object","description":"Comprehensive club dashboard data payload returned in the response data field.","required":["historical_health_analysis","club_outlook"],"properties":{"club_number":{"type":"string","description":"Club number"},"insights":{"$ref":"#/components/schemas/ClubInsights"},"month_change":{"description":"The club's figures against the fiscal month before; null without a performance record.","anyOf":[{"$ref":"#/components/schemas/ClubMonthChange"},{"type":"object","nullable":true,"enum":[null]}]},"historical_health_analysis":{"$ref":"#/components/schemas/ClubHistoricalHealthAnalysis","description":"Completed-programme-year analysis returned at data.historical_health_analysis, including a no_history DTO when no rows exist."},"club_outlook":{"$ref":"#/components/schemas/ClubOutlook"},"systems":{"type":"array","description":"Third-party systems the club is enrolled on now (first: Podium), read once a day from each system's own list of clubs. Empty when the club is on none.","items":{"type":"object","required":["system","name","url"],"properties":{"system":{"type":"string","description":"The system's key","example":"podium"},"name":{"type":"string","description":"The system's name","example":"Podium"},"url":{"type":"string","format":"uri","description":"The club's own page on the system","example":"https://form-ui.podium-app.cloud/club/Lisbon-Toastmasters-Club"},"enrolled_since":{"type":"string","nullable":true,"description":"YYYY-MM-DD the club was first seen on the system's list","example":"2026-11-17"}}}},"division_context":{"type":"object","nullable":true,"description":"Division-scoped context for this club","properties":{"division":{"type":"string"},"division_name":{"type":"string"},"area":{"type":"string"},"club_name":{"type":"string"},"october_renewals":{"type":"integer"},"april_renewals":{"type":"integer"},"active_members":{"type":"integer"},"educational_ratio":{"type":"number","description":"Educational awards ratio for the club (awards/base membership)"},"average_goals_met":{"type":"number","description":"Average goals met metric used in division context"},"goals_met":{"type":"integer"},"distinguished_status":{"type":"string"},"area_visits":{"type":"object","properties":{"nov_visit_award":{"type":"string","nullable":true},"may_visit_award":{"type":"string","nullable":true}},"additionalProperties":true},"last_updated":{"type":"string","nullable":true}},"additionalProperties":true},"area_context":{"type":"object","nullable":true,"description":"Area-scoped context for this club","properties":{"area":{"type":"string"},"area_name":{"type":"string"},"division":{"type":"string"},"district":{"type":"string"},"club_name":{"type":"string"},"october_renewals":{"type":"integer"},"april_renewals":{"type":"integer"},"active_members":{"type":"integer"},"educational_ratio":{"type":"number","description":"Educational awards ratio for the club (awards/base membership)"},"average_goals_met":{"type":"number","description":"Average goals met metric used in area context"},"goals_met":{"type":"integer"},"distinguished_status":{"type":"string"},"area_visits":{"type":"object","properties":{"nov_visit_award":{"type":"string","nullable":true},"may_visit_award":{"type":"string","nullable":true}},"additionalProperties":true},"last_updated":{"type":"string","nullable":true}},"additionalProperties":true}},"additionalProperties":true},"DistrictPaymentCounts":{"type":"object","description":"Membership payments to date: renewals by period, new and charter payments, and their total.","properties":{"october_renewals":{"type":"integer"},"april_renewals":{"type":"integer"},"late_renewals":{"type":"integer"},"total_renewals":{"type":"integer"},"new_payments":{"type":"integer"},"charter_payments":{"type":"integer"},"total_to_date":{"type":"integer"}},"required":["october_renewals","april_renewals","late_renewals","total_renewals","new_payments","charter_payments","total_to_date"]},"RecognitionLevelCounts":{"type":"object","description":"A goal or count for each recognition level.","properties":{"distinguished":{"type":"integer"},"select_distinguished":{"type":"integer"},"presidents_distinguished":{"type":"integer"},"smedley_distinguished":{"type":"integer"}},"required":["distinguished","select_distinguished","presidents_distinguished","smedley_distinguished"]},"EducationalAwardsBreakdown":{"type":"object","description":"Educational awards by Pathways level, DTMs and Pathways Mentor Program completions.","properties":{"level_1":{"type":"integer"},"level_2":{"type":"integer"},"level_3":{"type":"integer"},"level_4":{"type":"integer"},"level_5":{"type":"integer"},"dtm":{"type":"integer"},"mentor_program":{"type":"integer"}},"required":["level_1","level_2","level_3","level_4","level_5","dtm","mentor_program"]},"EducationalAwardsByPathway":{"type":"object","description":"Educational awards by Pathways path name. Only paths with an award appear.","additionalProperties":{"type":"integer"}},"DistrictMonthlySnapshot":{"type":"object","description":"The district's payments and recognition counts at the end of one fiscal month.","properties":{"fiscal_year":{"type":"string","pattern":"^\\d{4}-\\d{4}$"},"fiscal_month":{"type":"integer","minimum":1,"maximum":12},"paid_clubs":{"type":"integer"},"active_clubs":{"type":"integer"},"payments_to_date":{"type":"integer"},"payment_base":{"type":"integer"},"new_payments":{"type":"integer"},"april_renewals":{"type":"integer"},"late_renewals":{"type":"integer"},"charter_payments":{"type":"integer"},"total_distinguished_clubs":{"type":"integer"},"select_distinguished_clubs":{"type":"integer"},"presidents_distinguished_clubs":{"type":"integer"}},"required":["fiscal_year","fiscal_month","paid_clubs","active_clubs","payments_to_date","payment_base","new_payments","april_renewals","late_renewals","charter_payments","total_distinguished_clubs","select_distinguished_clubs","presidents_distinguished_clubs"]},"DistrictClubCoach":{"type":"object","description":"A club coach assigned to the club in the latest coach report.","properties":{"coach_name":{"type":"string","nullable":true},"coach_achievement":{"type":"string","nullable":true},"begin_date":{"type":"string","format":"date-time","nullable":true},"status":{"type":"string","nullable":true},"code":{"type":"string","nullable":true}},"required":["coach_name","coach_achievement","begin_date","status","code"]},"DistrictClub":{"type":"object","description":"A club's latest performance snapshot in the fiscal year.","properties":{"club_number":{"type":"string"},"club_name":{"type":"string","nullable":true},"division":{"type":"string"},"area":{"type":"string"},"fiscal_year":{"type":"string","pattern":"^\\d{4}-\\d{4}$"},"fiscal_month":{"type":"integer","nullable":true},"active_members":{"type":"integer","nullable":true},"member_base":{"type":"integer","nullable":true},"goals_met":{"type":"integer","nullable":true},"educational_awards":{"type":"integer"},"educational_ratio":{"type":"number","description":"Educational awards per member of the base; 0 when the base is 0."},"average_goals_met":{"type":"number"},"club_status":{"type":"string","nullable":true},"distinguished_status":{"type":"string","nullable":true},"levels_completed":{"type":"integer"},"level_1s":{"type":"integer"},"level_2s":{"type":"integer"},"add_level_2s":{"type":"integer"},"level_3s":{"type":"integer"},"level_4s_path_completions_or_dtm_awards":{"type":"integer"},"add_level_4s_path_completions_or_dtm_award":{"type":"integer"},"new_members":{"type":"integer"},"add_new_members":{"type":"integer"},"off_list_on_time":{"type":"integer"},"charter_date":{"type":"string","nullable":true},"latitude":{"type":"string","nullable":true},"longitude":{"type":"string","nullable":true},"meeting_times":{"type":"string","nullable":true,"description":"When the club meets, as its Find-a-Club listing says"},"meeting_schedule":{"type":"object","nullable":true,"description":"The meeting times read into weekdays and weeks of the month at import; null when the club lists none or they haven't been read yet","properties":{"version":{"type":"integer","description":"Parser version that read the text"},"placeable":{"type":"boolean","description":"Whether the rules say which days of a month the club meets"},"rules":{"type":"array","items":{"type":"object","properties":{"weekday":{"type":"integer","minimum":0,"maximum":6,"description":"0 = Sunday … 6 = Saturday"},"weeks":{"description":"\"every\" week, or the nth weekdays of the month (1-5, -1 for the last)","oneOf":[{"type":"string","enum":["every"]},{"type":"array","items":{"type":"integer"}}]}},"required":["weekday","weeks"]}},"time":{"type":"string","nullable":true,"description":"Start time as 24-hour \"HH:MM\""},"reason":{"type":"string","nullable":true,"enum":["no-day","fortnightly","monthly-count",null],"description":"Why an unplaceable schedule couldn't be placed"}},"required":["version","placeable","rules","time","reason"]},"october_renewals":{"type":"integer"},"april_renewals":{"type":"integer"},"late_renewals":{"type":"integer"},"new_payments":{"type":"integer"},"charter_payments":{"type":"integer"},"total_renewals":{"type":"integer"},"total_to_date":{"type":"integer"},"csp_submitted":{"type":"boolean","nullable":true,"enum":[true,null],"description":"True when the club has submitted its Club Success Plan, otherwise null."},"nov_visit_award":{"type":"integer","nullable":true},"may_visit_award":{"type":"integer","nullable":true},"off_trained_round_1":{"type":"integer","nullable":true},"off_trained_round_2":{"type":"integer","nullable":true},"april_renewal_status":{"type":"string","nullable":true},"october_renewal_status":{"type":"string","nullable":true},"coaches":{"type":"array","items":{"$ref":"#/components/schemas/DistrictClubCoach"}},"member_payments":{"$ref":"#/components/schemas/DistrictPaymentCounts"}},"required":["club_number","club_name","division","area","fiscal_year","fiscal_month","active_members","member_base","goals_met","educational_awards","educational_ratio","average_goals_met","club_status","distinguished_status","levels_completed","level_1s","level_2s","add_level_2s","level_3s","level_4s_path_completions_or_dtm_awards","add_level_4s_path_completions_or_dtm_award","new_members","add_new_members","off_list_on_time","charter_date","latitude","longitude","meeting_times","meeting_schedule","october_renewals","april_renewals","late_renewals","new_payments","charter_payments","total_renewals","total_to_date","csp_submitted","nov_visit_award","may_visit_award","off_trained_round_1","off_trained_round_2","april_renewal_status","october_renewal_status","coaches","member_payments"]},"DistrictArea":{"type":"object","description":"An area's goals as Toastmasters publishes them, its club totals and its clubs.","properties":{"district":{"type":"string"},"division":{"type":"string"},"area":{"type":"string"},"fiscal_year":{"type":"string","pattern":"^\\d{4}-\\d{4}$"},"fiscal_month":{"type":"integer","minimum":1,"maximum":12},"distinguished":{"type":"string","nullable":true},"total_dist_clubs":{"type":"integer","nullable":true},"total_paid_clubs":{"type":"integer","nullable":true},"dist_club_goal_for_dist":{"type":"integer","nullable":true},"dist_club_goal_for_select_dist":{"type":"integer","nullable":true},"dist_club_goal_for_pres_dist":{"type":"integer","nullable":true},"paid_club_goal_for_dist":{"type":"integer","nullable":true},"paid_club_goal_for_select_dist":{"type":"integer","nullable":true},"paid_club_goal_for_pres_dist":{"type":"integer","nullable":true},"total_members":{"type":"integer"},"clubs_5plus_goals":{"type":"integer"},"clubs_20plus_members":{"type":"integer"},"clubs_with_officers_trained_round_1":{"type":"integer"},"clubs_with_officers_trained_round_2":{"type":"integer"},"member_base":{"type":"integer"},"educational_awards":{"type":"integer"},"levels_completed":{"type":"integer"},"payments_to_date":{"type":"integer"},"educational_ratio":{"type":"number","description":"Educational awards per member of the base; 0 when the base is 0."},"average_goals_met":{"type":"number","description":"Mean DCP goals met per club; 0 when there are no clubs."},"member_payments":{"$ref":"#/components/schemas/DistrictPaymentCounts"},"clubs":{"type":"array","items":{"$ref":"#/components/schemas/DistrictClub"}}},"required":["district","division","area","fiscal_year","fiscal_month","distinguished","total_dist_clubs","total_paid_clubs","dist_club_goal_for_dist","dist_club_goal_for_select_dist","dist_club_goal_for_pres_dist","paid_club_goal_for_dist","paid_club_goal_for_select_dist","paid_club_goal_for_pres_dist","total_members","clubs_5plus_goals","clubs_20plus_members","clubs_with_officers_trained_round_1","clubs_with_officers_trained_round_2","member_base","educational_awards","levels_completed","payments_to_date","educational_ratio","average_goals_met","member_payments","clubs"]},"DistrictDivision":{"type":"object","description":"A division's goals as Toastmasters publishes them, its club totals, payment goals and areas.","properties":{"district":{"type":"string"},"division":{"type":"string"},"fiscal_year":{"type":"string","pattern":"^\\d{4}-\\d{4}$"},"fiscal_month":{"type":"integer","minimum":1,"maximum":12},"distinguished":{"type":"string","nullable":true},"club_base":{"type":"integer","nullable":true},"total_dist_clubs":{"type":"integer","nullable":true},"total_paid_clubs":{"type":"integer","nullable":true},"dist_club_goal_for_dist":{"type":"integer","nullable":true},"dist_club_goal_for_select_dist":{"type":"integer","nullable":true},"dist_club_goal_for_pres_dist":{"type":"integer","nullable":true},"paid_club_goal_for_dist":{"type":"integer","nullable":true},"paid_club_goal_for_select_dist":{"type":"integer","nullable":true},"paid_club_goal_for_pres_dist":{"type":"integer","nullable":true},"total_members":{"type":"integer"},"clubs_5plus_goals":{"type":"integer"},"clubs_20plus_members":{"type":"integer"},"clubs_with_officers_trained_round_1":{"type":"integer"},"clubs_with_officers_trained_round_2":{"type":"integer"},"member_base":{"type":"integer"},"educational_awards":{"type":"integer"},"levels_completed":{"type":"integer"},"payments_to_date":{"type":"integer"},"educational_ratio":{"type":"number","description":"Educational awards per member of the base; 0 when the base is 0."},"average_goals_met":{"type":"number","description":"Mean DCP goals met per club; 0 when there are no clubs."},"member_payments":{"$ref":"#/components/schemas/DistrictPaymentCounts"},"payment_base":{"type":"integer","description":"The district's payment base shared out by the division's share of the district member base."},"payment_goals":{"$ref":"#/components/schemas/RecognitionLevelCounts"},"areas":{"type":"array","items":{"$ref":"#/components/schemas/DistrictArea"}}},"required":["district","division","fiscal_year","fiscal_month","distinguished","club_base","total_dist_clubs","total_paid_clubs","dist_club_goal_for_dist","dist_club_goal_for_select_dist","dist_club_goal_for_pres_dist","paid_club_goal_for_dist","paid_club_goal_for_select_dist","paid_club_goal_for_pres_dist","total_members","clubs_5plus_goals","clubs_20plus_members","clubs_with_officers_trained_round_1","clubs_with_officers_trained_round_2","member_base","educational_awards","levels_completed","payments_to_date","educational_ratio","average_goals_met","member_payments","payment_base","payment_goals","areas"]},"DistrictSummaryTotals":{"type":"object","description":"The district's totals, programme status and recognition goals for the fiscal month.","properties":{"total_divisions":{"type":"integer"},"total_areas":{"type":"integer"},"paid_clubs":{"type":"integer"},"active_clubs":{"type":"integer"},"total_clubs":{"type":"integer"},"payment_base":{"type":"integer"},"paid_club_base":{"type":"integer"},"total_ytd_payments":{"type":"integer","nullable":true},"distinguished_clubs":{"type":"integer"},"member_payments":{"$ref":"#/components/schemas/DistrictPaymentCounts"},"new_payments":{"type":"integer"},"april_renewals":{"type":"integer"},"late_renewals":{"type":"integer"},"charter_payments":{"type":"integer"},"payment_growth":{"type":"number","nullable":true,"description":"Payments to date as a percentage of the payment base."},"club_growth":{"type":"string","nullable":true},"total_distinguished_clubs":{"type":"integer"},"total_csps_completed":{"type":"integer"},"select_distinguished_clubs":{"type":"integer"},"presidents_distinguished_clubs":{"type":"integer"},"smedley_distinguished_clubs":{"type":"integer"},"dsp":{"type":"string","nullable":true},"training":{"type":"string","nullable":true},"market_analysis":{"type":"string","nullable":true},"region_advisor_meetings":{"type":"string","nullable":true},"distinguished":{"type":"string","nullable":true},"fiscal_year":{"type":"string","pattern":"^\\d{4}-\\d{4}$"},"fiscal_month":{"type":"integer","minimum":1,"maximum":12},"member_base":{"type":"integer"},"educational_awards":{"type":"integer"},"educational_awards_breakdown":{"$ref":"#/components/schemas/EducationalAwardsBreakdown"},"educational_awards_by_pathway":{"$ref":"#/components/schemas/EducationalAwardsByPathway"},"educational_ratio":{"type":"number"},"average_goals_met":{"type":"number"},"active_members":{"type":"integer"},"average_members_per_club":{"type":"number"},"average_new_members_per_club":{"type":"number"},"clubs_5plus_goals":{"type":"integer"},"clubs_20plus_members":{"type":"integer"},"clubs_trained_r1":{"type":"integer"},"clubs_trained_r2":{"type":"integer"},"nov_visit_award":{"type":"integer"},"may_visit_award":{"type":"integer"},"monthly_membership_goals":{"description":"This month's membership payment targets; null when the payment base is 0.","anyOf":[{"$ref":"#/components/schemas/RecognitionLevelCounts"},{"type":"object","nullable":true,"enum":[null]}]},"monthly_membership_goals_fiscal_month":{"type":"integer","nullable":true},"membership_goals":{"$ref":"#/components/schemas/RecognitionLevelCounts"},"paid_club_goals":{"$ref":"#/components/schemas/RecognitionLevelCounts"},"distinguished_club_goals":{"$ref":"#/components/schemas/RecognitionLevelCounts"},"monthly_paid_club_goals":{"description":"This month's paid club targets.","anyOf":[{"$ref":"#/components/schemas/RecognitionLevelCounts"},{"type":"object","nullable":true,"enum":[null]}]},"monthly_paid_club_goals_fiscal_month":{"type":"integer","nullable":true}},"required":["total_divisions","total_areas","paid_clubs","active_clubs","total_clubs","payment_base","paid_club_base","total_ytd_payments","distinguished_clubs","member_payments","new_payments","april_renewals","late_renewals","charter_payments","payment_growth","club_growth","total_distinguished_clubs","total_csps_completed","select_distinguished_clubs","presidents_distinguished_clubs","smedley_distinguished_clubs","dsp","training","market_analysis","region_advisor_meetings","distinguished","fiscal_year","fiscal_month","member_base","educational_awards","educational_awards_breakdown","educational_awards_by_pathway","educational_ratio","average_goals_met","active_members","average_members_per_club","average_new_members_per_club","clubs_5plus_goals","clubs_20plus_members","clubs_trained_r1","clubs_trained_r2","nov_visit_award","may_visit_award","monthly_membership_goals","monthly_membership_goals_fiscal_month","membership_goals","paid_club_goals","distinguished_club_goals","monthly_paid_club_goals","monthly_paid_club_goals_fiscal_month"]},"DistrictProspectiveClub":{"type":"object","description":"A club in the district's latest prospective clubs report.","properties":{"club_number":{"type":"string","nullable":true},"club_name":{"type":"string","nullable":true},"division":{"type":"string","nullable":true},"area":{"type":"string","nullable":true},"status":{"type":"string","nullable":true},"date":{"type":"string","format":"date-time"}},"required":["club_number","club_name","division","area","status","date"]},"DistrictDashboardResponse":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"fiscal_year":{"type":"string","pattern":"^\\d{4}-\\d{4}$"},"fiscal_month":{"type":"integer","minimum":1,"maximum":12},"data":{"type":"object","properties":{"district":{"type":"string"},"region":{"type":"string","nullable":true},"fiscal_year":{"type":"string","pattern":"^\\d{4}-\\d{4}$"},"district_context":{"type":"object","description":"District-wide educational and goal benchmarks.","properties":{"district":{"type":"string"},"region":{"type":"string","nullable":true},"fiscal_year":{"type":"string","pattern":"^\\d{4}-\\d{4}$"},"fiscal_month":{"type":"integer","minimum":1,"maximum":12},"educational_awards":{"type":"integer"},"member_base":{"type":"integer"},"educational_ratio":{"type":"number"},"average_goals_met":{"type":"number"}},"required":["district","region","fiscal_year","fiscal_month","educational_awards","member_base","educational_ratio","average_goals_met"]},"divisions":{"type":"array","items":{"$ref":"#/components/schemas/DistrictDivision"}},"monthly_history":{"type":"array","items":{"$ref":"#/components/schemas/DistrictMonthlySnapshot"}},"insights":{"description":"Rule-built insights for the report date; null when no report date is known.","anyOf":[{"$ref":"#/components/schemas/DistrictInsights"},{"type":"object","nullable":true,"enum":[null]}]},"month_change":{"description":"The district's totals against the fiscal month before, with each division's change in parts; null when no clubs were reported for the month.","anyOf":[{"$ref":"#/components/schemas/MonthChange"},{"type":"object","nullable":true,"enum":[null]}]}},"required":["district","region","fiscal_year","district_context","divisions","monthly_history","insights","month_change"]},"summary":{"$ref":"#/components/schemas/DistrictSummaryTotals"},"prospective_clubs":{"type":"array","items":{"$ref":"#/components/schemas/DistrictProspectiveClub"}},"monthly_history":{"type":"array","description":"The same as data.monthly_history.","items":{"$ref":"#/components/schemas/DistrictMonthlySnapshot"}},"filters":{"type":"object","required":["district","fiscalYear","latest"],"properties":{"district":{"type":"string"},"fiscalYear":{"type":"string","pattern":"^\\d{4}-\\d{4}$"},"fiscalMonth":{"type":"integer","minimum":1,"maximum":12,"description":"Sent only when the request names a fiscal month."},"latest":{"type":"boolean"}}},"timestamp":{"type":"string","format":"date-time"}},"required":["success","fiscal_year","fiscal_month","data","summary","prospective_clubs","monthly_history","filters","timestamp"]},"GlobalDistrict":{"type":"object","description":"One district's payments, recognition counts and goals in the global summary.","properties":{"district":{"type":"string"},"region":{"type":"string","nullable":true},"fiscal_year":{"type":"string","pattern":"^\\d{4}-\\d{4}$"},"fiscal_month":{"type":"integer","minimum":1,"maximum":12},"payments_to_date":{"type":"integer"},"new_payments":{"type":"integer"},"april_payments":{"type":"integer"},"late_payments":{"type":"integer"},"charter_payments":{"type":"integer"},"payments_base":{"type":"integer"},"payment_growth":{"type":"number","nullable":true,"description":"Payments to date as a percentage of the payment base."},"active_clubs":{"type":"integer"},"paid_clubs":{"type":"integer"},"paid_club_base":{"type":"integer"},"club_growth":{"type":"string","nullable":true},"distinguished_clubs":{"type":"integer"},"total_distinguished_clubs":{"type":"integer"},"presidents_distinguished_clubs":{"type":"integer"},"select_distinguished_clubs":{"type":"integer"},"smedley_distinguished_clubs":{"type":"integer"},"distinguished":{"type":"string","nullable":true,"enum":["President's Distinguished","Select Distinguished","Distinguished","None",null],"description":"The district's recognition level on current progress."},"distinguished_status":{"type":"string","nullable":true,"enum":["President's Distinguished","Select Distinguished","Distinguished","None",null],"description":"The same as distinguished."},"dsp":{"type":"string","nullable":true},"training":{"type":"string","nullable":true},"market_analysis":{"type":"string","nullable":true},"region_advisor_meetings":{"type":"string","nullable":true},"communication_plan":{"type":"string","nullable":true},"october_payments":{"type":"integer"},"distinguished_clubs_percent":{"type":"number","description":"Distinguished clubs as a percentage of the paid club base."},"clubs_5plus_goals":{"type":"integer"},"clubs_20plus_members":{"type":"integer"},"inactive_clubs":{"type":"integer"},"educational_ratio":{"type":"number"},"average_goals_met":{"type":"number"},"new_clubs_count":{"type":"integer"},"total_csps_completed":{"type":"integer"},"dist_club_goal_for_dist":{"type":"integer"},"dist_club_goal_for_select_dist":{"type":"integer"},"dist_club_goal_for_pres_dist":{"type":"integer"},"dist_club_goal_for_smed_dist":{"type":"integer"},"paid_club_goal_for_dist":{"type":"integer"},"paid_club_goal_for_select_dist":{"type":"integer"},"paid_club_goal_for_pres_dist":{"type":"integer"},"paid_club_goal_for_smed_dist":{"type":"integer"}},"required":["district","region","fiscal_year","fiscal_month","payments_to_date","new_payments","april_payments","late_payments","charter_payments","payments_base","payment_growth","active_clubs","paid_clubs","paid_club_base","club_growth","distinguished_clubs","total_distinguished_clubs","presidents_distinguished_clubs","select_distinguished_clubs","smedley_distinguished_clubs","distinguished","distinguished_status","dsp","training","market_analysis","region_advisor_meetings","communication_plan","october_payments","distinguished_clubs_percent","clubs_5plus_goals","clubs_20plus_members","inactive_clubs","educational_ratio","average_goals_met","new_clubs_count","total_csps_completed","dist_club_goal_for_dist","dist_club_goal_for_select_dist","dist_club_goal_for_pres_dist","dist_club_goal_for_smed_dist","paid_club_goal_for_dist","paid_club_goal_for_select_dist","paid_club_goal_for_pres_dist","paid_club_goal_for_smed_dist"]},"GlobalRegion":{"type":"object","description":"A region's totals over its districts.","properties":{"region":{"type":"string"},"districts":{"type":"array","items":{"type":"string"}},"payments_to_date":{"type":"integer"},"new_payments":{"type":"integer"},"april_payments":{"type":"integer"},"late_payments":{"type":"integer"},"charter_payments":{"type":"integer"},"payments_base":{"type":"integer"},"active_clubs":{"type":"integer"},"paid_clubs":{"type":"integer"},"paid_club_base":{"type":"integer"},"distinguished_clubs":{"type":"integer"},"total_distinguished_clubs":{"type":"integer"},"presidents_distinguished_clubs":{"type":"integer"},"select_distinguished_clubs":{"type":"integer"},"smedley_distinguished_clubs":{"type":"integer"},"educational_awards":{"type":"integer"},"base_membership":{"type":"integer"},"total_goals_met":{"type":"integer"},"total_clubs":{"type":"integer"},"october_payments":{"type":"integer"},"total_districts":{"type":"integer"},"distinguished_rate":{"type":"number","description":"Distinguished clubs as a percentage of active clubs."},"paid_rate":{"type":"number","description":"Paid clubs as a percentage of active clubs."},"average_clubs_per_district":{"type":"number"},"educational_ratio":{"type":"number"},"average_goals_met":{"type":"number"}},"required":["region","districts","payments_to_date","new_payments","april_payments","late_payments","charter_payments","payments_base","active_clubs","paid_clubs","paid_club_base","distinguished_clubs","total_distinguished_clubs","presidents_distinguished_clubs","select_distinguished_clubs","smedley_distinguished_clubs","educational_awards","base_membership","total_goals_met","total_clubs","october_payments","total_districts","distinguished_rate","paid_rate","average_clubs_per_district","educational_ratio","average_goals_met"]},"GlobalSummaryResponse":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"fiscal_year":{"type":"string","pattern":"^\\d{4}-\\d{4}$"},"fiscal_month":{"type":"integer","minimum":1,"maximum":12,"nullable":true,"description":"The requested fiscal month, else the current one for the current fiscal year, else null."},"data":{"type":"object","properties":{"total_districts":{"type":"integer"},"total_regions":{"type":"integer"},"payments_to_date":{"type":"integer"},"new_payments":{"type":"integer"},"april_payments":{"type":"integer"},"late_payments":{"type":"integer"},"charter_payments":{"type":"integer"},"payments_base":{"type":"integer"},"active_clubs":{"type":"integer"},"paid_clubs":{"type":"integer"},"paid_club_base":{"type":"integer"},"distinguished_clubs":{"type":"integer"},"total_distinguished_clubs":{"type":"integer"},"presidents_distinguished_clubs":{"type":"integer"},"select_distinguished_clubs":{"type":"integer"},"smedley_distinguished_clubs":{"type":"integer"},"total_csps_completed":{"type":"integer"},"educational_awards_breakdown":{"$ref":"#/components/schemas/EducationalAwardsBreakdown"},"educational_awards_by_pathway":{"$ref":"#/components/schemas/EducationalAwardsByPathway"},"distinguished_rate":{"type":"number","description":"Distinguished clubs as a percentage of active clubs."},"paid_rate":{"type":"number","description":"Paid clubs as a percentage of active clubs."},"average_clubs_per_district":{"type":"number"},"districts":{"type":"array","items":{"$ref":"#/components/schemas/GlobalDistrict"}},"regions":{"type":"array","items":{"$ref":"#/components/schemas/GlobalRegion"}}},"required":["total_districts","total_regions","payments_to_date","new_payments","april_payments","late_payments","charter_payments","payments_base","active_clubs","paid_clubs","paid_club_base","distinguished_clubs","total_distinguished_clubs","presidents_distinguished_clubs","select_distinguished_clubs","smedley_distinguished_clubs","total_csps_completed","educational_awards_breakdown","educational_awards_by_pathway","distinguished_rate","paid_rate","average_clubs_per_district","districts","regions"]},"metadata":{"type":"object","properties":{"last_updated":{"type":"string","format":"date-time"},"cache_ttl":{"type":"integer","description":"Seconds a complete response is reused for."},"fiscal_year":{"type":"string","pattern":"^\\d{4}-\\d{4}$"},"response_time_ms":{"type":"integer"},"partial_data":{"type":"boolean","description":"True when the educational awards could not be read."},"cached":{"type":"boolean"}},"required":["last_updated","cache_ttl","fiscal_year","response_time_ms","partial_data","cached"]},"filters":{"type":"object","description":"Always empty; kept for compatibility.","additionalProperties":false},"timestamp":{"type":"string","format":"date-time"}},"required":["success","fiscal_year","fiscal_month","data","metadata","filters","timestamp"]},"DistrictClubHistoricalHealthItem":{"type":"object","description":"One club in the resolved district roster. club_number is canonicalized by removing leading zeroes. historical_health_analysis is the unchanged reusable completed-programme-year analysis.","required":["rank","club_number","club_name","division","area","club_status","active_members","distinguished_status","historical_health_analysis","club_outlook"],"properties":{"rank":{"type":"integer","nullable":true,"minimum":1,"description":"Unique 1-based ordinal rank for a finite analysis score; null for unranked null-score clubs."},"club_number":{"type":"string","description":"Canonical club number without leading zeroes."},"club_name":{"type":"string","nullable":true},"division":{"type":"string","nullable":true},"area":{"type":"string","nullable":true},"club_status":{"type":"string","nullable":true},"active_members":{"type":"number","nullable":true},"distinguished_status":{"type":"string","nullable":true},"historical_health_analysis":{"$ref":"#/components/schemas/ClubHistoricalHealthAnalysis"},"club_outlook":{"$ref":"#/components/schemas/ClubOutlook"}}},"DistrictClubHistoricalHealthResponse":{"type":"object","description":"One district club-roster snapshot with each club's complete reusable historical-health analysis. Roster fiscal filters select this snapshot only; they do not alter the completed-history years selected by the analysis.","required":["success","fiscal_year","fiscal_month","data","summary","metadata","filters","timestamp"],"properties":{"success":{"type":"boolean","enum":[true]},"fiscal_year":{"type":"string","pattern":"^\\d{4}-\\d{4}$","description":"Fiscal year of the one resolved district roster snapshot."},"fiscal_month":{"type":"integer","minimum":1,"maximum":12,"description":"Fiscal month of the one resolved district roster snapshot."},"data":{"type":"object","required":["district","region","clubs"],"properties":{"district":{"type":"string"},"region":{"type":"string","nullable":true},"clubs":{"type":"array","description":"Complete resolved roster, including clubs with missing history. A known district snapshot with no clubs returns an empty array.","items":{"$ref":"#/components/schemas/DistrictClubHistoricalHealthItem"}}}},"summary":{"type":"object","required":["total_clubs","ranked_clubs","unranked_clubs","analysis_status_counts"],"properties":{"total_clubs":{"type":"integer","minimum":0},"ranked_clubs":{"type":"integer","minimum":0},"unranked_clubs":{"type":"integer","minimum":0},"analysis_status_counts":{"type":"object","required":["available","limited_history","insufficient_data","no_history"],"properties":{"available":{"type":"integer","minimum":0},"limited_history":{"type":"integer","minimum":0},"insufficient_data":{"type":"integer","minimum":0},"no_history":{"type":"integer","minimum":0}}}}},"metadata":{"type":"object","required":["analysis_current_fiscal_year","ranking"],"properties":{"analysis_current_fiscal_year":{"type":"string","pattern":"^\\d{4}-\\d{4}$","description":"Current fiscal year passed to each completed-programme-year analysis; it is independent of the roster snapshot filters."},"ranking":{"type":"object","description":"Finite scores sort descending. Equal scores use canonical club number ascending, then receive unique ordinal ranks. Null scores sort last and are unranked.","required":["key","direction","nulls","tie_breaker","rank_style"],"properties":{"key":{"type":"string","enum":["historical_health_analysis.score"]},"direction":{"type":"string","enum":["desc"]},"nulls":{"type":"string","enum":["last_unranked"]},"tie_breaker":{"type":"string","enum":["normalized_club_number_asc"]},"rank_style":{"type":"string","enum":["ordinal"]}}}}},"filters":{"type":"object","required":["district","fiscalYear","fiscalMonth"],"properties":{"district":{"type":"string"},"fiscalYear":{"type":"string","pattern":"^\\d{4}-\\d{4}$"},"fiscalMonth":{"type":"integer","minimum":1,"maximum":12}}},"timestamp":{"type":"string","format":"date-time"}}},"DropdownRegionOption":{"type":"object","properties":{"value":{"type":"string","description":"The value to send back as a filter"},"label":{"type":"string","description":"Display text, e.g. \"District 74\""},"region":{"type":"string"}},"required":["value","label","region"]},"DropdownDistrictOption":{"type":"object","properties":{"value":{"type":"string","description":"The value to send back as a filter"},"label":{"type":"string","description":"Display text, e.g. \"District 74\""},"district":{"type":"string"},"region":{"type":"string","nullable":true}},"required":["value","label","district","region"]},"DropdownDivisionOption":{"type":"object","properties":{"value":{"type":"string","description":"The value to send back as a filter"},"label":{"type":"string","description":"Display text, e.g. \"District 74\""},"district":{"type":"string","nullable":true},"division":{"type":"string"}},"required":["value","label","district","division"]},"DropdownAreaOption":{"type":"object","properties":{"value":{"type":"string","description":"The value to send back as a filter"},"label":{"type":"string","description":"Display text, e.g. \"District 74\""},"district":{"type":"string","nullable":true},"division":{"type":"string","nullable":true},"area":{"type":"string"}},"required":["value","label","district","division","area"]},"DropdownRegionsResponse":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"array","items":{"$ref":"#/components/schemas/DropdownRegionOption"}},"metadata":{"type":"object","properties":{"timestamp":{"type":"string","format":"date-time"},"count":{"type":"integer","minimum":0,"description":"Number of options in data"},"last_updated":{"type":"string","format":"date-time"}},"required":["timestamp","count","last_updated"]}},"required":["success","data","metadata"]},"DropdownDistrictsResponse":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"array","items":{"$ref":"#/components/schemas/DropdownDistrictOption"}},"metadata":{"type":"object","properties":{"timestamp":{"type":"string","format":"date-time"},"count":{"type":"integer","minimum":0,"description":"Number of options in data"},"last_updated":{"type":"string","format":"date-time"}},"required":["timestamp","count","last_updated"]}},"required":["success","data","metadata"]},"DropdownDivisionsResponse":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"array","items":{"$ref":"#/components/schemas/DropdownDivisionOption"}},"metadata":{"type":"object","properties":{"timestamp":{"type":"string","format":"date-time"},"count":{"type":"integer","minimum":0,"description":"Number of options in data"},"district":{"type":"string","description":"The district filter applied, or \"all\""},"last_updated":{"type":"string","format":"date-time"}},"required":["timestamp","count","district","last_updated"]}},"required":["success","data","metadata"]},"DropdownAreasResponse":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"array","items":{"$ref":"#/components/schemas/DropdownAreaOption"}},"metadata":{"type":"object","properties":{"timestamp":{"type":"string","format":"date-time"},"count":{"type":"integer","minimum":0,"description":"Number of options in data"},"district":{"type":"string","description":"The district filter applied, or \"all\""},"division":{"type":"string","description":"The division filter applied, or \"all\""},"last_updated":{"type":"string","format":"date-time"}},"required":["timestamp","count","district","division","last_updated"]}},"required":["success","data","metadata"]},"DashboardFiltersResponse":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","required":["fiscalYears","months","districts"],"properties":{"fiscalYears":{"type":"array","items":{"type":"object","properties":{"value":{"type":"string"},"label":{"type":"string"}},"required":["value","label"]}},"months":{"type":"array","description":"Months with data in the fiscal year","items":{"type":"object","properties":{"value":{"type":"integer"},"label":{"type":"string"},"month":{"type":"integer"}},"required":["value","label","month"]}},"dates":{"type":"array","description":"Report dates in the month; sent only when a fiscal year and a month are given","items":{"type":"object","properties":{"value":{"type":"string"},"label":{"type":"string"},"date_value":{"type":"string"}},"required":["value","label","date_value"]}},"districts":{"type":"array","items":{"type":"object","properties":{"value":{"type":"string"},"label":{"type":"string"},"district":{"type":"string"}},"required":["value","label","district"]}}}},"metadata":{"type":"object","properties":{"fiscal_year_count":{"type":"integer","minimum":0},"month_count":{"type":"integer","minimum":0},"date_count":{"type":"integer","minimum":0},"district_count":{"type":"integer","minimum":0},"last_updated":{"type":"string","format":"date-time"}},"required":["fiscal_year_count","month_count","date_count","district_count","last_updated"]}},"required":["success","data","metadata"]},"HealthStatus":{"type":"object","required":["status"],"properties":{"status":{"type":"string","enum":["ok","unhealthy","error"]}}},"ReadinessStatus":{"type":"object","required":["status"],"properties":{"status":{"type":"string","enum":["ready","not ready"]}}},"LivenessStatus":{"type":"object","required":["status"],"properties":{"status":{"type":"string","enum":["alive"]}}},"DetailedHealth":{"type":"object","required":["status","timestamp","checks"],"properties":{"status":{"type":"string","enum":["healthy","unhealthy"]},"timestamp":{"type":"string","format":"date-time"},"checks":{"type":"object","required":["database","cache","memory","disk","uptime"],"properties":{"database":{"type":"object","required":["status"],"properties":{"status":{"type":"string","description":"\"healthy\" when the check passes"},"message":{"type":"string"}},"additionalProperties":true},"cache":{"type":"object","required":["status"],"properties":{"status":{"type":"string","description":"\"healthy\" when the check passes"},"message":{"type":"string"}},"additionalProperties":true},"memory":{"type":"object","required":["status"],"properties":{"status":{"type":"string","description":"\"healthy\" when the check passes"},"message":{"type":"string"}},"additionalProperties":true},"disk":{"type":"object","required":["status"],"properties":{"status":{"type":"string","description":"\"healthy\" when the check passes"},"message":{"type":"string"}},"additionalProperties":true},"uptime":{"type":"number","description":"Seconds the process has been running"}}}}},"DetailedHealthFailure":{"type":"object","required":["status","timestamp","error","message"],"properties":{"status":{"type":"string","enum":["error"]},"timestamp":{"type":"string","format":"date-time"},"error":{"type":"string"},"message":{"type":"string"}}},"MonthTotals":{"type":"object","description":"A scope's totals over its clubs for one fiscal month. Suspended clubs count only as suspended.","properties":{"clubs":{"type":"integer","description":"Clubs that aren't suspended."},"suspended_clubs":{"type":"integer"},"paid_clubs":{"type":"integer","description":"Clubs that aren't suspended with an October or April renewal on record."},"distinguished_clubs":{"type":"integer"},"active_members":{"type":"integer"},"goals_met":{"type":"integer","description":"DCP goals met, summed over the clubs."},"educational_awards":{"type":"integer"},"new_members":{"type":"integer","description":"New and additional new members counted for the DCP."}},"required":["clubs","suspended_clubs","paid_clubs","distinguished_clubs","active_members","goals_met","educational_awards","new_members"]},"MonthChangePart":{"type":"object","description":"One part's change: a division in a district, an area in a division, or a club in an area.","properties":{"key":{"type":"string","description":"The division letter, area number or club number."},"current":{"$ref":"#/components/schemas/MonthTotals"},"previous":{"description":"Last month's totals; null in July or when no clubs were reported last month.","anyOf":[{"$ref":"#/components/schemas/MonthTotals"},{"type":"object","nullable":true,"enum":[null]}]},"change":{"description":"This month's totals minus last month's; null when previous is.","anyOf":[{"$ref":"#/components/schemas/MonthTotals"},{"type":"object","nullable":true,"enum":[null]}]},"clubs_added":{"type":"array","items":{"type":"string"},"description":"Clubs here this month but not last month: chartered or moved in."},"clubs_removed":{"type":"array","items":{"type":"string"},"description":"Clubs here last month but not this month: moved out or no longer reported."}},"required":["key","current","previous","change","clubs_added","clubs_removed"]},"MonthChange":{"type":"object","description":"A district's, division's or area's totals for the reported fiscal month against the month before, from the monthly club snapshots, with the change for each of its parts. A club that moved counts in its new part this month and its old part last month.","properties":{"fiscal_year":{"type":"string","example":"2026-2027"},"fiscal_month":{"type":"integer","minimum":1,"maximum":12,"description":"Fiscal month (1 = July) of the figures."},"previous_fiscal_month":{"type":"integer","minimum":1,"maximum":11,"nullable":true,"description":"The fiscal month compared with; null in July, which starts the fiscal year."},"current":{"$ref":"#/components/schemas/MonthTotals"},"previous":{"description":"Last month's totals; null in July or when no clubs were reported last month.","anyOf":[{"$ref":"#/components/schemas/MonthTotals"},{"type":"object","nullable":true,"enum":[null]}]},"change":{"description":"This month's totals minus last month's; null when previous is.","anyOf":[{"$ref":"#/components/schemas/MonthTotals"},{"type":"object","nullable":true,"enum":[null]}]},"clubs_added":{"type":"array","items":{"type":"string"},"description":"Clubs here this month but not last month: chartered or moved in."},"clubs_removed":{"type":"array","items":{"type":"string"},"description":"Clubs here last month but not this month: moved out or no longer reported."},"parts":{"type":"array","items":{"$ref":"#/components/schemas/MonthChangePart"}}},"required":["fiscal_year","fiscal_month","previous_fiscal_month","current","previous","change","clubs_added","clubs_removed","parts"]},"ClubMonthFigures":{"type":"object","description":"A club's figures for one fiscal month.","properties":{"active_members":{"type":"integer"},"goals_met":{"type":"integer"},"educational_awards":{"type":"integer"},"new_members":{"type":"integer"},"club_status":{"type":"string","nullable":true},"distinguished_status":{"type":"string","enum":["D","S","P","M",null],"nullable":true},"division":{"type":"string","nullable":true},"area":{"type":"string","nullable":true}},"required":["active_members","goals_met","educational_awards","new_members","club_status","distinguished_status","division","area"]},"ClubMonthChange":{"type":"object","description":"A club's figures for the reported fiscal month against the month before.","properties":{"fiscal_year":{"type":"string","example":"2026-2027"},"fiscal_month":{"type":"integer","minimum":1,"maximum":12,"description":"Fiscal month (1 = July) of the figures."},"previous_fiscal_month":{"type":"integer","minimum":1,"maximum":11,"nullable":true,"description":"The fiscal month compared with; null in July, which starts the fiscal year."},"current":{"$ref":"#/components/schemas/ClubMonthFigures"},"previous":{"description":"Last month's figures; null in July or without a record last month.","anyOf":[{"$ref":"#/components/schemas/ClubMonthFigures"},{"type":"object","nullable":true,"enum":[null]}]},"change":{"type":"object","nullable":true,"description":"This month's figures minus last month's; null when previous is.","properties":{"active_members":{"type":"integer"},"goals_met":{"type":"integer"},"educational_awards":{"type":"integer"},"new_members":{"type":"integer"}},"required":["active_members","goals_met","educational_awards","new_members"]},"club_status_changed":{"type":"boolean"},"distinguished_status_changed":{"type":"boolean","description":"The club reached, lost or changed its Distinguished level."},"moved":{"type":"boolean","description":"The club moved to another division or area."}},"required":["fiscal_year","fiscal_month","previous_fiscal_month","current","previous","change","club_status_changed","distinguished_status_changed","moved"]},"DCPHistory":{"type":"object","properties":{"club_number":{"type":"string","description":"Club number"},"club_name":{"type":"string","description":"Club name"},"district":{"type":"string","description":"District number"},"area":{"type":"string","description":"Area"},"division":{"type":"string","description":"Division"},"fiscal_year":{"type":"string","description":"Fiscal year (e.g., \"24-25\")","pattern":"^[0-9]{2}-[0-9]{2}$"},"memb_base_7_1":{"type":"integer","description":"Membership count on July 1st (start of fiscal year)"},"year_end_memb":{"type":"integer","description":"Year-end membership count"},"traditional_goal_1":{"type":"integer","minimum":0,"description":"CC progress count; Goal 1 is achieved at 2"},"traditional_goal_2":{"type":"integer","minimum":0,"description":"Additional CC progress count; Goal 2 is achieved at 2"},"traditional_goal_3":{"type":"integer","minimum":0,"description":"AC progress count; Goal 3 is achieved at 1"},"traditional_goal_4":{"type":"integer","minimum":0,"description":"Additional AC progress count; Goal 4 is achieved at 1"},"traditional_goal_5":{"type":"integer","minimum":0,"description":"CL/AL/DTM progress count; Goal 5 is achieved at 1"},"traditional_goal_6":{"type":"integer","minimum":0,"description":"Additional CL/AL/DTM progress count; Goal 6 is achieved at 1"},"pathways_goal_1":{"type":"integer","minimum":0,"description":"Level 1 progress count; Goal 1 is achieved at 4"},"pathways_goal_2":{"type":"integer","minimum":0,"description":"Level 2 progress count; Goal 2 is achieved at 2"},"pathways_goal_3":{"type":"integer","minimum":0,"description":"Additional Level 2 progress count; Goal 3 is achieved at 2"},"pathways_goal_4":{"type":"integer","minimum":0,"description":"Level 3 progress count; Goal 4 is achieved at 2"},"pathways_goal_5":{"type":"integer","minimum":0,"description":"Level 4/path completion/DTM progress count; Goal 5 is achieved at 1"},"pathways_goal_6":{"type":"integer","minimum":0,"description":"Additional Level 4/path completion/DTM progress count; Goal 6 is achieved at 1"},"goal_7_new_members":{"type":"integer","minimum":0,"maximum":4,"description":"Goal 7 new-member progress count, capped at 4"},"goal_8_add_new_members":{"type":"integer","minimum":0,"description":"Goal 8 uncapped overflow count; starts only after Goal 7 reaches 4 and is achieved at 4"},"goal_9_jun_aug_training":{"type":"integer","minimum":0,"description":"June-August trained-officer count; one half of Goal 9"},"goal_9_dec_feb_training":{"type":"integer","minimum":0,"description":"December-February trained-officer count; one half of Goal 9"},"goal_10_renewals":{"type":"integer","description":"Goal 10: Membership renewals achievement (0 or 1)"},"goal_10_officer_lists":{"type":"integer","description":"Goal 10: Officer list submission achievement (0 or 1)"},"total_goals":{"type":"integer","description":"Total goals achieved (out of 20)","minimum":0,"maximum":20},"retention_rate":{"type":"number","description":"Membership retention rate (percentage)","minimum":0,"maximum":100},"award":{"type":"string","description":"Award received (Distinguished, Select Distinguished, President's Distinguished, or \"-\" for no award)"},"scraped_date":{"type":"string","format":"date","description":"Date when data was recorded"},"data_source":{"type":"string","description":"Source of the data (typically \"mikeraffety.com\")"}}},"HypotheticalAreaRequest":{"type":"object","required":["club_numbers"],"additionalProperties":false,"properties":{"club_numbers":{"type":"array","minItems":1,"maxItems":50,"items":{"type":"string","pattern":"^[A-Za-z0-9-]+$"},"description":"Club numbers; leading zeros are ignored and repeats are dropped."}}},"HypotheticalDivisionRequest":{"type":"object","required":["areas"],"additionalProperties":false,"properties":{"areas":{"type":"array","minItems":1,"maxItems":20,"description":"The new areas; a club listed in two areas stays in the first.","items":{"type":"object","required":["area","club_numbers"],"additionalProperties":false,"properties":{"area":{"type":"string","maxLength":10},"club_numbers":{"type":"array","minItems":1,"maxItems":50,"items":{"type":"string","pattern":"^[A-Za-z0-9-]+$"},"description":"Club numbers; leading zeros are ignored and repeats are dropped."}}}}}},"HypotheticalClub":{"type":"object","description":"A club's current numbers from its dashboard, flattened for the tools.","properties":{"club_number":{"type":"string"},"club_name":{"type":"string"},"district":{"type":"string"},"division":{"type":"string"},"area":{"type":"string","description":"The club's current area."},"assigned_area":{"type":"string","description":"Hypothetical division only: the new area the club was assigned to."},"club_status":{"type":"string"},"suspended":{"type":"boolean","description":"Suspended clubs are listed but left out of every total."},"charter_date":{"type":"string","nullable":true},"active_members":{"type":"integer"},"member_base":{"type":"integer"},"goals_met":{"type":"integer"},"educational_awards":{"type":"integer"},"educational_ratio":{"type":"number","nullable":true},"officers_trained_round_1":{"type":"integer"},"officers_trained_round_2":{"type":"integer"},"october_renewals":{"type":"boolean"},"april_renewals":{"type":"boolean"},"nov_visit":{"type":"boolean"},"may_visit":{"type":"boolean"},"coaches":{"type":"integer"},"distinguished_status":{"type":"string","enum":["D","S","P","M",null],"nullable":true},"member_payments":{"type":"object","properties":{"late":{"type":"integer"},"oct_ren":{"type":"integer"},"apr_ren":{"type":"integer"},"total_ren":{"type":"integer"},"new":{"type":"integer"},"charter":{"type":"integer"},"total_new":{"type":"integer"}},"required":["late","oct_ren","apr_ren","total_ren","new","charter","total_new"]},"latitude":{"type":"number","nullable":true},"longitude":{"type":"number","nullable":true},"location":{"type":"string","nullable":true},"address":{"type":"string","nullable":true},"feedback":{"type":"object","description":"What the club still needs as of the report date.","properties":{"needs_attention":{"type":"boolean","description":"Fewer than 20 members or fewer than 5 goals."},"members_needed":{"type":"integer","description":"Members still needed to reach 20."},"needs_coach":{"type":"boolean","description":"Fewer than 10 members and no coach assigned."},"officers_round_1_needed":{"type":"boolean"},"officers_round_2_needed":{"type":"boolean"},"nov_visit_needed":{"type":"boolean"},"may_visit_needed":{"type":"boolean"}},"required":["needs_attention","members_needed","needs_coach","officers_round_1_needed","officers_round_2_needed","nov_visit_needed","may_visit_needed"]}},"required":["club_number","club_name","district","division","area","club_status","suspended","charter_date","active_members","member_base","goals_met","educational_awards","educational_ratio","officers_trained_round_1","officers_trained_round_2","october_renewals","april_renewals","nov_visit","may_visit","coaches","distinguished_status","member_payments","latitude","longitude","location","address","feedback"]},"HypotheticalArea":{"type":"object","properties":{"as_of":{"type":"string","format":"date","description":"The newest of the clubs' report dates."},"month":{"type":"string"},"month_target":{"type":"integer","description":"Goals a club should have met by this month."},"clubs":{"type":"array","items":{"$ref":"#/components/schemas/HypotheticalClub"}},"current_areas":{"type":"array","description":"Where the counted clubs are today, largest group first.","items":{"type":"object","properties":{"district":{"type":"string"},"division":{"type":"string"},"area":{"type":"string"},"clubs":{"type":"integer"}},"required":["district","division","area","clubs"]}},"summary":{"type":"object","properties":{"paid_clubs":{"type":"integer","description":"Clubs that aren't suspended."},"total_members":{"type":"integer"},"member_base":{"type":"integer"},"distinguished_clubs":{"type":"integer"},"twenty_plus_member_clubs":{"type":"integer"},"on_track_clubs":{"type":"integer","description":"Clubs with 20+ members and at least this month's target of goals."},"average_goals":{"type":"number"},"member_payments":{"type":"object","properties":{"late":{"type":"integer"},"oct_ren":{"type":"integer"},"apr_ren":{"type":"integer"},"total_ren":{"type":"integer"},"new":{"type":"integer"},"charter":{"type":"integer"},"total_new":{"type":"integer"}},"required":["late","oct_ren","apr_ren","total_ren","new","charter","total_new"]},"distinguished_pct":{"type":"number"},"twenty_plus_member_pct":{"type":"number"},"educational_awards":{"type":"integer"},"educational_ratio":{"type":"number","nullable":true},"visits":{"type":"object","properties":{"goal":{"type":"integer","description":"Clubs to visit in each round: 75% of paid clubs."},"nov":{"type":"object","properties":{"visited":{"type":"integer"},"pct":{"type":"integer"}},"required":["visited","pct"]},"may":{"type":"object","properties":{"visited":{"type":"integer"},"pct":{"type":"integer"}},"required":["visited","pct"]}},"required":["goal","nov","may"]},"distinguished_status":{"type":"string","enum":["D","S","P",null],"nullable":true,"description":"Derived with the standard goals once both visit rounds are met."}},"required":["paid_clubs","total_members","member_base","distinguished_clubs","twenty_plus_member_clubs","on_track_clubs","average_goals","member_payments","distinguished_pct","twenty_plus_member_pct","educational_awards","educational_ratio","visits","distinguished_status"]},"recognition_goals":{"type":"object","description":"The standard recognition goals: paid clubs and Distinguished clubs for each level.","properties":{"distinguished":{"type":"object","properties":{"paid_clubs":{"type":"integer"},"distinguished_clubs":{"type":"integer"}},"required":["paid_clubs","distinguished_clubs"]},"select_distinguished":{"type":"object","properties":{"paid_clubs":{"type":"integer"},"distinguished_clubs":{"type":"integer"}},"required":["paid_clubs","distinguished_clubs"]},"presidents_distinguished":{"type":"object","properties":{"paid_clubs":{"type":"integer"},"distinguished_clubs":{"type":"integer"}},"required":["paid_clubs","distinguished_clubs"]}},"required":["distinguished","select_distinguished","presidents_distinguished"]},"not_found":{"type":"array","items":{"type":"string"},"description":"Club numbers that weren't found."}},"required":["as_of","month","month_target","clubs","current_areas","summary","recognition_goals","not_found"]},"HypotheticalDivision":{"type":"object","properties":{"as_of":{"type":"string","format":"date","description":"The newest of the clubs' report dates."},"month":{"type":"string"},"month_target":{"type":"integer","description":"Goals a club should have met by this month."},"clubs":{"type":"array","items":{"$ref":"#/components/schemas/HypotheticalClub"}},"areas":{"type":"array","items":{"type":"object","properties":{"area":{"type":"string"},"paid_clubs":{"type":"integer"},"total_members":{"type":"integer"},"distinguished_clubs":{"type":"integer"},"twenty_plus_member_clubs":{"type":"integer"},"five_plus_goal_clubs":{"type":"integer"},"officers_round_1_clubs":{"type":"integer","description":"Clubs with 4+ officers trained in round 1."},"officers_round_2_clubs":{"type":"integer"},"average_goals":{"type":"number"}},"required":["area","paid_clubs","total_members","distinguished_clubs","twenty_plus_member_clubs","five_plus_goal_clubs","officers_round_1_clubs","officers_round_2_clubs","average_goals"]}},"summary":{"type":"object","properties":{"paid_clubs":{"type":"integer","description":"Clubs that aren't suspended."},"total_members":{"type":"integer"},"member_base":{"type":"integer"},"distinguished_clubs":{"type":"integer"},"twenty_plus_member_clubs":{"type":"integer"},"on_track_clubs":{"type":"integer","description":"Clubs with 20+ members and at least this month's target of goals."},"average_goals":{"type":"number"},"member_payments":{"type":"object","properties":{"late":{"type":"integer"},"oct_ren":{"type":"integer"},"apr_ren":{"type":"integer"},"total_ren":{"type":"integer"},"new":{"type":"integer"},"charter":{"type":"integer"},"total_new":{"type":"integer"}},"required":["late","oct_ren","apr_ren","total_ren","new","charter","total_new"]}},"required":["paid_clubs","total_members","member_base","distinguished_clubs","twenty_plus_member_clubs","on_track_clubs","average_goals","member_payments"]},"recognition_goals":{"type":"object","description":"The standard recognition goals: paid clubs and Distinguished clubs for each level.","properties":{"distinguished":{"type":"object","properties":{"paid_clubs":{"type":"integer"},"distinguished_clubs":{"type":"integer"}},"required":["paid_clubs","distinguished_clubs"]},"select_distinguished":{"type":"object","properties":{"paid_clubs":{"type":"integer"},"distinguished_clubs":{"type":"integer"}},"required":["paid_clubs","distinguished_clubs"]},"presidents_distinguished":{"type":"object","properties":{"paid_clubs":{"type":"integer"},"distinguished_clubs":{"type":"integer"}},"required":["paid_clubs","distinguished_clubs"]}},"required":["distinguished","select_distinguished","presidents_distinguished"]},"not_found":{"type":"array","items":{"type":"string"}}},"required":["as_of","month","month_target","clubs","areas","summary","recognition_goals","not_found"]},"YearTotals":{"type":"object","description":"A district's or division's totals over its clubs for one fiscal month. Suspended clubs count only as suspended.","properties":{"clubs":{"type":"integer","description":"Clubs that aren't suspended."},"suspended_clubs":{"type":"integer"},"paid_clubs":{"type":"integer","description":"Clubs that aren't suspended with an October or April renewal on record."},"distinguished_clubs":{"type":"integer"},"member_base":{"type":"integer","description":"Membership base, summed over the clubs."},"active_members":{"type":"integer"},"net_growth":{"type":"integer","description":"active_members minus member_base."},"clubs_under_8_members":{"type":"integer","description":"Clubs below the 8 members needed for good standing."},"clubs_at_or_above_base":{"type":"integer","description":"Clubs with at least max(base, 8) members."},"goals_met":{"type":"integer","description":"DCP goals met, summed over the clubs."},"clubs_with_no_goals":{"type":"integer"},"clubs_with_5_plus_goals":{"type":"integer"},"level_1s":{"type":"integer"},"level_2s":{"type":"integer","description":"Level 2s plus additional Level 2s."},"level_3s":{"type":"integer"},"level_4s":{"type":"integer","description":"Level 4s, path completions and DTMs, plus additional ones."},"educational_awards":{"type":"integer"},"new_members":{"type":"integer","description":"New and additional new members counted for the DCP."},"clubs_with_4_officers_trained_round_1":{"type":"integer"},"csp_submitted":{"type":"integer","description":"Clubs that submitted a Club Success Plan."}},"required":["clubs","suspended_clubs","paid_clubs","distinguished_clubs","member_base","active_members","net_growth","clubs_under_8_members","clubs_at_or_above_base","goals_met","clubs_with_no_goals","clubs_with_5_plus_goals","level_1s","level_2s","level_3s","level_4s","educational_awards","new_members","clubs_with_4_officers_trained_round_1","csp_submitted"]},"DistrictYearFigures":{"type":"object","description":"The district summary figures for one fiscal month.","properties":{"paid_clubs":{"type":"integer"},"paid_club_base":{"type":"integer"},"active_clubs":{"type":"integer"},"payments_to_date":{"type":"integer"},"payment_base":{"type":"integer"},"october_payments":{"type":"integer"},"april_payments":{"type":"integer"},"new_payments":{"type":"integer"},"late_payments":{"type":"integer"},"charter_payments":{"type":"integer"},"distinguished_clubs":{"type":"integer"}},"required":["paid_clubs","paid_club_base","active_clubs","payments_to_date","payment_base","october_payments","april_payments","new_payments","late_payments","charter_payments","distinguished_clubs"]},"DistrictYearSummaryComparison":{"type":"object","properties":{"current":{"$ref":"#/components/schemas/DistrictYearFigures"},"previous":{"description":"The same month last year; null when no district summary was reported then.","anyOf":[{"$ref":"#/components/schemas/DistrictYearFigures"},{"type":"object","nullable":true,"enum":[null]}]},"change":{"description":"This year's figures minus last year's; null when previous is.","anyOf":[{"$ref":"#/components/schemas/DistrictYearFigures"},{"type":"object","nullable":true,"enum":[null]}]}},"required":["current","previous","change"]},"YearTotalsComparison":{"type":"object","properties":{"current":{"$ref":"#/components/schemas/YearTotals"},"previous":{"description":"The same month last year; null when no club was reported then.","anyOf":[{"$ref":"#/components/schemas/YearTotals"},{"type":"object","nullable":true,"enum":[null]}]},"change":{"description":"This year's figures minus last year's; null when previous is.","anyOf":[{"$ref":"#/components/schemas/YearTotals"},{"type":"object","nullable":true,"enum":[null]}]}},"required":["current","previous","change"]},"DivisionYearComparison":{"type":"object","description":"One division's totals in both years. A club that moved counts in its division for each year.","properties":{"key":{"type":"string","description":"Division letter."},"current":{"$ref":"#/components/schemas/YearTotals"},"previous":{"description":"The same month last year; null when no club was reported then.","anyOf":[{"$ref":"#/components/schemas/YearTotals"},{"type":"object","nullable":true,"enum":[null]}]},"change":{"description":"This year's figures minus last year's; null when previous is.","anyOf":[{"$ref":"#/components/schemas/YearTotals"},{"type":"object","nullable":true,"enum":[null]}]}},"required":["key","current","previous","change"]},"ClubYearComparison":{"type":"object","description":"A club's figures in both years; a side is null when the club wasn't reported that month.","properties":{"club_number":{"type":"string","description":"Canonical club number, without leading zeros."},"club_name":{"type":"string","nullable":true},"current":{"type":"object","description":"A club's figures for the month in one year.","properties":{"division":{"type":"string","nullable":true},"area":{"type":"string","nullable":true},"club_status":{"type":"string","nullable":true},"member_base":{"type":"integer"},"active_members":{"type":"integer"},"goals_met":{"type":"integer"},"educational_awards":{"type":"integer"}},"nullable":true,"required":["division","area","club_status","member_base","active_members","goals_met","educational_awards"]},"previous":{"type":"object","description":"A club's figures for the month in one year.","properties":{"division":{"type":"string","nullable":true},"area":{"type":"string","nullable":true},"club_status":{"type":"string","nullable":true},"member_base":{"type":"integer"},"active_members":{"type":"integer"},"goals_met":{"type":"integer"},"educational_awards":{"type":"integer"}},"nullable":true,"required":["division","area","club_status","member_base","active_members","goals_met","educational_awards"]}},"required":["club_number","club_name","current","previous"]},"DistrictYearComparison":{"type":"object","description":"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.","properties":{"district":{"type":"string","example":"74"},"fiscal_year":{"type":"string","example":"2026-2027"},"fiscal_month":{"type":"integer","minimum":1,"maximum":12,"description":"Fiscal month (1 = July)."},"previous_fiscal_year":{"type":"string","example":"2025-2026"},"report_date":{"type":"string","nullable":true,"format":"date","description":"The report day this year's figures reflect."},"previous_report_date":{"type":"string","nullable":true,"format":"date","description":"The report day last year's figures reflect; null when no clubs were reported then."},"summary":{"description":"District summary figures; null without a district summary this month.","anyOf":[{"$ref":"#/components/schemas/DistrictYearSummaryComparison"},{"type":"object","nullable":true,"enum":[null]}]},"clubs":{"$ref":"#/components/schemas/YearTotalsComparison"},"divisions":{"type":"array","items":{"$ref":"#/components/schemas/DivisionYearComparison"}},"club_list":{"type":"array","items":{"$ref":"#/components/schemas/ClubYearComparison"},"description":"Every club reported in either year."}},"required":["district","fiscal_year","fiscal_month","previous_fiscal_year","report_date","previous_report_date","summary","clubs","divisions","club_list"]},"DistrictYearComparisonResponse":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"$ref":"#/components/schemas/DistrictYearComparison"},"timestamp":{"type":"string","format":"date-time"}},"required":["success","data","timestamp"]}},"parameters":{"District":{"name":"district","in":"query","description":"District to filter by: a district number, U (undistricted) or F (Founders)","required":false,"schema":{"type":"string"}},"FiscalYear":{"name":"fiscalYear","in":"query","description":"Fiscal year (YYYY-YYYY); defaults to the current fiscal year","required":false,"schema":{"type":"string","pattern":"^[0-9]{4}-[0-9]{4}$"}},"FiscalMonth":{"name":"fiscalMonth","in":"query","description":"Fiscal month (1 = July, 12 = June)","required":false,"schema":{"type":"integer","minimum":1,"maximum":12}},"Latest":{"name":"latest","in":"query","description":"true skips the cached response and sends Cache-Control: no-store","required":false,"schema":{"type":"string","enum":["true","false"]}},"StartDate":{"name":"startDate","in":"query","description":"First report date to include (YYYY-MM-DD)","required":false,"schema":{"type":"string","format":"date"}},"EndDate":{"name":"endDate","in":"query","description":"Last report date to include (YYYY-MM-DD); on or after startDate","required":false,"schema":{"type":"string","format":"date"}},"Date":{"name":"date","in":"query","description":"Specific date to filter by (YYYY-MM-DD)","required":false,"schema":{"type":"string","format":"date"}},"Limit":{"name":"limit","in":"query","description":"Maximum number of records to return","required":false,"schema":{"type":"integer","minimum":1,"maximum":1000,"default":1000}},"Offset":{"name":"offset","in":"query","description":"Number of records to skip","required":false,"schema":{"type":"integer","minimum":0,"default":0}}},"securitySchemes":{"HealthDiagnosticsToken":{"type":"apiKey","in":"header","name":"X-Health-Diagnostics-Token","description":"Production detailed-health token. Configure the server with HEALTH_DIAGNOSTICS_TOKEN."}}}}