Additional Matches and Submatches Data Model

What Is an Additional Match?

An additional match, or submatch, is a separate line within the main sporting event. A submatch has its own game_id and its own set of betting markets and odds.

Examples of submatches:

• first or second half;
• corners;
• first-half or second-half corners;
• yellow cards;
• fouls and offsides;
• shots and shots on target;
• player statistics;
• other additional match markets.

In this documentation, “additional match” and “submatch” refer to the same entity from the sub_games array.

Main Match and Submatch

The main match and its submatches are connected through game_id and game_mid.

For a main match, game_id and game_mid usually match, while game_dop_name remains empty:

{
  "game_id": 746146992,
  "game_mid": 746146992,
  "game_dop_name": ""
}

A submatch has its own game_id, while game_mid points to the main match:

{
  "game_id": 746147010,
  "game_mid": 746146992,
  "game_dop_name": "Corners"
}

In this example:

• 746147010 is the ID of the “Corners” submatch;
• 746146992 is the ID of the main match;
• request corner odds using the submatch’s game_id, 746147010.

Do not replace a submatch’s game_id with game_mid; these fields serve different purposes.

Where to Retrieve the Submatch List

Retrieve the additional-match list only from sub_games in the detailed event response for the main match.

events
  ↓ main match game_id
main match event
  ↓ sub_games[].game_id
selected submatch event
  ↓ game_oc_list
complete list of its betting selections and odds

In the events match list, sub_games is not used and is returned empty:

{
  "sub_games": []
}

topmatches?full=true and toplist?full=true do not provide the submatch list either.

sub_games Structure

sub_games is an array of links to available additional matches:

{
  "sub_games": [
    {
      "game_id": 746147013,
      "game_num": 150080,
      "game_name": "2nd half"
    },
    {
      "game_id": 746147010,
      "game_num": 205978,
      "game_name": "Corners"
    },
    {
      "game_id": 746147314,
      "game_num": 178621,
      "game_name": "Yellow Cards"
    }
  ]
}

game_name is intended for display. Do not use the name text as a technical identifier, because it depends on the selected language.

Use only game_id in the request. Do not generate a submatch ID yourself or use game_num in its place.

What sub_games Contains

A sub_games item contains only a submatch link and name. It does not contain:

• odds;
• betting markets;
• the full match object;
• separate statistics;
• a list of child submatches.

To retrieve betting selections and odds, make a separate event request using the selected additional match’s game_id.

Requesting an Additional Match

The main Live match returned a link to the “Corners” submatch:

{
  "game_id": 746147010,
  "game_num": 205978,
  "game_name": "Corners"
}

Request the submatch with the same event method:

curl --request GET \
  --url 'https://YOUR_API_DOMAIN/v1/event/746147010/group/live/en' \
  --header 'Package: YOUR_API_KEY'

Shortened response fragment:

{
  "status": 1,
  "page": "/v1/event",
  "body": {
    "game_id": 746147010,
    "game_mid": 746146992,
    "game_dop_name": "Corners",
    "game_desk": "Half",
    "game_oc_counter": 175,
    "sub_games": []
  }
}

The submatch’s full betting list is in body.game_oc_list. It uses the same group structure as the main match’s betting list.

Saved full response: “Corners” submatch, Live, Russian.

Live and Prematch

Additional matches may be returned in both Live and Prematch. Request a submatch using the same sports line type from which its game_id was retrieved:

sub_games from Live     → event/{gameId}/group/live/{lang}
sub_games from Prematch → event/{gameId}/group/line/{lang}

Prematch and Live versions of matches have different IDs. Do not carry a main match or submatch game_id from line into live.

The contents of sub_games may also differ between Prematch and Live. Use only the current list from the latest API response.

Submatch Names and Types

In sub_games, the name is stored in game_name:

{
  "game_name": "Corners"
}

After requesting the additional match, its type is returned in game_dop_name:

{
  "game_dop_name": "Corners"
}

game_desk may additionally describe a playing segment, such as Half, Set, or Quarter. It does not replace game_id and must not be used as a permanent submatch type ID.

The available names depend on the sport and its available markets. Do not define a fixed list that every match must contain.

Submatch Odds

A submatch is a separate sports line object with its own:

• game_id;
• game_oc_counter;
• markets in game_oc_list;
• selections and odds;
• oc_pointer values.

The odds in game_oc_list apply only to the selected submatch. They do not include bets from the main match or other additional matches.

For example, if you request the “Corners, 1st Half” submatch, the response contains odds only for first-half corners:

• not for every event in the first half;
• not for all corners in the main match;
• not for the entire main match.

To retrieve odds for all corners in the match, separately open the “Corners” submatch. To retrieve odds for the main match, request event using the main match’s game_id.

Use the group format to display the complete list, and preserve the market, column, and selection order created by the API.

For details about the betting structure, see Odds and Betting Market Data Model.

Statistics in a Submatch

stat_list in a submatch response applies to the entire main match. It does not contain separate statistics for the selected additional match.

For example, when requesting “Corners, 1st Half” or “1st Half,” stat_list still contains the main match’s general statistics. Do not filter statistics based on game_dop_name.

Detailed rules are documented in Live Match Statistics Data Model.

When a Submatch Is Unavailable

The additional-match list may change. If an item is no longer present in the current sub_games, do not continue displaying it as available.

When requesting an outdated game_id, the API may return:

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

After this response, stop updating the old ID. The message does not explain the exact reason why the additional match disappeared.

Group Matches and event_plan

event_plan and sub_games are different structures.

event_plan is intended for group matches. In the main object of such an event, the sides may have generic names such as “Home — Away.” event_plan expands these sides and lists all actual teams participating in the group match.

Each array object pairs one home-side team with the corresponding away-side team. The complete array contains all such pairs and therefore provides the full team list for both sides.

For example, sub_games may contain a separate “Corners” or “1st Half” market, while event_plan for a “Home — Away” group match contains pairs of specific teams:

Home                            Away
Anzoategui          →           Trujillanos
Caracas             →           Carabobo

A populated event_plan can be retrieved only through a specific event request. In an events list, the field is returned as [].

event_plan Object Fields

Shortened group-match composition example:

{
  "event_plan": [
    {
      "opp_1_name": "Anzoategui",
      "opp_2_name": "Trujillanos",
      "opp_1_id": 6354451,
      "opp_2_id": 2792,
      "opp_1_country_id": 41,
      "opp_2_country_id": 41,
      "opp_1_icon": "b85e2e3631e4b873b1d74975e6dd4e93.png",
      "opp_2_icon": "2792.png",
      "game_start": 1787342400
    },
    {
      "opp_1_name": "Caracas",
      "opp_2_name": "Carabobo",
      "opp_1_id": 2776,
      "opp_2_id": 29081,
      "opp_1_country_id": 41,
      "opp_2_country_id": 41,
      "opp_1_icon": "6309ee8475d59f87fff70fd08858e36f.png",
      "opp_2_icon": "56b11c23ac71e2f6934a7e0feb46dd5e.png",
      "game_start": 1787353200
    }
  ]
}

event_plan items are not links to submatches: they do not contain a separate game_id for an event request. Use them to display the complete composition of the home and away sides and the schedule of pairs within the group match.

For a participant 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

Practical Integration Rules

1. Retrieve sub_games only from the main match’s detailed event response.
2. Open a submatch using its own game_id.
3. Request an additional match in the same sports line type: live or line.
4. Do not use the legacy game_num field.
5. Do not expect odds directly inside sub_games.
6. Link a submatch to the main match through game_mid.
7. Do not interpret submatch statistics as separate statistics for its market.
8. Do not mix additional matches from sub_games with the group-match composition in event_plan.
9. Refresh the submatch list using the current API response.

Verification Responses

• Main Live match with 13 submatches
• Main Prematch match with 24 submatches
• Detailed “Corners” submatch response

These saved verification responses are in Russian because the available full submatch snapshot was captured using lang=ru. The object structure and field names are language-independent.

Related Documents

• Match Data Model
• Live Match Statistics Data Model
• Odds and Betting Market Data Model
• event — Specific Match
• Field Reference