---
id: core-concepts
title: Sport Line API — Core Concepts
description: Explanation of sports line entities and relationships among sports, countries, tournaments, matches, and odds.
version: v1
language: en
---

# Sport Line API — Core Concepts

This document explains how the sports line is structured, how its objects relate to one
another, and which identifiers must be used during integration.

## REST API and Data Freshness

Sport Line API uses REST API. Each request returns a snapshot of the data at the time of
the request.

To receive updated scores, match states, and odds, the client application must repeat
its requests. The recommended intervals are documented in
[Data Update Guidelines](update-guidelines.md).

WebSocket support is under development and is not currently used in production
integrations.

## Prematch and Live

The sports line is divided into two data types:

| URL value | Name | Contents |
|---|---|---|
| `line` | Prematch | Matches that have not started yet |
| `live` | Live | Matches currently in progress |

The line type is included in the request path. For example, the Live menu uses:

```text
/v1/menu/live/en
```

The same sports match may first appear in Prematch and then move to Live after it
starts. A new `game_id` is generated for the Live match and does not match the Prematch
ID. Treat them as separate API events and do not link them by `game_id`.

## Sports Line Hierarchy

Sport Line API organizes its data as follows:

```text
sport
└── country
    └── tournament
        └── match
            ├── betting markets and odds
            └── match sub-events
                └── their own betting markets and odds
```

| Level | Description | Primary ID |
|---|---|---|
| Sport | Football, basketball, tennis, and other sports | `sportId` |
| Country | The country associated with the tournament | `countryId` |
| Tournament | A league, cup, or other competition | `tournamentId` |
| Match | An individual sports event | `game_id` |
| Match sub-event | A separate line within the main match | `sub_games[].game_id` |

The `menu` method returns this entire hierarchy down to the tournament level. Retrieve
the match list separately with the `events` method.

If the client does not need the full menu, separate methods can return only sports,
countries, or tournaments.

Sub-events are returned in the main match's `sub_games` field. Depending on the sport
and available data, they may represent halves, corners, cards, fouls, or other match
metrics. Not every match contains sub-events.

## Build Navigation from Current Responses

Do not request sports, countries, or tournaments using stored static IDs without first
checking that they are present in the current response. Sport Line API returns only the
sections that contain available matches for the selected line type at the time of the
request.

Recommended sequence:

```text
menu for live or line
  ↓ current sportId
  ↓ current countryId
  ↓ current tournamentId
events
```

When using step-by-step navigation, follow the complete sequence:

```text
sports
  ↓ sportId from the current response
countries
  ↓ countryId from the current response
tournaments
  ↓ tournamentId from the current response
events
```

Do not store `sportId` and `tournamentId` once and assume that their sections will
always be present in `line` or `live`. An identifier may continue to represent the same
sport or tournament, but its presence in the current sports line is dynamic.

For example, Prematch may contain a single cricket match in a particular league. While
the match is available, the API returns:

```text
Cricket → country → league → match
```

When the match starts and moves to Live, is cancelled, or disappears from Prematch for
another reason, the league will no longer appear in the Prematch menu. If no other
cricket matches remain in Prematch, the Cricket sport will also disappear from the
response.

The same rule applies to Live: when the only Live match in a tournament ends, the
tournament disappears from the Live response. If it was the only match for that sport,
the sport disappears as well.

Check `line` and `live` separately. A sport or tournament being present in Prematch does
not mean that it is already present in Live, and vice versa.

When updating navigation:

1. Retrieve a new current response for the required line type.
2. Check whether the selected sport is still present in the response.
3. Check the selected country and tournament within that sport.
4. If the selected branch has disappeared, stop treating it as available and show the
   user the current sections instead.
5. Do not continue repeatedly requesting `events` for a tournament ID that is no longer
   present in the current navigation.

## Identifiers

Always take identifiers from a current API response. Do not derive them from names or
substitute one ID for another.

| Object | Parameter in the URL description | Field in JSON |
|---|---|---|
| Sport | `sportId` | `sport_id` |
| Country | `countryId` | `country_id` |
| Tournament | `tournamentId` | `tournament_id` |
| Match | `gameId` | `game_id` |

URL parameter names usually use the `sportId` style, while JSON responses use
`sport_id`. These names represent the same identifier in different naming styles.

For the `events` method, `tournamentId = 0` means: return matches from all tournaments
of the selected sport.

## `game_id`, `zp`, and `vi` Are Different Identifiers

`game_id` is the match ID in Sport Line API. Use it to request detailed match data with
the `event` method.

`zp` is a separate ID for Live 3D Tracker. Pass the value of `zp` as the tracker's
`gameid` parameter:

```text
tracker gameid = zp from Sport Line API
```

If `zp` is `null`, Live 3D Tracker is unavailable for that match. The tracker works only
for Live matches and supported sports.

Do not pass `game_id` to the tracker instead of `zp`.

`vi` is the video stream ID of a Live match. For example:

```json
{
  "vi": "DR_3_1783061985"
}
```

The `zp` and `vi` fields are stored in the match's JSON object:

| Field | Purpose |
|---|---|
| `zp` | Live 3D Tracker ID |
| `vi` | Live video stream ID |

These values do not replace `game_id` and are used only to connect the corresponding
service.

## The `events` and `event` Methods

The method names differ by only one letter, but they serve different purposes:

| Method | Purpose |
|---|---|
| `events` | Returns matches for a sport or a specific tournament |
| `event` | Returns detailed data for one match by `game_id` |

General workflow:

1. Retrieve the hierarchy with `menu`.
2. Select `sportId` and `tournamentId`.
3. Retrieve the match list with `events`.
4. Take the required match's `game_id`.
5. Retrieve full details with `event`.

General path formats:

```text
/v1/events/{sportId}/{tournamentId}/{format}/{count}/live/{lang}
/v1/event/{gameId}/{format}/live/{lang}
```

## Line Type and Response Format

The line type and response format are separate parameters:

| Concept | Allowed values | Purpose |
|---|---|---|
| Line type | `line`, `live` | Selects Prematch or Live matches |
| Response format | `sub` for `events`, `group` for `event` | Determines how matches and odds are grouped in JSON |

For example, `live` and `sub` in the `events` method mean: return Live matches grouped
by tournament.

### Formats

| Format | Available in | Structure |
|---|---|---|
| `sub` | `events` only | Matches grouped by tournament |
| `group` | `event` only | Odds organized into markets and columns and sorted by value |

Use only `sub` with `events` and only `group` with `event`.

The `group` format is recommended for a specific match because the API already builds
the columns and sorts selections by value. The client does not need to rebuild or
re-sort this structure.

The format does not change the match itself, its ID, or the line type. It changes only
how the response data is organized.

## Match, Market, and Odds

A match object may contain:

- sport, country, and tournament information;
- match participants;
- start time;
- current score, period, and timer;
- betting markets and odds;
- statistics and match sub-events;
- Live 3D Tracker and Live video stream identifiers, when available.

### Match Sub-events

Each item in `sub_games` has its own `game_id`, number, and name. Use that `game_id` to
request the sub-event through the `event` method and retrieve its markets and odds.

Sub-events may provide bets on a specific part of the match or a particular statistic.
For example:

- selections for a particular half or period;
- corners;
- cards;
- fouls;
- other additional metrics.

In addition to sub-events, `game_oc_list` may contain bets on individual player metrics.
Such bets are betting markets and are not necessarily separate items in `sub_games`.

The `stat_list` field contains current statistics for the match itself. These are actual
match metrics, not a list of available bets.

Betting data uses two levels:

```text
market (group) → selection with odds
```

For example, a market may contain several possible selections. Each selection has its
own name, current odds value, and availability indicator.

A detailed table of match, market, and odds fields is available in the
[Data Models](../README.md#data-models) section.

## The `counter` Field

Menu objects may contain a `counter` field. It represents the number of available
matches within the corresponding sport, country, or tournament for the selected line
type.

The `counter` value may change as matches appear, start, and end. Do not use it as a
permanent identifier.

## Response Language

The language code is included at the end of the request path:

```text
/v1/menu/live/en
```

The language affects the names of sports, countries, tournaments, teams, markets, and
other text fields. Object identifiers do not depend on the selected language.

The language must be supported by Sport Line API and included in the client's
subscription.

## Esports

Methods that support esports data use the optional query parameter:

```text
?cybersport=true
```

If the parameter is omitted, the regular sports dataset is returned. Each method's
documentation specifies whether the parameter is supported and how it is used.

## Common Successful Response Format

Most successful responses use the following common envelope:

```json
{
  "status": 1,
  "page": "/v1/menu",
  "body": []
}
```

| Field | Description |
|---|---|
| `status` | Request status. A successful response usually returns `1` |
| `page` | The API method that generated the response |
| `body` | Method data. Its type and structure depend on the method |

Errors may use a different structure with `error_code` and `error_message` fields. See
[Error Handling](error-handling.md) for more details.

## Applying These Concepts During Integration

1. Store Prematch and Live data separately.
2. Link objects by ID, not by name.
3. Obtain `game_id` from `events` before requesting `event`.
4. Use `zp`, not `game_id`, for Live 3D Tracker.
5. Use `vi` for Live video streaming.
6. Account for scores, timers, states, and odds changing over time.
7. Check API responses for errors and empty arrays.

Next: [Data Update Guidelines](update-guidelines.md).
