topmatches Method — Top Matches

Purpose

The topmatches method returns a ready-made selection of top matches across all sports available to the client’s API key.

It is useful for a separate “Top Matches” section on a home page. The request does not require a previously retrieved sportId, countryId, or tournamentId.

SportAPI determines the contents and order of the selection. One response contains up to 10 matches. Request parameters cannot change the selection criteria.

Live and Prematch use separate selections.

This is an optional method. It does not replace the core menu → events → event integration flow.

Request

GET https://YOUR_API_DOMAIN/v1/topmatches/{type}/{lang}

Send the API key in the HTTP header:

Package: YOUR_API_KEY

Path Parameters

Values of type:

The full Parameter

full is an optional query parameter that controls the amount of match data returned.

Example URL with extended objects:

GET https://YOUR_API_DOMAIN/v1/topmatches/live/en?full=true

Important: full=true returns the complete set of summary fields, but not the full list of all match odds. game_oc_list still contains a short set of main markets and best odds, similar to events. To retrieve all available markets and selections, call event using game_id.

Live Request Examples

Short summaries:

curl --request GET \
  --url 'https://YOUR_API_DOMAIN/v1/topmatches/live/en' \
  --header 'Package: YOUR_API_KEY'

Extended objects:

curl --request GET \
  --url 'https://YOUR_API_DOMAIN/v1/topmatches/live/en?full=true' \
  --header 'Package: YOUR_API_KEY'

Prematch Request Examples

Short summaries:

curl --request GET \
  --url 'https://YOUR_API_DOMAIN/v1/topmatches/line/en' \
  --header 'Package: YOUR_API_KEY'

Extended objects:

curl --request GET \
  --url 'https://YOUR_API_DOMAIN/v1/topmatches/line/en?full=true' \
  --header 'Package: YOUR_API_KEY'

Shortened Response Example

The following is one summary from a real English Live response without full=true:

{
  "status": 1,
  "page": "/v1/topmathes",
  "body": [
    {
      "sgame_id": "0",
      "stat_id": "0",
      "game_id": 746267958,
      "game_mid": 746267958,
      "game_start": 1787382000,
      "tournament_name": "Mobile Legends. MPL Indonesia",
      "opp_1_name": "Team Liquid ID",
      "opp_2_name": "Evos",
      "opp_1_icon": "2b86bbc5fe28202aaddb53e2fe651a46.png",
      "opp_2_icon": "459077.png",
      "sport_id": 40,
      "sport_name": "Esports",
      "score_full": "1:0",
      "period_name": "2 map",
      "timer": 0,
      "va": 1,
      "vi": "20072803",
      "zp": null
    }
  ]
}

These values come from a sports line snapshot and will change over time.

Top-level Response Fields

The current page value is /v1/topmathes, without the letter c. This is the actual value returned by the API. The request URL itself is spelled correctly as /v1/topmatches/.... Do not use page to construct the next URL.

Short Summary Fields

Response with full=true

With full=true, body remains a flat match array, but each item contains an extended object similar to a match object from events:

• country ID and name;
• tournament ID and name;
• team or participant IDs;
• score and period;
• a short list of markets and odds in game_oc_list;
• video and Live 3D Tracker availability;
• additional match object fields.

In topmatches?full=true, game_oc_list has the same structure as in events: a market’s oc_list is a regular selection array. The event method with the group format uses a different structure, where oc_list contains nested column arrays.

In the saved topmatches?full=true responses, sub_games and event_plan are empty arrays. To retrieve available submatches or the component matches of a complex event, request the specific match through event.

All extended object fields are documented in the Sport Line API Field Reference.

Icons

Build the sport icon URL from sport_id:

https://cdn.sportapi.net/sports/v1/color/{sport_id}.webp

With full=true, build the tournament icon URL from tournament_id:

https://cdn.sportapi.net/tournaments/v1/color/{tournament_id}.webp

For a team icon, remove the extension from opp_1_icon or opp_2_icon and insert the remaining name into the URL:

https://cdn.sportapi.net/opp/v1/color/{iconName}.webp

Subscription Restrictions

The method returns top matches only for sports available to the client’s API key. One response may contain matches from different sports.

To retrieve a regular match list for a specific sport or tournament, use events. For complete details of one match, use event.

Snapshot of Saved Responses

At the time of the requests, every Live and Prematch response contained 10 matches. These are dynamic data snapshots from August 22, 2026, not a permanent selection size.

Full unabridged responses:

Short Summaries

• Live, Russian
• Prematch, Russian
• Live, English
• Prematch, English

Extended Objects (full=true)

• Live, Russian
• Prematch, Russian
• Live, English
• Prematch, English

The files contain only API response bodies. No API key is stored in them.

Update Frequency

Recommended request frequency for topmatches:

• Live — no more than once every 30 seconds;
• Prematch (line) — no more than once every 120 seconds.

See Data Update Guidelines for more details.

Key, subscription, and parameter errors are documented in Error Handling.