Round

Owned by Raiko Pajur
Jul 03, 2023
6 min read

Table of Contents

Round

What is Round? A Round is representation of a real-life Season based on Rounds. E.g. Tennis or Snooker tournaments or other Sport which are Phase based. Like the Group Phase of Champions League and the Elimination Phase of it. There are several domain rules for proposing the different types of rounds:

  • A parent round can only be Round of type Phase

  • Start Date of the Round must be within the range defined by the Season to which the Round will be attached

  • If round is of type Round Competitors cannot be attached to the Round (this means that you must add RoundCompetitors only to the other available Round types).

A Round can be proposed through the Fixtures API v2 on endpoint /v2/rounds

A Round will be considered as duplicate when all of the properties GSS Season Id and Round Name match any of the already existing Rounds inside the GSS Seasons in the GSS system.

A Round can be requested through the Fixture API v2 on endpoint /v2/rounds.

When to use

The Round entity can be used to define the real-life Rounds in the Season e.g. Premier League 2021/2022 Round N, where N is the Round number.

How to use

The Round entity can be used to override some rules of the Season or the Competition or to combine many Fixtures under one entity. The Round entity can be retrieved from the Fixtures API v2 on endpoint /v2/rounds. And then set the needed GSS Id to the request which is going to be made to Fixtures API v2 when it is needed.

Example workflow

  1. GET GSS Rounds from Fixtures API v2

    curl --location --request GET 'https://ci.fixtures.api.geniussports.com/v2/rounds' \ --header 'x-api-key: <<api_key>>' \ --header 'Content-Type: application/json' \ --header 'Authorization: <<id_token>>' \ --data-raw ''

    Successful response would be with status code 200 and JSON data in format:

    { "page": 0, "pageSize": 0, "totalItems": 0, "items": [ { "metadataProperties": [ // Sport specific rules which will be applied to the fixture if not overriden { "name": "string", "value": "string", "isDeleted": true } ], "id": 0, // GSS Round Id "createdOn": "2022-06-28T12:39:01.441Z", "modifiedOn": "2022-06-28T12:39:01.441Z", "updatesCount": 0, "name": "string", "startDate": "2021-11-29T11:59:33.257Z", "endDate": "2021-11-29T11:59:33.257Z", "type": "string", // Type of the round (Phase = 0, Round = 1) "season": { "Id": 0, // GSS Season Id related to the current round "Name": "string", "Ref": "/seasons/{Id}" }, "sport": { "Id": 0, // GSS Sport ID Defines what competitors can be added to the current Round and later on to the Fixture "Name": "string", "ref": "/sports/{id}" // Endpoint on which Sport is available }, "competition": { "Id": 0, // The GSS Competiton related to the current Round "Name": "string", "Ref": "/competitions/{Id}" }, "parentRound": { "id": 0, // The GSS Round Id of the parent Round associated with the current Round if available "name": "string", "ref": "/rounds/{id}" }, "timezone": { "id": 0, // The GSS Timezone Id realted to the current Round "name": "string", "ref": "/timezones/{id}" } } ], "self": "string", "previous": "string", "next": "string", "first": "string", "last": "string" }

     

  2. POST Fixture for any of the retrieved GSS Round Ids:

    curl --location --request POST 'https://ci.fixtures.api.geniussports.com/v2/fixtures' \ --header 'x-api-key: <<api_key>>' \ --header 'Content-Type: application/json' \ --header 'Authorization: <<id_token>>' \ --data-raw '{ "competitors": [ 1, 2 ], "startDate": "2021-11-29T12:03:49.578Z", "roundId": 0, // GSS Round Id from the previous request "seasonId": 0 }'

Read Data Points

Field

Type

Nullable

Description

Field

Type

Nullable

Description

id

int64|unsigned

The numeric identifier of the Round in GSS

name

string

The name of the Round.

type

string|in: Phase, Round, AggregateEvent

The type of the Round. Examples:

Phase - England Premier League 2020/2021 Regular Season or UEFA Champions League 2020/2021 Group Stage or UEFA Champions League 2020/2021 Round of 16

Round - UEFA Champions League 2020/2021 Group A

AggergateEvent - UEFA Champions League 2020/2021 Manchester City v Paris Saint-Germain (Aggregate Event aka Series)

startDate

timestamp

The date on which the Round starts

endDate

timestamp

The date on which the Round ends

parentRound

object|SportEmbed

The numeric identifier, name and a reference of the Parent Round for which is the current Round.

sport

object|SportEmbed

The numeric identifier, name and a reference of the Sport for which is the Round. This property is read-only and is auto-filled by the associated Season

competition

object|CompetitionEmbed

The numeric identifier, name and a reference of the Competitions for which is the Round. This property is read-only and is auto-filled by the associated Season

season

object|SeasonEmbed

The numeric identifier, name and a reference of the Season for which is the Round

timezone

object|TimezoneEmbed

The timezone where the Round will be held

metadataProperties

array|MetadataEmbed

Check AllowedMetadataPropertyType

createdOn

timestamp

The timestamp when the data entity was created

modifiedOn

timestamp

The timestamp when the data entity was modified

updatesCount

int32|unsigned

The amount of times the data entity was updated

Create/ Update Data Points

Field

Type

Required On Create

Required On Update

Description

Field

Type

Required On Create

Required On Update

Description

id

int64|unsigned

The numeric identifier of the Round in GSS

startDate

string

The date on which the Round starts

endDate

string

The date on which the Round ends

name

string

The name of the Round

type

int32|in: 0, 1, 2

The type of the Round. Once set it cannot be changed! Examples:

0 - Phase - England Premier League 2020/2021 Regular Season or UEFA Champions League 2020/2021 Group Stage or UEFA Champions League 2020/2021 Round of 16

1 - Round - UEFA Champions League 2020/2021 Group A

2 - AggergateEvent - UEFA Champions League 2020/2021 Manchester City v Paris Saint-Germain (Aggregate Event aka Series)

timezone

string

The timezone where the Round will be held

competitiors

array|int64|unsigned

The GSS Competitor Ids which will take part in the Round

seasonId

int64|unsigned

The GSS Seasons Id with which the Round will be associated. Once set it cannot be changed!

parentRoundId

int64|unsigned

The GSS Round Id of the Round which will represent the ParentRound of the current Round. Once set it cannot be changed!

metadataProperties

string

Check AllowedMetadataPropertyType

 

Validations

Description

On Create

On Update

On Delete

Response Code

Contains Conflict Header

Error Message

Description

On Create

On Update

On Delete

Response Code

Contains Conflict Header

Error Message

Round must exist

400

Not found. Missing Round entity with id: {proposed id}

Round must not exist

409

Conflict detected! Round with the same name exists in the same season. Existing round id: {existing round id}

Season must exist

400

Not found. Missing Season entity with id: {proposed season id}

Parent Round must exist

400

Not found. Missing Round entity with id: {proposed parent round id}

Timezone must exist

400

Not found. Timezone with name {proposed timezone} does not exists.

All competitors must exist

400

Only existing competitors are allowed to be added to season. Competitors which do not exist are: {competitors ids separated by ', '}

Only distinct competitors can be sent

400

Duplicated competitors: {competitor ids separated by ', '}

Only competitors which are part of season can be sent except for:

  1. When the Competition associated to the Season is friendly competition (has metadata property with name IsFriendly and value yes)

  2. When The Competitors are TBD competitors

400

Not all competitors {non TBD competitor ids from proposed competitors separated by ', '} are added in this season: {proposed season id}

Only competitors which do not have fixtures for the Round can be removed

400

Cannot delete round competitors {competitor ids separated by ‘, '}, having fixtures:{fixture ids separated by ', ’}

Fixtures are not associated with the Round

400

Cannot delete round with id {proposed round id} because it has fixtures!

Proposed startDate must be before the proposed endDate

400

Start date must be smaller than or equal to end date!

Competitors must not be sent when round is of type “Round” (1)

400

Round competitors are not allowed for round of type Round

Competitors count must not be more than 2 when Round is of type “AggregateEvent“ (2)

400

Round of type aggregate event cannot have more than 2 competitors

Round of type AggregateEvent (2) must have ParentRound

400

Round of type 'AggregateEvent' should have parent round.

ParentRound’s SeasonId must be same as proposed Season Id when ParentRound is proposed

400

The round: {proposed parent round id} is not in season: {proposed season id}

Only Round of type Phase (0) can be proposed as ParentRound

400

The parent round can only be of 'Phase' type.

Proposed endDate must be before the proposed season’s endDate

400

End date must be smaller or equal to Season's end date {proposed season's endDate in format yyyy-MM-dd}

Proposed startDate must be after the proposed season’s startDate

400

Start date must be greater or equal to Season's start date {proposed season's startDate in format yyyy-MM-dd}

Child Rounds are not associated with the Round

400

Cannot delete round with child rounds