toplist Method — Top Matches for a Selected Sport

Purpose

The toplist method returns a selection of top matches for one selected sport. For example, it can be used for a section featuring the main football matches.

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

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

Prematch Only

toplist works only with upcoming Prematch matches. This method has no type path parameter, and it cannot be used with live.

For Live top matches, use topmatches:

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

Before Making a Request

The request requires a sportId. Retrieve it through menu or sports.

The API key must provide access to the selected sport.

Request

GET https://YOUR_API_DOMAIN/v1/toplist/{sportId}/{lang}

Send the API key in the HTTP header:

Package: YOUR_API_KEY

Path Parameters

The full Parameter

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

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.

Request Examples

Short summaries for top football matches (sportId=1):

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

Extended objects:

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

Shortened Response Example

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

{
  "status": 1,
  "page": "/v1/toplist",
  "body": [
    {
      "sgame_id": "6a35079e5e99bd05c63e9104",
      "stat_id": "6a34c3a75e99bd05c63e703a",
      "game_id": 730328424,
      "game_mid": 730328424,
      "game_start": 1787398200,
      "tournament_name": "England. Premier League",
      "opp_1_name": "Hull City",
      "opp_2_name": "Manchester United",
      "opp_1_icon": "715c2f5d95d5a5a03bdb4d4e11bbd696.png",
      "opp_2_icon": "1996.png",
      "sport_id": 1,
      "sport_name": "Football",
      "score_full": "0:0",
      "period_name": "",
      "timer": 0,
      "va": null,
      "vi": null,
      "zp": null
    }
  ]
}

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

Top-level Response Fields

Matches are not grouped by country or tournament.

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;
• a short list of markets and odds in game_oc_list;
• additional match object fields.

In toplist?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 toplist?full=true responses, sub_games, event_plan, and stat_list are empty arrays. To retrieve detailed data, 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 country icon URL from country_id:

https://cdn.sportapi.net/flags/v1/color/{country_id}.webp

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

Difference from topmatches

To retrieve a regular list of all available matches for a selected sport or tournament, rather than only the top selection, use events.

Snapshot of Saved Responses

Football (sportId=1) was used for verification. At the time of the requests, both the short and extended responses contained 10 Prematch matches.

Full unabridged responses:

Short Summaries

• Russian
• English

Extended Objects (full=true)

• Russian
• English

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

Update Frequency

toplist contains Prematch matches only. The recommended request frequency is no more than once every 120 seconds.

See Data Update Guidelines for more details.

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