week_2024/docs/leaderboard_api.md

Tomato Challenge — Leaderboard API

Provides the data for the intranet score banner: a ranked list of countries plus up to three rotating "badge" messages.

Endpoint

GET https://savethetomato.ikeafoundation.org/api/v1/leaderboard

Authentication

Send a Bearer token in the header:

Authorization: Bearer ikea-tomato-2026

Missing/wrong token returns 401 { "error": "Unauthorized" }.

Response

{
  "leaderboard": [
    { "country_code": "DK", "score": 100, "tomatoes": 5, "per_employee": 1.2 },
    { "country_code": "PL", "score": 63,  "tomatoes": 3, "per_employee": 0.9 }
  ],
  "badges": [
    { "type": "new_players",   "country_code": "FR", "message": "10 new players in France!" },
    { "type": "encouragement", "country_code": "SE", "message": "Ketch-up Sweden!" },
    { "type": "participation", "country_code": "CN", "message": "China, every tomato counts!" }
  ],
  "updated_at": "2026-07-03T12:00:00Z"
}

leaderboard

Always contains all countries, sorted best-to-worst by score.

• country_code — ISO 2-letter code, uppercase.
• score — blended 0–100 ranking score.
• tomatoes — total saved (whole number).
• per_employee — tomatoes per employee (decimal, may be null).

badges

Zero to three messages, at most one of each type. Render message as-is.

• new_players — a country just gained players.
• encouragement — nudge for a trailing country.
• participation — a country not yet on the board.

country_code is included if you want to show a flag alongside the message.

updated_at

ISO-8601 timestamp of the data.

Notes

• Response is cached for ~1 minute, so numbers/badges change about once a minute — safe to poll on that cadence.
• The field/structure is stable; exact scoring and badge wording may still be tuned. Don't hard-code specific messages.
• Data is currently simulated for development and will be reset before go-live.