---
id: api-toplist
title: toplist Method — Top Matches for a Selected Sport
description: Reference for the TOPLIST method, which returns popular matches for a selected sport.
version: v1
language: en
---

# `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`](topmatches.md):

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

## Before Making a Request

The request requires a `sportId`. Retrieve it through [`menu`](../menu.md) or
[`sports`](sports.md).

The API key must provide access to the selected sport.

## Request

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

Send the API key in the HTTP header:

```http
Package: YOUR_API_KEY
```

## Path Parameters

| Parameter | Type | Required | Description |
|---|---|---:|---|
| `sportId` | number | yes | Sport ID retrieved from `menu` or `sports` |
| `lang` | string | yes | Language of names. It must be supported by the API and included in the client's subscription |

## The `full` Parameter

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

| Value | Result |
|---|---|
| parameter omitted or `full=false` | Short match summary without odds, country ID, or tournament ID |
| `full=true` | Extended match object with teams, country, tournament, and a short odds list |

**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`](../events.md). To retrieve all available markets and
selections, call [`event`](../event.md) using `game_id`.

## Request Examples

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

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

Extended objects:

```bash
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`:

```json
{
  "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

| Field | Type | Description |
|---|---|---|
| `status` | number | Request status. A successful response returns `1` |
| `page` | string | Method name. This request returns `/v1/toplist` |
| `body` | array | Flat array of top matches for the selected sport |

Matches are not grouped by country or tournament.

## Short Summary Fields

| Field | Type | Description |
|---|---|---|
| `sgame_id` | string | Reserved test field. It is not currently used by the API |
| `stat_id` | string | Reserved test field. It is not currently used by the API |
| `game_id` | number | Match ID for requesting the detailed `event` method |
| `game_mid` | number or `null` | Main match ID |
| `game_start` | number | Start time as a Unix timestamp in seconds |
| `tournament_name` | string | Tournament name in the selected language |
| `opp_1_name` | string | First team or participant |
| `opp_2_name` | string | Second team or participant |
| `opp_1_icon` | string | Icon file name for the first team or participant |
| `opp_2_icon` | string | Icon file name for the second team or participant |
| `sport_id` | number | Sport ID |
| `sport_name` | string | Sport name in the selected language |
| `score_full` | string | Prematch usually returns `0:0` |
| `period_name` | string | Prematch returns an empty string |
| `timer` | number | Timer in seconds. Prematch usually returns `0` |
| `va` | number or `null` | Prematch usually returns `null` |
| `vi` | string or `null` | Prematch usually returns `null` |
| `zp` | number or `null` | Prematch usually returns `null` |

## 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](../../data-models/field-reference.md).

## Icons

Build the sport icon URL from `sport_id`:

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

With `full=true`, build the country icon URL from `country_id`:

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

Build the tournament icon URL from `tournament_id`:

```text
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:

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

## Difference from `topmatches`

| Method | Sport selection | Live | Prematch |
|---|---|---:|---:|
| `topmatches` | All available sports | yes | yes |
| `toplist` | One sport selected by `sportId` | no | yes |

To retrieve a regular list of all available matches for a selected sport or tournament,
rather than only the top selection, use [`events`](../events.md).

## 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](../../examples/json-responses/toplist.sport-1.line.ru.json)
- [English](../../examples/json-responses/toplist.sport-1.line.en.json)

### Extended Objects (`full=true`)

- [Russian](../../examples/json-responses/toplist.full.sport-1.line.ru.json)
- [English](../../examples/json-responses/toplist.full.sport-1.line.en.json)

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](../../getting-started/update-guidelines.md) for more details.

Key, subscription, and parameter errors are documented in
[Error Handling](../../getting-started/error-handling.md).
