How-to use TOTW

Our Team of the Week (TOTW) engine automatically picks the top 11 performers of every round using Sportmonks’ proprietary Player Rating model. No editorial bias—just data‑driven, repeatable selection.

Quick Start

Action	API request
Get all available TOTWS	https://api.sportmonks.com/v3/football/team-of-the-week?api_token=YOURTOKEN
Get the TOTW for a specific round	https://api.sportmonks.com/v3/football/team-of-the-week/rounds/ROUND_ID?api_token=YOURTOKEN
Get the latest TOTW for a specific league	https://api.sportmonks.com/v3/football/team-of-the-week/leagues/LEAGUE_ID/latest?api_token=YOURTOKEN

All endpoints require your standard api_token query parameter.

---

Includes

Enrich your response by adding includes to your response with ?include=.

Include	Adds…
player	Player objects (id, name, nationality, height, etc.)
team	Team objects (id, name, logo, etc.)
round	Round metadata (name, start/end dates, fixtures, etc.)

Add includes to enrich the response. See the example of an API request, which includes three includes below:

# Example > latest Premier League TOTW with player & team objects.

"https://api.sportmonks.com/v3/football/team-of-the-week/leagues/271/latest?api_token=YOURTOKEN&include=player;team;round"

Combine multiple keys with semicolons: &include=player;team;round

---

Example response

https://api.sportmonks.com/v3/football/team-of-the-week?api_token=YOURTOKEN&include=team;round

"data": [

{

"id": 1,

"player_id": 455900,

"fixture_id": 18946393,

"round_id": 318161,

"team_id": 18644,

"rating": "7.45",

"formation_position": 2,

"formation": "4-3-3",

"team": {

"id": 18644,

"sport_id": 1,

"country_id": 44,

"venue_id": 6569,

"gender": "male",

"name": "Argentina",

"short_code": "ARG",

"image_path": "https://cdn.sportmonks.com/images/soccer/teams/20/18644.png",

"founded": 1893,

"type": "national",

"placeholder": false,

"last_played_at": "2025-03-26 00:00:00"

},

"round": {

"id": 318161,

"sport_id": 1,

"league_id": 726,

"season_id": 22305,

"stage_id": 77465895,

"name": "1",

"finished": true,

"is_current": false,

"starting_at": "2023-09-07",

"ending_at": "2023-09-09",

"games_in_current_week": false

---

Coverage & Limitations

• Round‑based competitions only. Knock‑out stages and playoff matches are not yet supported.

• Player ratings are updated once all fixtures in a round are finished; a TOTW becomes available immediately thereafter.

---

Error Handling

TOTW endpoints follow our standard error model. Common codes include:

Code	Meaning	Typical cause
401	Unauthorized	Missing/invalid api_token.
404	Not Found	Round or league not eligible for TOTW.
429	Rate Limit	Exceeded plan allowance.

---

Feedback & Bug Reporting

We 💚 feedback! Email [e-mail] with:

1. Full request URL including query string

2. The round or league ID affected

3. What you observed vs. what you expected

4. Any additional screenshots or logs

The more context you provide, the faster we can assist.

Early‑Bird Reward

Consistent beta testers who provide actionable feedback will receive a lifetime discount on the TOTW add‑on when it leaves beta.

---

Changelog

Date (UTC)	Version	Notes
2025‑05‑02	0.9.0‑beta	Initial public beta release.

---

Need something else? Ping us on Slack or email, and we’ll expand the docs.