Skip to content

Home

Jump to bottom
Stephen Hurwit edited this page Jul 1, 2022 · 3 revisions

Welcome to the Sports Building Block wiki!

The Sports Building Block (Sports BB) is the service responsible for managing sports data in the Rokwire ecosystem. This Building Block is designed to support various data providers for sports content.

This Wiki provides an overview of the functionality included in the Sports Building Block. It includes the following sections:

Sports Data

The Sports BB primarily manages data about sport teams and events.

Sport Definition Model

Sport Definitions contain basic information about a given sport. All Sport Definitions can be retrieved using the GET /api/v2/sports endpoint.

Sport Definitions contain the following data:

Name Key Type Required Description Example
Name name string true The name of the sport for display purposes Women's Basketball
Short Name shortName string true A unique short name for the sport to be used as an identifier wbball
Custom Name custom_name string true A custom name that represents the sport type Basketball
Has Position hasPosition boolean true A flag indicating that the data provider includes the position of the team members on the roster true
Has Height hasHeight boolean true A flag indicating that the data provider includes the height of the team members on the roster true
Has Weight hasWeight boolean true A flag indicating that the data provider includes the weight of the team members on the roster false
Has Sort By Position hasSortByPosition boolean true A flag indicating that sorting the roster by position is supported true
Has Sort By Number hasSortByNumber boolean true A flag indicating that sorting the roster by player number is supported true
Has Scores hasScores boolean false A flag indicating that the data provider includes scores for games. Defaults to false if missing. true
Gender gender string true The gender of the team women
Ticketed ticketed boolean true A flag indicating that games for this sport are ticketed true
Icon icon string true Local path in app assets to the icon to display for this sport images/athletics-basketball-orange.png

News Model

The News model represents an article related to a sports team. News articles can be retrieved using the GET /api/v2/news endpoint.

The News model contains the following data:

Name Key Type Required Description Example
ID id string true The unique identifier generated by the system for this item. b1e06d21-6d07-4c53-9946-804e94f745f7
Title title string true The title of this article Women's Basketball Wins Championship Game
Link link string true A URL where the full article can be accessed https://www.example.com/sports/wbball/championship-win
Category category string true The category of this article Women's Basketball
Sport sport string true The Short Name of the sport to which this article is related wbball
Description description string true A short description of this article Women's Basketball has won the championship game
Full Text fulltext string true The HTML formatted full text of this article

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Duis pretium, erat a venenatis posuere, ex nulla vulputate eros, id dapibus justo ipsum sed nibh.

Praesent ante velit, egestas vitae lorem in, tristique finibus erat.
Full Text Raw fulltext_raw string true The raw HTML full text of this article

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Duis pretium, erat a venenatis posuere, ex nulla vulputate eros, id dapibus justo ipsum sed nibh.

Praesent ante velit, egestas vitae lorem in, tristique finibus erat.
Image URL image_url string true The URL of the image to be displayed with this article https://www.example.com/sports/wbball/championship-win/image
Published Date UTC pub_date_utc string true The date and time at which the article was published in the E, dd MMM yyyy HH:mm:ss v format Thu, 30 Jun 2022 14:08:00 GMT

Coach Model

The Coach model represents the coach of a Sports team. The Coaches for a specific sports team can be retrieved using the GET /api/v2/coaches endpoint.

Coach models contain the following data:

Name Key Type Required Description Example
ID id string true The unique identifier generated by the system for this item. 4d54bd1e-fc0f-403b-9a6f-8359291a35e5
Name name string false The full name of this coach Jane Doe
First Name first_name string false The first name of this coach Jane
Last Name last_name string false The last name of this coach Doe
Email email string false The email address of this coach [email protected]
Phone phone string false The phone number of this coach in the format xxx-xxx-xxxx 111-222-3333
Title title string false The job title of this coach 111-222-3333
Bio bio string false An HTML bio for this coach

Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Duis pretium, erat a venenatis posuere, ex nulla vulputate eros, id dapibus justo ipsum sed nibh.
Photos photos Photos false Photos of the coach

Player Model

Players represent the members of a Sports team. The Players for a specific sports team can be retrieved using the GET /api/v2/players endpoint.

Players contain the following data:

Name Key Type Required Description Example
ID id string true The unique identifier generated by the system for this item ad1ef533-b24a-4fb9-ba6e-07bc3523460b
Name name string false The full name of this coach Jane Doe
First Name first_name string false The first name of this coach Jane
Last Name last_name string false The last name of this coach Doe
Uni uni string false The email address of this coach [email protected]
Position pos_short string false The position of this player G
Height height string false The height of this player in the format ft-in 6-1
Weight weight string false The weight of this player 215
Gender gender string false The gender of this player F
Year year_long string false The school year of this player Sophomore
Home Town home_town string false The home town of this player Chicago, IL
High School highschool string false The high school that this player attended Example High School
Captain captain boolean false Flag indicating if this player is the team captain. Default is false if missing false
Bio bio string false An HTML bio for this coach

Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Duis pretium, erat a venenatis posuere, ex nulla vulputate eros, id dapibus justo ipsum sed nibh.
Photos photos Photos false Photos of the coach

Sport Social Network Model

Sport Social Networks include the identifiers for the social media accounts of a Sports team. The Sport Social Networks for a specific sports team can be retrieved using the GET /api/v2/social endpoint.

Sport Social Networks contain the following data:

Name Key Type Required Description Example
Short Name shortname string true The Short Name of the sport wbball
Twitter Name sport_twitter_name string false The Twitter handle (username) of this team ExampleTwitterHandle
Instagram Name sport_instagram_name string false The Instagram username of this team ExampleInstagramUser
Facebook Page sport_facebook_page string false The URL of the Facebook page for this team https://www.facebook.com/ExampleFacebookPage

Game Model

Games represent an individual sports game. Games can be retrieved using the GET /api/v2/game endpoint.

Games contain the following data:

Name Key Type Required Description Example
ID id string true The unique identifier generated by the system for this item 6fecc199-f48d-4b7f-97bb-778c92c5aac6
Date date string false The date of the game in the format d/M/yyyy 7/20/2022
Date Time UTC datetime_utc false true The DateTime of the game 2022-07-20T20:00:00Z
End Date end_date string false The end date of the game in the format d/M/yyyy 7/20/2022
End Date Time UTC end_datetime_utc string false The end DateTime of the game 2022-07-20T24:00:00Z
Time time string false The time of the game for display purposes 3 PM CT
All Day all_day boolean false A flag indicating that the game runs all day. Default is false if missing false
Status status string false The status of the game. Options include A (active), O (over), and C (cancelled) A
Description description string false A description of the game for display purposes Homecoming
Sport sport Game Sport false The Sport of this game
Location location Game Location false The Location of this game
Parking URL parking_url string false A URL that includes information on event parking for this game https://www.example.com/parking/events
Links links Game Links false The Game Links for this game
Opponent opponent Game Opponent false The Opponent for this game
Results results list (Game Result) false A list of Game Results for this game https://www.example.com/parking/events

Game Sport Model

Game Sports are references to a Sport for use in the Game model. Game Sports contain the following data:

Name Key Type Required Description Example
Title title string false The name of the sport for display purposes Women's Basketball
Short Name shortname string false The Short Name of the sport wbball

Game Location Model

Game Locations represent locations where a Game is taking place. Game Locations contain the following data:

Name Key Type Required Description Example
Location location string false The name of the location for display purposes Chicago, IL
HAN HAN string false Indicator if this is a home (H), away (A), or neutral (N) game A

Game Links Model

Game Links include relevant links for a Game. Game Links include the following data:

Name Key Type Required Description Example
Livestats livestats string false The URL where Live Stats for this game can be accessed https://www.example.com/livestats/6fecc199-f48d-4b7f-97bb-778c92c5aac6
Video video string false The URL where a video stream of this game can be accessed https://www.example.com/video/6fecc199-f48d-4b7f-97bb-778c92c5aac6
Audio audio string false The URL where an audio stream of this game can be accessed https://www.example.com/video/6fecc199-f48d-4b7f-97bb-778c92c5aac6
Tickets tickets string false The URL tickets for this game can be purchased https://www.example.com/tickets/6fecc199-f48d-4b7f-97bb-778c92c5aac6
PreGame pregame Game Info false The pre-game [Game Info] for this game

Game Info Model

Game Info models represent a news story about a Game. Game Info models include the following data:

Name Key Type Required Description Example
ID id string true The unique identifier generated by the system for this item ff799598-be42-4e4e-aa9a-f14e8ae6a5af
URL url string false The URL where info about this story can be accessed https://www.example.com/game-news/ff799598-be42-4e4e-aa9a-f14e8ae6a5af
Story Image URL story_image_url string false The URL where an image for this story can be accessed https://www.example.com/images/ff799598-be42-4e4e-aa9a-f14e8ae6a5af
Text text string false The text of the story Lorem ipsum dolor sit amet, consectetur adipiscing elit. Duis pretium, erat a venenatis posuere, ex nulla vulputate eros, id dapibus justo ipsum sed nibh.

Game Opponent Model

Game Opponents represent the opponent of the team in a specific Game. Game Opponents include the following data:

Name Key Type Required Description Example
Name name string false The name of the opponent Example Opponent Team
Logo Image logo_image string false A URL for the logo of the opponent team https://www.example.com/logos/example-opponent-team

Game Results Model

Game Results represent the results of a Game. Game Results include the following data:

Name Key Type Required Description Example
Status status string false The status of the results. Options include W (won), L (lost), and N (n/a) Example Opponent Team
Team Score team_score string false The score of the team in this game 5
Opponent Score opponent_score string false The score of the opponent in this game 2

Photos Model

Photos include links to a photo at different sizes for display purposes. Photos include the following data:

Name Key Type Required Description Example
Full Size fullsize string false The URL of the full-sized photo https://www.example.com/photos/example-photo/full
Thumbnail thumbnail string false The URL of a thumbnail of the photo https://www.example.com/photos/example-photo/thumbnail

Team Schedule Model

Team Schedules represent the list of games scheduled for a Sports team. Team Schedules can be retrieved for a specific sports team using the GET /api/v2/team-schedule endpoint.

Team Schedules include the following data:

Name Key Type Required Description Example
Label label string false The label for this schedule, usually the year(s) 2021-22
Games games list (Game) false The list of games in this schedule

Team Record Model

Team Records represent the record for a specific Sports team. Team Records can be retrieved for a specific sports team using the GET /api/v2/team-record endpoint.

Team Records include the following data:

Name Key Type Required Description Example
Overall Record overall_record_unformatted string false The overall record for the team 7-20
Conference Record conference_record string false The conference record for the team 1-13
Streak streak string false The streak for the team L1
Home Record home_record string false The home record for the team 6-9
Away Record away_record string false The away record for the team 0-8
Neutral Record neutral_record string false The neutral for the team 1-3

Live Stats

The Sports BB provides Live Stats updates by sending notifications when changes occur for games that are currently in progress. To retrieve currently live games, users can send a request to the GET /api/v2/live-games endpoint to retrieve the Live Games. The Sports BB will send notifications about updates to Live Games through the Notifications Integration.

Live Game Model

Live Games represent sports games that are currently in progress. Live Games contain the following data:

Name Key Type Required Description Example
Game ID GameId string true The unique identifier for the game 123456789
Path Path string true The Short Name for the sport of this game baseball
Has Started HasStarted boolean true Flag indicating that the game has started true
Is Complete IsComplete boolean true Flag indicating that the game is over false
Clock Seconds ClockSeconds string true Seconds remaining on the clock 10
Period Period string true The current period of the game 6
Home Score HomeScore string true The current score of the home team 5
Visiting Score VisitingScore string true The current score of the visiting team 2
Custom Custom string false Custom game data (eg. sport-specific details)

Configs

The Sports BB supports the configuration of Live Stats sources and Notifications through the PUT /api/v2/config for admins. These Configs are JSON encoded and contain the following data:

  • livestats_source: This field allows for the configuration of the Data Providers for the Live Stats of each Sport
  • {sport}_config: Sport-specific configs for supported sports including football, mbball, wbball, wvball
    • phases: Mapping of phase codes to display names
    • last_play_enabled: Boolean flag indicating if the "last play" feature is enabled for this sport
    • xml_date_check: Boolean flag indicating if the date of the XML feed should be checked to ensure it is for the current game
  • notification_config: Configs for Notifications
    • messages: Configs for Notification Messages
      • game_ended_msg: Title of message notifications to be sent when games end
      • game_ended_score_format: Format of the score to include in message notifications sent when games end
      • game_started_msg: Title of message notifications to be sent when games start
      • game_title_format: Format of the title of the game to be shown in message notifications

An example of these configs can be seen below:

{
    "livestats_source": {
        "baseball": {
            "away": ["sidearm"],
            "home": ["sidearm"]
        },
        "football": {
            "away": ["sidearm"],
            "home": ["xml_feed", "sidearm"]
        },
        "mbball": {
            "away": ["sidearm"],
            "home": ["xml_feed", "sidearm"]
        },
        "mten": {
            "away": ["sidearm"],
            "home": ["sidearm"]
        },
        "softball": {
            "away": ["sidearm"],
            "home": ["sidearm"]
        },
        "wbball": {
            "away": ["sidearm"],
            "home": ["xml_feed", "sidearm"]
        },
        "wsoc": {
            "away": ["sidearm"],
            "home": ["sidearm"]
        },
        "wten": {
            "away": ["sidearm"],
            "home": ["sidearm"]
        },
        "wvball": {
            "away": ["sidearm"],
            "home": ["xml_feed", "sidearm"]
        }
    },
    "football_config": {
        "phases": {
            "1": "1st Quarter",
            "2": "2nd Quarter",
            "3": "3rd Quarter",
            "4": "4th Quarter",
            "final": "Final Score",
            "ht": "Half Time",
            "ot": "Over Time",
            "pre": "Pregame"
        },
        "last_play_enabled": true,
        "xml_date_check": true
    },
    "mbball_config": {
        "phases": {
            "1": "1st Half",
            "2": "2nd Half",
            "final": "Final Score",
            "ot": "Over Time",
            "pre": "Pregame"
        },
        "last_play_enabled": false,
        "xml_date_check": true
    },
    "wbball_config": {
        "phases": {
            "1": "1st Quarter",
            "2": "2nd Quarter",
            "3": "3rd Quarter",
            "4": "4th Quarter",
            "final": "Final Score",
            "ot": "Over Time",
            "pre": "Pregame"
        },
        "last_play_enabled": false,
        "xml_date_check": true
    },
    "wvball_config": {
        "phases": {
            "final": "Final Score",
            "game_name": "Set",
            "pre": "Pregame"
        },
        "xml_date_check": true
    },
    "notification_config": {
        "messages": {
            "game_ended_msg": "The Game had ended.",
            "game_ended_score_format": "Score %[1]s %[2]d : %[3]s %[4]d",
            "game_started_msg": "The Game has started",
            "game_title_format": "%[1]s vs %[2]s"
        }
    }
}

Integrations

Rokwire Integrations

Notifications

The Sports BB integrates with the Notifications Building Block to send notifications to clients.

Data Notifications

Data Messages about Live Stats updates. The Data field of the message will be populated with the latest Live Game data.

Message Notifications

Notification Messages will also be sent for key events during the game including the game starting and ending. The content of these messages can be configured in the Configs.

Notification Topics

These messages will be sent to a Topic for the sport of the game being tracked, where the Name of the Topic will be the Short Name of the sport. Clients may then subscribe to this topic to receive a notification about updates to the Live Stats.

Notification Configurations

To enable this integration the following environment variables must be configured:

  • SS_INTERNAL_API_KEY: The internal API key to be authenticated by the Notifications BB

External Integrations

Data Providers

The Sports BB integrates with external systems as data providers.

SIDEARM Sports

SIDEARM Sports is a content management system for sports data used by many Universities. The Sports BB integrates with SIDEARM as a data source to provide all of the Sports Data and Live Stats described above.

XML Feed

The Sports BB also integrates with XML feeds for Live Stats provided through an FTP server. To enable this integration, the following environment variables must be configured:

  • XML_FEED_FTP_HOST: The FTP server's host for the XML feed
  • XML_FEED_FTP_USER: The user for the FRP server of the XML feed
  • XML_FEED_FTP_PASSWORD: The user's password for the FTP server of the XML feed
Clone this wiki locally