Liveblog Sports Event

Sport liveblogs have special data structures to:

• display events like goals, penalties, etc.
• connect those events to teams and players
• display the time of play the event occurred

This page documents the structure both for writing sport events through the API and for reading them, e.g. when rendering a liveblog with your own frontend instead of the Tickaroo web embed.

SportEventContentBlock

To describe all those purposes, the sport_event field of an Event must be filled with a Tik::Model::Content::SportEventContentBlock object.

"sport_event": {
  "_type": "Tik::Model::Content::SportEventContentBlock",
  // ID of the content block
  // since there is only one sport_event per event it can be any value
  "local_id": "",

  // the sportstype this event is for (soccer, icehockey)
  "sportstype": "",

  // the event type that happened
  "event_type": "",

  // Optional: a title displayed along the event
  "title": "",

  // Optional: the team this event refers to
  "team": {},

  // Optional: Tik::Model::Content::SportEventPlayer[]
  // players involved in this event
  "players": [],

  // Optional: The Game Phase to display
  "phase": {
    "_type": "Tik::Model::Content::SportPhase",
    // Full display name, for example "2nd Half"
    "name": "",
    // Optional: short display name for constrained layouts, for example "HT2"
    "short_name": ""
  },

  // Optional: text to display representing the current time or game phase
  // for example "32'" to signify 32. Minute of the game
  "time_of_play": "",

  // Optional: true if the event was revoked after the fact,
  // for example a goal overturned by video review.
  // Renderers should display the event as cancelled (e.g. struck through),
  // not hide it.
  "is_cancelled": false
}

Specifying sportstype and event_type

The sportstype must be set to a valid sports type (Appendix A).

The event type must be set to a valid event type (Appendix B), for all types are listed at the end of this document. The specified event_type will in most cases match the sportstype, but in practice any event type can be used in any sports allowing for great flexibility of our templates.

Depending on the event_type, other fields can be set:

• team: Some events allow to specify which team is affected. Refer to the event types table to see which event allows for that.
• players: Some events allow to specify one or multiple players involved in this event. Refer to the event types table to see which events allow players to be specified

Note for renderers: in real liveblogs — especially games imported from external data providers — a SportEventContentBlock can arrive without an event_type, carrying only time_of_play (and possibly phase). Your renderer must tolerate such blocks; the Tickaroo web embed shows the time of play and renders no event body in that case.

Adding the team

While the actual team object has more fields, only the following are used when writing events:

"team": {
  "_type": "Tik::Model::Team",

  // The id of the team, if it already exists
  "_id": "",

  // The display name of the team
  "name": ""
}

When reading events, the embedded team typically carries additional fields, e.g.:

"team": {
  "_type": "Tik::Model::Team",
  "local_id": "",
  "name": "Spanien",
  // Optional: short display name for constrained layouts
  "short_name": "",
  // Optional: team logo, see "Displaying player and team images" below
  "image": "",
  "sportstype": "soccer"
}

Teams can either be precreated or added on-the-fly.

Using a predefined team

Only _type and _id need to be set

"team": {
  "_type": "Tik::Model::Team",
  "_id": ""
}

After the event object has been created, the response will contain the full team information.

For more information on creating teams before using them please refer to the Teams API Documentation.

Creating a team on the fly

Only _type and name need to be set.

"team": {
  "_type": "Tik::Model::Team",
  "name": ""
}

The team will be created with the specified name and assigned an _id. The response, after the event has been created, will contain a full team object including the new id.

Adding involved players

Players will be displayed in the order they are specified in the array. Each entry is wrapped in a Tik::Model::Content::SportEventPlayer object.

{
  "_type": "Tik::Model::Content::SportEventPlayer",

  // The type of the involvement of the player in the event (example 'scorer')
  // Valid types for each event can be found in the Appendix B Table
  "event_player_type": "",

  // Displayed type of the involvement of the player in the event (example 'Scorer')
  "event_player_title": "",

  // The actual Tik::Model::Player object
  "player": {}
}

event_player_type vs event_player_title

The two fields serve different purposes:

• event_player_type is the stable, locale-independent key. Use it in your renderer for icons, styling and grouping — it is always one of the values in the table below, regardless of the liveblog’s language.
• event_player_title is the display label, already localized in the liveblog’s locale. Display it as-is; do not translate the type yourself.

For example, a goal in a German-language liveblog contains:

{
  "_type": "Tik::Model::Content::SportEventPlayer",
  "event_player_type": "scorer",
  "event_player_title": "Torschütze",
  "player": { ... }
}

Player involvement types

These are all event_player_type values that can occur. Which types are used by which event is listed in Appendix B.

Player fields when reading events

When reading events, each embedded player is a full Tik::Model::Player. All fields, their units and notes for displaying them are documented in the Player API Documentation.

Using a predefined player

Only _type and _id need to be set

"player": {
  "_type": "Tik::Model::Player",
  "_id": ""
}

After the event object has been created, the response will contain the full player information.

For more information on creating players before using them please refer to the Player API Documentation.

Creating a player on the fly

Only _type and name need to be set.

"player": {
  "_type": "Tik::Model::Player",
  "name": ""
}

The player will be created with the specified name and assigned an _id. The response, after the event has been created, will contain a full player object including the new id.

Displaying player and team images

The image field of players and teams contains one of two kinds of references:

• an absolute HTTPS URL (typical for games imported from external sports data providers) — can be used directly, e.g. "https://s.hs-data.com/gfx/person/cropped/250x250/475490.png"
• an imageservice:// URI (Tickaroo-managed players and teams) — not directly fetchable, e.g. "imageservice://media/organization/…/player/…/image/….png"

To display (and resize or crop) an imageservice:// URI, use the Tickaroo Image Service documented in the Media Documentation. The Image Service also accepts HTTPS URLs, so you can route all images through it for uniform sizing.

Appendix A: Sportstype Table

Appendix B: Event Types Table