Release Notes

API Releases

Release 4.1.20: 3D ball and player tracking

06-Sep-2023

From version API V 4.1.20 our system will support 3D ball and player tracking data: https://help.signality.com/api/#tag/Phases/operation/Tracks

Changes for data users

To get the 3D positional data of the ball (x, y, z), a new coordinate system will be used, and it will be reflected in the data output.

Coordinate system before data format version 6.x.x:

From data format version 6.x.x:

Managing the data output change between old games and new games

Existing games will remain with the old coordinate system if not reprocessing is requested. Thus, users will need to manage differently the data after this change. Users will be able to identify the new coordinate system by checking the field “version” in the header of all GET messages responses (please notice that data version differs to the API version, e.g.: response Headers on GetTracks: https://help.signality.com/api/#tag/Phases/operation/Tracks). Only games tagged with the data format version 6.x.x or later will have the new coordinate system.

RESPONSE HEADERS

{
  'Date': 'Thu, 06 Apr 2023 14:48:15 GMT',
  'Content-Type': 'application/json; charset=utf-8',
  'Transfer-Encoding': 'chunked',
  'Connection': 'keep-alive',
(…)
  'Referrer-Policy': 'no-referrer',
  'X-XSS-Protection': '0',
  'Last-Modified': 'Fri, 09 Apr 2023 00:54:59 GMT',
  'Version': '6.0.0',
  'Stage': 'live',
  'content-encoding': 'gzip'
}

Changes for video providers

3D ball and player tracking will require stereoscopic configuration of the cameras and the venue needs to be configured with Venue/Create/installation_type: MultipleSides

2D ball and player tracking will be the default configuration (Venue/Create/installation_type: SingleSide, from: https://help.signality.com/api/#tag/Venues/operation/Create) and for consistency purposes will follow the same coordinate system as the 3D.

Managing the same venue with multiple camera configuration

In the case the same venue will have different camera configuration, video providers can create a second venue adding a different “installationType,” as mentioned above and sending the corresponding video streams for each venue created in the system.

Camera calibration changes

The new 3D ball tracking feature introduces a new calibration coordinate system which aligns with the tracking data output, having the centre of the pitch as the origin and the “z” axis pointing above the pitch.

Calibration coordinate system before data format version 6.x.x:

Calibration coordinate system from data format version 6.x.x:

Managing old and new games with different calibration systems

Both: new and old calibration system will be supported. Users can know which calibration system is used by validating the position of the reference landmarks. We recommend using the “R” landmark since it will be far away from the origin in the old calibration system and very close to the origin in the new calibration system. The next code illustrates how to implement the validation.

// Initialize R as landmark "R" from calibration reference landmarks in game
R = game.calibration.reference_landmarks.R

// Calculate the Euclidean distance between origin [0,0,0] and R
dist = calculateDistance([0,0,0], R)

// If dist is less than 5 then it is the new coordinate system
if dist < 5 then
    coordinateSystem = "New"
else
    // Otherwise, it is the old coordinate system
    coordinateSystem = "Old"
end if

Release 4.1.9

16-jan-23

• Support time_start in / CreateInstantGame endpoint: This feature will allow the processing of the video with the with the following logic:

- If there is not information provided about the if the field time_start is omitted from the request, the processing -of the video starts from the very beginning of the video. (This part is unchanged)

- if the request is submitted more than 10mn before kickoff, the deployment of processing pipeline is scheduled. Which means that the calibration refinement will be triggered as well

- otherwise, if game order is submitted between 5mn and 10 min before kickoff, the processing pipeline will be deployed right away to be ready at kickoff.

- otherwise, the processing pipeline is not going to be ready on time. In this scenario the pipeline will start the processing 30 seconds before kickoff. There will be a few additional constraints in that case: streams are required in the game order and can’t be submitted later, otherwise the game order is rejected streams must be “seekable”, which means old segments of the video are accessible. This can’t apply to “true” live streaming protocols such as RTSP and SRT

• New endpoint GameStatusCodes: This endpoint will allow to retrieve the full list of error codes and descriptions. The StatusCodes endpoint explains the status_code in the Games model.

• Support of 3-digit player numbers (from 0 to 999, formerly only supported from 1 to 99). This change impacts: TeamAwayLineup TeamAwayPlayers TeamHoimeLineup TeamHomePlayers Events Tracks

Release 4.1.0

CHANGELOG

• Specify semantic identification for IDs as uuid. Applies to venue, phase and game IDs.

• Remove obsolete properties from the Game model: team_home_formation, team_away_formation, team_home_logo and team_away_logo.

• Remove obsolete properties from the Phase model: time_start, time_end, team_home_redcards, team_home_substitutions, team_home_kickoff, team_home_is_left, team_away_redcards andteam_away_substitutions.

• Documentation readability improvement: regroup endpoints in 4 categories Games, Venues, Phases and User.

Release 4.0.0

NOTES

We recommend our users to use the version 4 of this API, which is now generally available. API Version 3 is still available, but from now on new features will be shipped in the version 4 only.

BREAKING CHANGES

• From API v4, authentication relies on JWT tokens. Therefore it’s now required to use the corresponding Bearer schema.

• Remove _ in endpoints GET|POST https://api.signality.com/v3/games/{id}/_streams, so it’s now https://api.signality.com/v4/games/{id}/streams

• API v4 proposes a different workflow to submit new calibrations. In API v3 it was required to first create a new calibration before submitting jpeg images, one image at a time. In API v4, there’s a single endpoint to submit images on new calibration requests using multipart/form-data. See https://help.signality.com/api/#operation/VenueCalibrationController.postCalibrationWithImages for details

IMPROVEMENTS

• While previous version relied on swagger, OpenAPI v3 is now supported by default. That should considerably improve the readibility and compliance of the specifications.

• Starting from version 4.0.0, the API service supports semantic versioning using url prefix, such as /v4.0.0/. Note that /v4/ would always redirect towards the most recent version of the API.

NEW FEATURES

• Phase model is accessible using its number property, in addition to phaseId. Example: GET /v4.0.0/games/<GAME_ID>/phases/1.

• For each data channel, tracks, events and stats, GET operations returned additional metadata in the HTTP header:

--- `ContentLength`: indicate the length of the body in bytes

--- `LastModified`: when data was last modified

--- `Version`: to indicate what's the version format of the data

--- `Stage`: `live` or `final`, for `tracks` channel only.

Those metadata fields can also be retrieved independently of the data itself, by using HEAD operations on the same endpoints, aka. HEAD https://api.signality.com/v4.0.0/games/{gameId}/phases/{phaseIdOrNumber}/tracks

Release 3.6.0

-- Add team_home_colors and team_away_colors properties to the Game model, an array of strings describing team jersey colors in hexadecimal notation

-- /instant, /request and /plan endpoints support team_home_colors and team_away_colors new properties

Release 3.5.0

-- new property status_code in Game model indicating the outcome (more detailed documentation will follow):

- 1XX: deployment failure, aka. lack of ressources
- 2XX: processing failure, aka. missing streams at kickoff, crash etc.
- 3XX: data innacuracy, aka. calibration being off, missing substitution etc.

Release 3.4.0

-- new property deployment_state in Game model to indicate the state of the processing pipeline:

"deployment_state": {
    "default": "WaitingForValidation",
    "enum": [
        "WaitingForValidation",
        "Manual",
        "Planned",
        "Deploying",
        "Deployed",
        "Destroying",
        "Destroyed"
    ],
    "description": "state of processing pipeline",
    "type": "string"
}

Release 3.3.0

New endpoints to manipulate calibrations

-- GET venues/{id}/calibrations to list calibrations of a venue

-- GET venues/{id}/calibrations/{fk} to get a specific calibration

-- POST venues/{id}/calibrations to create a new calibration

-- POST venues/{id}/calibrations/{fk}/image/{label} to upload a new image for an existing calibration

Improvements

-- endpoints /plan, /instant and /request support a new property calibrationId in request payload. If not specified, the most recent calibration is used. For a calibration to be valid, calibrationId must refer to an existing calibration of the venue and the calibration must have at least one element in _views. If condition is not met, an error 400 is returned.

Fixes

-- data_level type is now integer in openapi documentation

-- document request body for users/login

Breaking changes

-- change endpoint to create a new venue: POST venues (instead of POST venues/new) to match with naming convention

Release 3.2.0

-- data_level is now exposed in Game model

see Data levels for details

Release 3.1.0

-- new endpoint to create Venues /venues/new

-- new endpoint to submit still images from camera /venues/{id}/image/{label}

Release 3.0.0

-- initial API release

Data Serialization

visualize

Version 5.0.2

1. Change team possession to percentage in stats channel

Version 3.5.0

1. Add shot events
2. Add idx atttribute, a message counter per channel (tracks, stats and events) and type (applies to events only)

Version 3.4.0

1. Add free kick events

Version 3.3.0

1. Fix: PhaseState is one of start, running or end
2. Fix typo

Version 3.2.0

1. use int64 formt for utc time fields

Version 3.1.0

1. new flatten structure for event messages

Version 3.0.0

1. initial data serialization release