---
id: api-topmatches
title: topmatches Method — Top Matches
description: Reference for the TOPMATCHES method, which returns popular matches across all sports.
version: v1
language: en
---

# `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

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

Send the API key in the HTTP header:

```http
Package: YOUR_API_KEY
```

## Path Parameters

| Parameter | Type | Required | Description |
|---|---|---:|---|
| `type` | string | yes | Sports line type: `live` or `line` |
| `lang` | string | yes | Language of names. It must be supported by the API and included in the client's subscription |

Values of `type`:

| Value | Matches returned |
|---|---|
| `live` | Top matches currently in progress |
| `line` | Upcoming Prematch top matches |

## The `full` Parameter

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

| 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, score, and a short odds list |

Example URL with extended objects:

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

## Live Request Examples

Short summaries:

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

Extended objects:

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

## Prematch Request Examples

Short summaries:

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

Extended objects:

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

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

| Field | Type | Description |
|---|---|---|
| `status` | number | Request status. A successful response returns `1` |
| `page` | string | The current API response returns `/v1/topmathes` |
| `body` | array | Flat top-match array without grouping by sport or tournament |

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

| 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 | Current overall score. Prematch usually returns `0:0` |
| `period_name` | string | Current Live period. Prematch returns an empty string |
| `timer` | number | Live match timer in seconds. Divide by `60` to obtain minutes. Prematch usually returns `0` |
| `va` | number or `null` | `1` — video is available; `null` — no video is available |
| `vi` | string or `null` | Live video stream ID |
| `zp` | number or `null` | Live 3D Tracker ID, passed to the tracker as `gameid` |

## 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](../../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 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
```

## 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`](../events.md). For complete details of one match, use [`event`](../event.md).

## 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](../../examples/json-responses/topmatches.live.ru.json)
- [Prematch, Russian](../../examples/json-responses/topmatches.line.ru.json)
- [Live, English](../../examples/json-responses/topmatches.live.en.json)
- [Prematch, English](../../examples/json-responses/topmatches.line.en.json)

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

- [Live, Russian](../../examples/json-responses/topmatches.full.live.ru.json)
- [Prematch, Russian](../../examples/json-responses/topmatches.full.line.ru.json)
- [Live, English](../../examples/json-responses/topmatches.full.live.en.json)
- [Prematch, English](../../examples/json-responses/topmatches.full.line.en.json)

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

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