---
id: integration-guide
title: Sport Line API — Integration Guide
description: Step-by-step instructions for connecting Sport Line API to a website, application, or internal client system.
version: v1
language: en
---

# Sport Line API — Integration Guide

Sport Line API provides up-to-date sports data for a client's website, application, or
other software product.

Official website: [sportapi.net](https://sportapi.net).

Telegram support: [@suport_sportapi](https://t.me/suport_sportapi).

## Contents

1. [What Sport Line API Provides](#1-what-sport-line-api-provides)
2. [Integration Requirements](#2-integration-requirements)
3. [Making Your First Request](#3-making-your-first-request)
4. [Core Integration Flow](#4-core-integration-flow)
5. [Prematch and Live](#5-prematch-and-live)
6. [Data Returned by the API](#6-data-returned-by-the-api)
7. [Additional Methods](#7-additional-methods)
8. [Ready-to-use Icons](#8-ready-to-use-icons)
9. [Updating Data](#9-updating-data)
10. [Live 3D Tracker](#10-live-3d-tracker)
11. [Video Streaming](#11-video-streaming)
12. [Error Handling](#12-error-handling)
13. [Integration Examples](#13-integration-examples)
14. [Detailed Documentation](#14-detailed-documentation)
15. [Support](#15-support)

## 1. What Sport Line API Provides

Sport Line API allows you to retrieve:

- available sports;
- countries, tournaments, and competitions;
- upcoming Prematch events;
- events currently in progress in Live;
- teams or participants in an event;
- start time, current score, period, and timer;
- a short list of the main odds in event lists;
- the full list of betting markets and odds for a selected event;
- sub-events such as halves, corners, cards, fouls, and other additional markets;
- key Live statistics;
- information about Live 3D Tracker and video availability.

Sport Line API uses REST API. Your application retrieves current data through standard
HTTP requests.

WebSocket support is under development and is not yet available for production
integrations.

## 2. Integration Requirements

To integrate Sport Line API, you need to:

1. Contact the [SportAPI manager on Telegram](https://t.me/suport_sportapi) and request
   access to the sports line.
2. Obtain your API base URL and personal access key from the manager.
3. Confirm which sports and languages are included in your subscription.
4. Store the key in the protected configuration of your backend application.
5. Send the key in the `Package` HTTP header with every request.

The base URL may differ between client connections. In every example, replace
`https://YOUR_API_DOMAIN` with the address provided by the manager.

Send the key as follows:

```http
Package: YOUR_API_KEY
```

Do not include the key in a URL or expose it in browser-side JavaScript, a mobile
application, a public repository, or error messages. Requests to Sport Line API should
be made through your backend.

The sports, languages, and access period available to you are determined by your key's
subscription package.

See [Authentication and Access](getting-started/authentication-and-access.md) for more
details.

## 3. Making Your First Request

Request the Live menu to verify your connection:

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

In this request:

- `live` requests events that are currently in progress;
- `en` requests the response in English;
- `Package` is the HTTP header containing your API key.

A successful response uses the following common envelope:

```json
{
  "status": 1,
  "page": "/v1/menu",
  "body": [
    {
      "id": 1,
      "name": "Football",
      "counter": 53,
      "sub": []
    }
  ]
}
```

| Field | Description |
|---|---|
| `status` | Request status. A successful response usually returns `1` |
| `page` | The API method that generated the response |
| `body` | Data returned by the selected method |

The values above demonstrate the response structure. The actual sports line changes
continuously.

See [Quick Start](getting-started/quick-start.md) for more details.

## 4. Core Integration Flow

Use the following sequence for the core integration:

```text
menu → events → event
```

### Step 1. Retrieve the Current Menu

```http
GET /v1/menu/{type}/{lang}
```

The `menu` method returns the currently available hierarchy in a single request:

```text
sport → country → tournament
```

Select current `sportId` and `tournamentId` values from the response.

See [`menu` — Sports Line Menu](api-reference/menu.md) for more details.

### Step 2. Retrieve the Event List

```http
GET /v1/events/{sportId}/{tournamentId}/sub/50/{type}/{lang}
```

When calling `events`:

- use only the `sub` format;
- pass `50` in the required `count` path segment;
- pass a specific tournament ID, or use `tournamentId=0` to retrieve events from all
  tournaments of the selected sport.

The `count` parameter no longer limits the number of results. The value `50` remains in
the URL for compatibility, while the API returns all available events in the selected
scope.

The response is grouped by tournament:

```text
body
└── tournament
    └── events_list
        └── events
```

Each event's `game_oc_list` contains a short list of its main odds. The contents depend
on the sport. For example, football may use a `1X2` market, basketball commonly offers
the first or second team to win, and tennis has no draw selection.

Do not build the interface around one fixed set of market or selection names. Read the
actual markets and odds returned by the API.

See [`events` — Event List](api-reference/events.md) for more details.

### Step 3. Retrieve Full Event Details

Take the selected event's `game_id` from the `events` response and make the following
request:

```http
GET /v1/event/{gameId}/group/{type}/{lang}
```

The `event` method supports only the `group` format. The API already:

- organizes selections into betting markets;
- creates columns within each market;
- sorts selections by their values.

Preserve the order of markets, columns, and selections returned by the API.

The `event` method returns the full available odds list for the selected event, its
sub-events, Live statistics, and other detailed data.

See [`event` — Specific Event](api-reference/event.md) for more details.

### Use Only Current IDs

Do not create a permanent static list of sports, countries, and tournaments. The API
returns only sections that currently contain events for the selected line type.

If the only event in a tournament ends, that tournament may disappear from the next
`menu` response. If no other events remain for the sport, the sport itself will also
disappear from the menu.

Before requesting `events`, verify that the selected `sportId` and `tournamentId` are
still present in the current menu for the same `live` or `line` type.

## 5. Prematch and Live

Sport Line API separates data into two types:

| URL value | Data returned |
|---|---|
| `line` | Prematch — events that have not started yet |
| `live` | Live — events currently in progress |

Prematch and Live data must be requested and stored separately.

When an event moves from Prematch to Live, a new `game_id` is created. The Live ID does
not match the Prematch ID, so do not link the two versions by `game_id`.

If the event is no longer available under its previous ID, the `event` method may
return:

```json
{
  "status": 1,
  "page": "/v1/event",
  "body": {
    "message": "Game id finished"
  }
}
```

This message does not explain the reason. The event may have moved to Live under a new
ID, been cancelled, or disappeared from the line for another reason. After receiving
this response, stop requesting the old `game_id` and refresh the current menu and event
list.

## 6. Data Returned by the API

### Match

A match object may contain:

- `game_id` — the match ID used by the `event` method;
- `game_start` — the start time as a Unix timestamp in seconds;
- sport, country, and tournament data;
- team or participant names and IDs;
- the score, period, and timer for a Live match;
- betting markets and odds;
- statistics and sub-events;
- tracker and video fields, when available.

The `timer` field is returned in seconds. To display minutes, divide the value by `60`
and round it for the interface if necessary. Do not send a request every second merely
to update the timer. Update its display locally and synchronize it during the next
scheduled request.

See [Match Data Model](data-models/match.md) for more details.

### Odds

The odds structure is organized as follows:

```text
game_oc_list
└── betting market
    └── oc_list
        └── column
            └── selections and odds
```

The main fields of a selection are:

| Field | Description |
|---|---|
| `oc_name` | Selection name |
| `oc_rate` | Current odds value |
| `oc_size` | Handicap, total, or another parameter value |
| `oc_pointer` | Unique bet or selection identifier |
| `oc_block` | Indicates whether the selection is blocked |

If the separate bet placement and settlement system is connected, `oc_pointer` is the
value used to pass the selected outcome to that system. See
[Bet Pointer](https://sportapi.net/docs/coupon/bet-placement/bet-pointer.html) for the transfer format and
[Coupon Placement](https://sportapi.net/docs/coupon/bet-placement/place-coupon.html) for the next request.

See [Odds and Betting Markets](data-models/odds.md) for more details.

### Sub-events

Sub-events are separate events within the main match. Examples include:

- first half;
- corners;
- first-half corners;
- yellow cards;
- fouls;
- other additional markets.

The sub-event list is returned only in the detailed `event` response, in the
`sub_games` field. Each sub-event has its own `game_id`. To retrieve its odds, make a
separate `event` request using that ID.

The odds in the response apply only to the selected sub-event. For example, when you
request “First-half corners,” the API returns odds only for first-half corners, not for
the entire match or all corners in the match.

See [Sub-events and Additional Matches](data-models/sub-events.md) for more details.

### Live Statistics

Key Live statistics are stored in `stat_list` and are returned only for Live data:

- in the `events` match list;
- in the detailed `event` response for a specific match.

The available metrics depend on the sport and the specific match. These are the main
current characteristics of a Live match, not a separate API for in-depth sports
analytics.

Extended statistics—including match history, team and player analysis, H2H, previous
meetings, and future matches—belong to a separate API that is still under development.

See [Match Statistics](data-models/live-statistics.md) for more details.

A complete table of JSON fields is available in the
[Sport Line API Field Reference](data-models/field-reference.md).

## 7. Additional Methods

Additional methods are not required for the core integration. Use them only when your
project needs the corresponding feature.

The recommended core sequence remains:

```text
menu → events → event
```

| Method | Purpose | Notes |
|---|---|---|
| [`sports`](api-reference/optional-methods/sports.md) | Retrieve sports | Step-by-step alternative to `menu` |
| [`countries`](api-reference/optional-methods/countries.md) | Retrieve countries for a selected sport | Used after `sports` |
| [`tournaments`](api-reference/optional-methods/tournaments.md) | Retrieve tournaments for a selected sport and country | Used after `countries` |
| [`topmatches`](api-reference/optional-methods/topmatches.md) | Retrieve a curated list of top matches | Supports Live and Prematch |
| [`toplist`](api-reference/optional-methods/toplist.md) | Retrieve top matches for a selected sport | Prematch only |
| [`search`](api-reference/search.md) | Search for matches by text | The search text must be URL-encoded |

In most cases, `menu` is preferable because it returns sports, countries, and
tournaments in a single request. The `sports → countries → tournaments` sequence
requires three requests and is intended for specific interface scenarios.

For methods that support filtering for esports data, use:

```text
?cybersport=true
```

Do not call every additional method automatically merely because it exists in the API.

## 8. Ready-to-use Icons

SportAPI provides standard icons. Insert the current value from the API response into
the corresponding URL:

| Object | URL |
|---|---|
| Sport | `https://cdn.sportapi.net/sports/v1/color/{sportId}.webp` |
| Country | `https://cdn.sportapi.net/flags/v1/color/{countryId}.webp` |
| Tournament | `https://cdn.sportapi.net/tournaments/v1/color/{tournamentId}.webp` |
| Team or participant | `https://cdn.sportapi.net/opp/v1/color/{iconName}.webp` |

For a team or participant, use `opp_1_icon` or `opp_2_icon`. Remove the original file
extension, if present, before inserting the value into `{iconName}`.

## 9. Updating Data

Each REST request returns a snapshot of the data at the time of the request. Repeat
requests at the recommended intervals to retrieve score, period, statistics, and odds
updates.

| Data or method | Live | Prematch (`line`) |
|---|---:|---:|
| `menu` | 20 seconds minimum | 60 seconds minimum |
| `sports`, `countries`, `tournaments` | 60 seconds minimum | 120 seconds minimum |
| `events` | 7 seconds minimum | 30 seconds minimum |
| `event` | 5 seconds minimum | 30 seconds minimum |
| `topmatches` | 30 seconds minimum | 120 seconds minimum |
| `toplist` | Not used | 120 seconds minimum |

An interval of “5 seconds minimum” means that you must not send the request more often
than once every 5 seconds. If the manager has provided different intervals for your
connection, follow the manager's values.

Do not start another request for the same data while the previous request is still in
progress. Do not request a detailed `event` for every match unless those details are
actually shown to the user.

See [Data Update Guidelines](getting-started/update-guidelines.md) for more details.

## 10. Live 3D Tracker

Live 3D Tracker is a separate ready-made widget that visualizes a Live match. Sport Line
API does not provide the raw data required to render the tracker independently. Instead,
it returns the ready-made widget's ID in the `zp` field.

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

If `zp` is `null`, the tracker is unavailable for that match. Do not substitute
`game_id` or any other identifier for `zp`.

The tracker may be displayed for a Live match only when:

- `zp` is populated;
- the sport is supported by the tracker;
- the client has an active tracker key;
- the client's domain is allowed for that key;
- the sport and language are included in the subscription.

Supported sports:

| ID | Sport |
|---:|---|
| `1` | Football |
| `2` | Ice Hockey |
| `3` | Basketball |
| `4` | Tennis |
| `5` | Baseball |
| `6` | Volleyball |
| `7` | Rugby |
| `8` | Handball |
| `10` | Table Tennis |
| `13` | American Football |
| `17` | Water Polo |
| `21` | Darts |
| `26` | Formula 1 |
| `28` | Australian Rules Football |
| `44` | Horse Racing |
| `66` | Cricket |
| `86` | CS:GO / Esports |

A sport's presence in this table does not guarantee that the tracker is available for
every match. Always perform the final availability check using `zp`.

The ready-made widget can be embedded using a direct `iframe` or `embed.js`.

- [How Live 3D Tracker Relates to Sport Line API](additional-services/live-3d-tracker.md)
- [Complete Live 3D Tracker integration guide](https://sportapi.net/docs/live-3d-tracker/service-overview.html)
- <a href="https://bet-embed-sport-tracker-stage.vercel.app/showcase" target="_blank" rel="noopener noreferrer">Widget Showcase</a>

The showcase demonstrates the widget's appearance and does not use real Live data.

## 11. Video Streaming

Sport Line API indicates Live video availability through two fields:

| Field | Value |
|---|---|
| `va` | `1` — a stream is available; `null` — no stream is available |
| `vi` | A string video stream ID or `null` |

The value `va: 0` is not used. Even if `vi` contains only digits, keep it as a string.

Display video only when `va: 1` and `vi` is populated. The `vi` value itself is not a
stream URL or a ready-to-use `iframe` address. It is passed to a separate ready-made
video widget.

Video is available only for some Live matches. SportAPI does not stream matches from
top-tier sports leagues. Do not promise video for a particular competition or match
until the current `va` and `vi` values have been checked.

See [Video Streaming in Sport Line API](additional-services/video-streaming.md) for more
details.

## 12. Error Handling

An API error usually uses the following format:

```json
{
  "error_code": 100,
  "error_message": "Invalid Package"
}
```

Check for `error_code` and `error_message` instead of relying only on the HTTP status.

| `error_message` | What to check |
|---|---|
| `Missing Package header` | Whether the `Package` HTTP header was sent |
| `Invalid Package` | Whether the key was copied correctly |
| `Package has expired` | Whether the key is active and its access period has not expired |
| `Access denied` | Whether the sport or requested feature is included in the subscription |
| `Invalid language` | Whether the language code is supported |
| `The language is not available in your package.` | Whether the language is included in the key's subscription |
| `Wrong data type (accept only live or line)` | Whether the type is correctly set to `live` or `line` |

An empty `body: []` array is not always an error. It may mean that no data is currently
available for the selected scope.

See [Error Handling](getting-started/error-handling.md) for more details.

## 13. Integration Examples

The ready-to-use examples use placeholder keys and base URLs:

- [cURL](examples/curl.md)
- [JavaScript for Node.js](examples/javascript.md)
- [Python](examples/python.md)
- [PHP](examples/php.md)

These are lightweight working integration examples, not full SDKs. They demonstrate
authentication, the core `menu → events → event` sequence, and response handling.

Full real JSON responses with no API keys:
[Sport Line API Reference Responses](examples/json-responses/README.md).

## 14. Detailed Documentation

### Getting Started

- [Quick Start](getting-started/quick-start.md)
- [Authentication and Access](getting-started/authentication-and-access.md)
- [Core Concepts](getting-started/core-concepts.md)
- [Data Update Guidelines](getting-started/update-guidelines.md)
- [Error Handling](getting-started/error-handling.md)

### Core Methods

- [`menu`](api-reference/menu.md)
- [`search`](api-reference/search.md)
- [`events`](api-reference/events.md)
- [`event`](api-reference/event.md)

### Data Models

- [Response Format](data-models/response-format.md)
- [Match](data-models/match.md)
- [Odds and Betting Markets](data-models/odds.md)
- [Match Statistics](data-models/live-statistics.md)
- [Sub-events and Additional Matches](data-models/sub-events.md)
- [Field Reference](data-models/field-reference.md)

## 15. Support

If a request does not work, send the manager:

- the request URL without the API key;
- the time when the request was made;
- the HTTP status;
- `error_code` and `error_message`;
- the line type, language, and IDs used;
- a code example with all sensitive data removed.

Do not send your API key in a public chat or public issue.

- SportAPI support: [@suport_sportapi](https://t.me/suport_sportapi)
- Official website: [sportapi.net](https://sportapi.net)
