Team Rankings

Team Rankings are organization-level leaderboards that aggregate team performance across multiple competitions — unlike a single competition's standings table, which only ranks teams within one league or cup. A federation can use a ranking to crown a "club of the year", a recreational league can publish a multi-season power table, or a regional body can rank affiliated clubs across dozens of child competitions.

Overview & Plan Tier

A ranking is configured at the organization level (see Organization Profile). The organizer picks a ranking model, chooses which competitions feed into it, sets per-competition weights, and publishes. Every time a match result is confirmed anywhere inside a contributing competition, the ranking engine updates the affected teams and recomputes positions.

Key vocabulary

Lifecycle — create, disable, never delete

Once created, a ranking system stays attached to its organization permanently. There is no delete endpoint; the only way to take a ranking out of public circulation is to disable it by setting enabled: false on the ranking system — the table stops being computed and the public reads return nothing, but the configured rules, scoring, and event history remain in place. A disabled ranking can be re-enabled later without losing its history, and an organizer can keep editing all the same dials (scoring rules, competition values, org coefficients) while it is disabled.

The full set of organizer-side actions exposed by the API:

• Create — pick a template (local, regional, national, international) and the ranking is provisioned with that template's defaults. Fails with a conflict if one already exists.
• Update — edit any top-level setting (model type, visibility, season scope, rolling window, decay, tiebreakers); the same endpoint is used to disable the ranking by passing enabled: false.
• Edit scoring rules, edit competition values, edit org values — each is its own endpoint.
• Manual event — an organizer can add a one-off ranking event (a bonus, a sanction).
• Preview → publish or discard — the staged workflow that lets the organizer see the new table before it goes live.
• Recalc — rebuild every event's finalPoints from the current rules; safe to run anytime.

Ranking Models

A ranking is configured along two independent dimensions: its model type (how points are aggregated) and its season scope (which events are considered). Organizers pick both when creating the ranking and can switch later via the preview flow.

Standard

Best for: recreational leagues, single-competition power tables, social leagues with no tiering.

Awards flat base points for each match result and sums them across contributing competitions. No per-competition weight is applied — a win is a win regardless of which competition it happened in. Competition weight and affiliate coefficient sliders are ignored by this model.

Weighted

Best for: federations with tiered competitions (Div 1 / Div 2 / Cup), regional bodies aggregating results across affiliated clubs.

Same as Standard plus two multipliers — the competition weight and the affiliate coefficient. The final points for each event equal the base points multiplied by the competition weight and then by the affiliate coefficient.

This lets a federation say "a win in Division 1 is worth 1.5x a win in Division 3", or "matches played by the youth academy branch count at 0.5x for the senior club-of-the-year table".

Rolling

Best for: seasonal-form tables, "who's hot right now" rankings, federations that want positions to reflect recent form rather than a team's all-time total.

A first-class model type focused on a time window: only events from the last 6 months, 12 months, or 24 months count (or the last two completed seasons). An optional time decay can also be enabled — events older than today are exponentially down-weighted, so a win three months ago is worth less than a win last week, but still more than one a year ago.

Competition weight and affiliate coefficient sliders are still available but most Rolling deployments leave them at 1.0 — the whole point of this model is that recency, not tiering, drives the position.

Competition Value (Weight)

Each contributing competition has a weight — a multiplier that scales every ranking event originating in that competition. It is the main knob an organizer turns to encode "this competition is more prestigious than that one".

Alongside the weight, the same row exposes:

• Contributes to ranking — toggle to include or exclude a competition entirely. Toggling off keeps the competition's own standings table intact; it just stops feeding the ranking.
• Participation points — a flat number of points a team receives for merely taking part in the competition (useful for cup-style formats where not every team plays every matchday).

Are weight changes retroactive?

Yes. When the organizer publishes a new weight, the ranking engine recomputes every historical event from that competition using the new multiplier. A team that was sitting 3rd yesterday with Division 1 at weight 1.2 may be 2nd tomorrow if the organizer publishes a change to 1.5. This is by design — the ranking always reflects the current ruleset applied to the full history.

Affiliated-Organization Coefficient

Larger federations run child organizations (regional bodies, affiliated clubs, academies). The affiliate coefficient is a multiplier attached to a child organization, not to a specific competition. It propagates automatically to every competition that child organization runs — past, present, and future.

A disabled affiliate entry is greyed out — its coefficient is not consulted, and teams whose home org matches it are treated as if the coefficient were 1.0.

Weight vs coefficient — how to choose

• Use a competition weight when the distinction is between competitions (Division 1 vs Division 3, senior vs U19).
• Use an affiliate coefficient when the distinction is between organizations (Northern federation vs Southern federation, main club vs academy branch).
• Both multiply together. A team playing in Division 1 (weight 1.5) under the Northern federation (coefficient 1.2) earns 1.8x points per event (base points × 1.5 × 1.2).

How Points Are Computed

For each event the engine emits, it stores three multiplier inputs and a derived finalPoints:

The stored value is finalPoints = basePoints × competitionWeight × organizationCoefficient. A team's total is the sum of finalPoints across every non-voided event that falls inside the season scope — the breakdown modal shows the same per-competition totals the engine sees.

Read-time overlays (not baked into finalPoints)

Two settings affect the table but are not stored on each event — they are applied when the ranking is read:

• Time decay (Rolling model with decayEnabled: true): older events are exponentially down-weighted by decayRatePerDay. Because the multiplier depends on "today", the API recomputes the table on every read for this combination rather than summing the stored finalPoints.
• previousSeasonPartialPercent (only valid when season scope is current-plus-previous): an integer 0–100 that scales every previous-season event at read time. A value of 50 means a team's previous season contributes at half weight; 0 ignores it entirely.

Everything else — basePoints, competition weight, organization coefficient — is rewritten onto every affected event when the organizer publishes a change. That is what makes weight edits truly retroactive: the same formula has already been re-applied to every historical event by the time the new table appears.

Season scope — which events feed the table

Independent of the model type, the ranking has a season scope that filters which events the engine considers. An event whose date falls outside the scope is ignored on read; nothing is deleted — if the organizer later widens the scope, the older events appear again automatically.

Tiebreakers — how equal finalPoints totals are resolved

When two teams have the same finalPoints total, the engine walks an ordered list of tiebreakers chosen on the ranking template. The current options are:

The default order is template-specific — the local/regional preset starts with headToHead, then goalDifference; the national/international preset prioritizes headToHead then goalDifference then totalWins. Organizers can re-order or remove entries from this list on the ranking system settings.

Who Can Create / Edit / Delete

Endpoints fall into two families, and they are gated very differently.

Public reads

The ranking table, a team's breakdown, and a team's history are exposed as public reads with no auth gating — fans, players, team managers and referees all consume the same endpoints. The ranking's visibility setting (public, private, or members) then filters what callers actually see; a private ranking is not surfaced outside the organization.

Admin writes

Every mutation (create, update, scoring rules, competition values, org values, manual event, preview, publish, discard, recalc) requires organization-admin rights on the specific organization. That maps to the organizer role plus an admin grant on that org — a referee or a team manager from a contributing competition does not have access to these endpoints. Creating or editing a ranking is additionally gated by the PRO Plan check noted above.

Deleting a ranking

There is no delete endpoint. To take a ranking out of public circulation, an organization admin issues the standard update endpoint with enabled: false; the table stops being computed and the public reads return nothing, but the configured rules, scoring, and event history are preserved and the ranking can be re-enabled later without losing any data. See Lifecycle — create, disable, never delete for the full set of mutations and the staged preview/publish flow.

Team Breakdown Modal

Tapping a team's row on the ranking table opens the breakdown modal — the most useful view when you want to understand why a team is where it is.

Common Questions

Three situations come up most often. In each case, start by opening the breakdown modal: it shows exactly what the ranking is using, and most questions answer themselves once you can see the per-competition contribution.

1. A team thinks their ranking position is wrong

2. You want to change weights mid-season

3. A new child competition isn't being counted