How-to use TOTW - beta

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

All endpoints require your standard api_token query parameter.


Includes

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

Include

Add

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:

Latest Premier League TOTW with player & team objects

 https://api.sportmonks.com/v3/football/team-of-the-week/leagues/8/latest?api_token=YOURTOKEN&include=player;team;round
Response
{
  "data": [
    {
      "id": 11464,
      "player_id": 1371,
      "fixture_id": 19135026,
      "round_id": 339271,
      "team_id": 9,
      "rating": "8.12",
      "formation_position": 8,
      "formation": "4-3-3",
      "player": {
        "id": 1371,
        "sport_id": 1,
        "country_id": 556,
        "nationality_id": 556,
        "city_id": null,
        "position_id": 26,
        "detailed_position_id": null,
        "type_id": 26,
        "common_name": "K. De Bruyne",
        "firstname": "Kevin",
        "lastname": "De Bruyne",
        "name": "Kevin De Bruyne",
        "display_name": "Kevin De Bruyne",
        "image_path": "https://cdn.sportmonks.com/images/soccer/players/27/1371.png",
        "height": 181,
        "weight": 68,
        "date_of_birth": "1991-06-28",
        "gender": "male"
      },
      "team": {
        "id": 9,
        "sport_id": 1,
        "country_id": 462,
        "venue_id": 151,
        "gender": "male",
        "name": "Manchester City",
        "short_code": "MCI",
        "image_path": "https://cdn.sportmonks.com/images/soccer/teams/9/9.png",
        "founded": 1880,
        "type": "domestic",
        "placeholder": false,
        "last_played_at": "2025-05-17 15:30:00"
      },
      "round": {
        "id": 339271,
        "sport_id": 1,
        "league_id": 8,
        "season_id": 23614,
        "stage_id": 77471288,
        "name": "36",
        "finished": true,
        "is_current": false,
        "starting_at": "2025-05-10",
        "ending_at": "2025-05-11",
        "games_in_current_week": false
      }
    },
    {
      "id": 11467,
      "player_id": 1881,
      "fixture_id": 19135020,
      "round_id": 339271,
      "team_id": 11,
      "rating": "7.8",
      "formation_position": 11,
      "formation": "4-3-3",
      "player": {
        "id": 1881,
        "sport_id": 1,
        "country_id": 716,
        "nationality_id": 716,
        "city_id": 47715,
        "position_id": 27,
        "detailed_position_id": 152,
        "type_id": 27,
        "common_name": "A. Iwobi",
        "firstname": "Alex",
        "lastname": "Iwobi",
        "name": "Alex Iwobi",
        "display_name": "Alex Iwobi",
        "image_path": "https://cdn.sportmonks.com/images/soccer/players/25/1881.png",
        "height": 183,
        "weight": 75,
        "date_of_birth": "1996-05-03",
        "gender": "male"
      },
      "team": {
        "id": 11,
        "sport_id": 1,
        "country_id": 462,
        "venue_id": 485,
        "gender": "male",
        "name": "Fulham",
        "short_code": "FUL",
        "image_path": "https://cdn.sportmonks.com/images/soccer/teams/11/11.png",
        "founded": 1879,
        "type": "domestic",
        "placeholder": false,
        "last_played_at": "2025-05-18 14:00:00"
      },
      "round": {
        "id": 339271,
        "sport_id": 1,
        "league_id": 8,
        "season_id": 23614,
        "stage_id": 77471288,
        "name": "36",
        "finished": true,
        "is_current": false,
        "starting_at": "2025-05-10",
        "ending_at": "2025-05-11",
        "games_in_current_week": false
      }
    },
    {
      "id": 11469,
      "player_id": 5252,
      "fixture_id": 19135023,
      "round_id": 339271,
      "team_id": 1,
      "rating": "7.9",
      "formation_position": 5,
      "formation": "4-3-3",
      "player": {
        "id": 5252,
        "sport_id": 1,
        "country_id": 462,
        "nationality_id": 462,
        "city_id": 51663,
        "position_id": 25,
        "detailed_position_id": 154,
        "type_id": 25,
        "common_name": "A. Wan-Bissaka",
        "firstname": "Aaron",
        "lastname": "Wan-Bissaka",
        "name": "Aaron Wan-Bissaka",
        "display_name": "Aaron Wan-Bissaka",
        "image_path": "https://cdn.sportmonks.com/images/soccer/players/4/5252.png",
        "height": 183,
        "weight": 72,
        "date_of_birth": "1997-11-26",
        "gender": "male"
      },
      "team": {
        "id": 1,
        "sport_id": 1,
        "country_id": 462,
        "venue_id": 214,
        "gender": "male",
        "name": "West Ham United",
        "short_code": "WHU",
        "image_path": "https://cdn.sportmonks.com/images/soccer/teams/1/1.png",
        "founded": 1895,
        "type": "domestic",
        "placeholder": false,
        "last_played_at": "2025-05-18 13:15:00"
      },
      "round": {
        "id": 339271,
        "sport_id": 1,
        "league_id": 8,
        "season_id": 23614,
        "stage_id": 77471288,
        "name": "36",
        "finished": true,
        "is_current": false,
        "starting_at": "2025-05-10",
        "ending_at": "2025-05-11",
        "games_in_current_week": false
      }
    },
    ...
    // and more
  ]
}

Coverage & Limitations

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

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

  • Check the league coverage here


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 [email protected] 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.


Changelog

Date (UTC)

Version

Notes

2025‑05‑02

0.9.0‑beta

Initial public beta release.

Last updated

Was this helpful?