Game

Accessing a game list that you can report on

  curl -v -v  \
    "http://127.0.0.1:5000/bo/games?set=game_report&auth_token=TOKEN"

Access to a single game

Displays a comprehensive list of game details including referees, scores, game events and the lineup.

  curl -v -v  \
    "http://127.0.0.1:5000/bo/games/812625?set=game_report&auth_token=TOKEN"

Response

• list:
  • phases: List of phases that will be played in this game (e.g ['third1', 'third2', 'third3', 'prolongation', 'penalty_shootout']),
  • spectators Number of spectators.
  • total_seconds_played Game playtime duration in seconds.
  • player_inspection_ordered Whether a player inspection has been ordered.
  • started_at_worldtime When the game started playing (time of last start event, see status).
  • finished_at_worldtime When the game finished playing (time of last game_over event, see status).
  • penalty_shootout_played Whether a penalty shootout has been played.
  • prolongation_played Whether the prolongation has been played.
• references:
  • positions/…: Lineup positions.
    • topscorer: Whether or not the player is the highest scoring player in the lineup according to the current mobiliar ranking.
  • events/…: Events that happened during the game
    • when .type = Event, .subtype = PlayerInspection
      • attrs.done Whether the player inspection was performed. If this is false, the inspection was intentionally skipped.

Creating a lineup

  curl -H "Content-Type: application/json" -X PUT \
    -d "{\"positions\":[{\"player_id\":423520, \"captain\":\"yes\", \
    \"number\":\"13\"},{\"player_id\":433056}],\"auth_token\":\"TOKEN\"}" \
    "http://127.0.0.1:5000/bo/games/852878/lineups/428977"

You may provide license_ids instead of player_ids to specify the players.

Handling of position numbers

• If no number is given, and the system knows the shirt number the player usually wears, the position will default to said number.
• The system will remember the shirt number assigned to a player to provide the functionality above if it doesn't yet know a number for the player. You may prevent the system from remembering the shirt number used in a position by specifying do_not_remember_number: 'yes' for the position

Events

Creating an event for a game

Issue a POST request to /bo/games/:game_id/events.

There are 7 game events.

• Goal
• Penalty
• Penalty End
• Team
• Player
• Misc (miscellanous non-sportive events that may occur during a game)
• PlayerInspection

Each type needs a different set of attributes with the request to be created.

Goal (Adding a goal to a game)

Request attribute set:

• category_id: 1
• time: Time of the goal in game time relative to the start of the game.
• world_time: Absolute time of the event in format 'YYYY-MM-DDThh:mm:ss+hh:mm', e.g. '2015-10-28T12:34:45+01:00'
• team_id: ID of the team that made the goal.
• player_id: ID of the player who made the goal.
• assister_id: ID of the player who assisted (optional).

  curl -X POST -v -v  \
    "http://127.0.0.1:5000/bo/games/812625/events" \
    -d 'time=0:23:00' \
    -d 'world_time=2015-10-28T12:34:45+01:00' \
    -d "category_id=1" -d "player_id=413841" \
    -d "assister_id=463912" -d "team_id=429631" \
    -d 'auth_token=TOKEN'

Game Penalty (Straffstoss)

A GamePenalty event has the same attributes a s Goal event, with the following differences: * category_id: 164, other than that same attributes as Goal event * no assister_id

Penalty

There are 17 penalty events:

Attributes:

• category_id: One of 3-9, 153-158, 161, 162, 167.
• code: Optional. A penalty code from 0-999. See "Codes"
• time: Time of the penalty event in game time relative to the start of the game.
• world_time: Absolute time of the event in format 'YYYY-MM-DDThh:mm:ss+hh:mm', e.g. '2015-10-28T12:34:45+01:00'
• game_id: ID of the game.
• team_id: ID of the team the player is in.
• player_id: ID of the player who got the penalty.

  curl -X POST -v -v  \
    "http://127.0.0.1:5000/bo/games/812625/events" \
    -d 'time=0:42:00' \
    -d "category_id=3" -d "team_id=429631" -d "player_id=413841" \
    -d 'auth_token=TOKEN'

Penalty End

Records a players' last penalty as having ended.

Attributes:

• category_id: 151.
• time: Time of the penalty event in game time relative to the start of the game.
• world_time: Absolute time of the event in format 'YYYY-MM-DDThh:mm:ss+hh:mm', e.g. '2015-10-28T12:34:45+01:00'
• game_id: ID of the game.
• team_id: ID of the team the player is in.
• player_id: ID of the player who got the penalty.

  curl -X POST -v -v  \
    "http://127.0.0.1:5000/bo/games/812625/events" \
    -d 'time=0:42:00' \
    -d "category_id=151" -d "team_id=429631" -d "player_id=413841" \
    -d 'auth_token=TOKEN'

Team

There are 4 team events:

Attributes:

• category_id: One of 10,11,15,16.
• time: Time of the team event in game time relative to the start of the game.
• world_time: Absolute time of the event in Format 'YYYY-MM-DDThh:mm:ss+hh:mm', e.g. '2015-10-28T12:34:45+01:00'
• game_id: ID of the game.
• team_id: ID of the team.

  curl -X POST -v -v  \
    "http://127.0.0.1:5000/bo/games/812625/events" \
    -d 'world_time=2015-10-28T12:34:45+01:00' \
    -d 'time=0:42:00' \
    -d "category_id=10" -d "team_id=429631" \
    -d 'auth_token=TOKEN'

Player

There are 7 player events:

Attributes:

• category_id: One of 12-14,17-20,29.
• time: Time of the player event in game time relative to the start of the game.
• world_time: Absolute time of the event in Format 'YYYY-MM-DDThh:mm:ss+hh:mm', e.g. '2015-10-28T12:34:45+01:00'
• team_id: ID of the team the player is in.
• player_id: ID of the player.

  curl -X POST -v -v  \
    "http://127.0.0.1:5000/bo/games/812625/events" \
    -d 'world_time=2015-10-28T12:34:45+01:00' \
    -d 'time=0:42:00' \
    -d "category_id=20" -d "team_id=429631" -d "player_id=413841" \
    -d 'auth_token=TOKEN'

Misc

Attributes:

• category_id: 39.
• code: The code from 0-999 detailing which kind of miscellanous event happened. See "Codes"
• time: Time of the player event in game time relative to the start of the game.
• world_time: Absolute time of the event in Format 'YYYY-MM-DDThh:mm:ss+hh:mm', e.g. '2015-10-28T12:34:45+01:00'
• player_id: ID of the player (optional).

    curl -X POST -v -v \
    "http://127.0.0.1:5000/bo/games/852878/events" \
    -d 'time=0:23:00' \
    -d 'world_time=2015-10-28T12:34:45+01:00' \
    -d "category_id=39" \
    -d "code=123" \
    -d "auth_token=TOKEN"

PlayerInspection

Store the fact that a player inspection was performed or intentionally skipped.

Attributes:

• category_id: 165 if the inspection was done, 166 if it was skipped.
• time: Time of the player event in game time relative to the start of the game.
• world_time: Absolute time of the event in Format 'YYYY-MM-DDThh:mm:ss+hh:mm', e.g. '2015-10-28T12:34:45+01:00'

    curl -X POST -v -v \
    "http://127.0.0.1:5000/bo/games/852878/events" \
    -d 'time=0:00:00' \
    -d 'world_time=2015-10-28T12:34:45+01:00' \
    -d "category_id=165" \
    -d "auth_token=$TOKEN"

Codes

A list of accepted event codes is maintained in Opacc, contact swiss unihockey to get the latest valid codes.

• OpaccERP, BC 87700, Table 501, "Strafencodes/ Event-Codes"
• OXAS Business-Server, Service "GEvents", see Documentation "su neue Anwendungen OpaccXOAS"

Deleting an event of a game

Issue a DELETE request to /bo/games/:game_id/events/:event_id.

• game_id: ID of the game the event is part of.
• event_id: ID of the event to be deleted.

  curl -X DELETE -v -v  \
    "http://127.0.0.1:5000/bo/games/812625/events/1080631"
    -d 'auth_token=TOKEN'

Status

Setting status of a game

You can send the game any of these messages:

• start
• start_third
• end_third
• report_result
• game_over
• start_penalty_shootout
• forfait
• abort
• undo

(Open big version)

Valid messages

The state diagram illustrates when it may be legal to send what message. Which messages are usable depends on the game phases - if a game doesn't have a third third, you won't be able to start it. If a game has three thirds, you won't be able to start prolongation when in the second third.

The game information page will display the messages that can be sent to the game at any given time, taking the games' phases into account (see "Access to a single game", response description).

Sending a message

Here's how the typical status json message looks:

{
  "event": "start", 
  "second": 0, 
  "auth_token": "TOKEN"
}

Here's how this message would look when dispatching through 'curl':

  curl -H "Content-Type: application/json" -X PUT \
    -d "{\"auth_token\":\"TOKEN\",\
    \"second\":0,\"event\":\"start\"}" \
    "http://127.0.0.1:5000/bo/games/852878/status"

Note that throughout the API, PUT and POST messages can be sent using a 'Body' with the content type 'application/json'. This might be easier to do in your framework than url-encoded POSTs. Also, some messages that are deeply nested can only be formulated as url-encoded message with difficulty.

Depending on the message you're sending, more attributes need to be attached:

Event "start"

event: "start", No additional attributes. See above.

Event "start_third"

event: "start_third", No additional attributes. See above.

Event "end_third"

event: "end_third", No additional attributes. See above.

Event "start_penalty_shootout"

event: "start_penalty_shootout", No additional attributes. See above.

Event "forfait"

{
  "event": "forfait", 
  "second": 13, 
  "auth_token": "TOKEN", 
  "winner": "home"
}

Reports the game as being forfaited, with the home team carrying the win.

Event "game_over"

The game ended, no more playing is going on.

{
  "event": "game_over", 
  "second": 4200, 
  "auth_token": "TOKEN"
}

Event "report_result"

A typical message looks like this:

{
  "event": "report_result", 
  "auth_token": "TOKEN", 
  "home": 3, 
  "away": 4,
  "spectators": 230,
  "second": 3600,
  "penalty_shootout": "yes", 
  "prolongation": "yes"
}

This reports the game as finished after an hour of effective play time, 3:4. 230 people spectated. Penalty shootout and prolongation fields are important mostly when the game is reported as finished directly from the start node, without reporting intermediate game states.

Event "abort"

event: "abort", No additional attributes.

Event "undo"

The undo event will undo the last status change.

An example scenario:

1. Game is in first third.
2. Call to /bo/games/:id/status with start_third, putting game in the second third
3. Record a goal via /bo/games/:id/events
4. Call to /bo/games/:id/status with undo

The game will now again be in the first third. Events recorded in the second third (such as the goal in 3.) are deleted.

The payload looks like this:

{
  "event": "undo", 
  "auth_token": "TOKEN" 
}

To reduce visual clutter, this event is not represented in the state diagram above.

Modifying past state transitions

You may modify a transition that already happened - as of now, this is limited to modifying the second it happened at.

To do this, you issue a PUT to /bo/:game_id/status/history/transitions

Parameters:

• to: Name of the state the game changed to. Any of the state names in the state diagram shown in the section Setting status of a game. See table below for their names.
• second: An integer. New value for the second the event happened at.

Limitations:

You may not change the starting time for any of the thirds (as they're fixed by the rules to start at 0:00, 20:00 and 40:00).

Example:

Change the penalty shootout to have started 1 hour into the game:

curl -X PUT -v -v \
  "http://127.0.0.1:5000/bo/games/854222/status/history/transitions" \
  -d 'second=3600' \
  -d 'to=penalty_shootout' \
  -d "auth_token=$TOKEN"