Help Center

Resource: Game

Resource: Game

Data Elements

Name Read Only Required Type Length Notes
id Yes Number assignr.com primary key
start_time Yes String RFC-822 Date Format, local time zone
end_time Yes String RFC-822 Date Format, local time zone
localized_date Yes String Localized game date in local time zone
localized_time Yes String Localized game start time in local time zone
lock_version Yes Number Optional, used for optimistic locking
created_at Yes String RFC-822 Date Format, local time zone
updated_at Yes String RFC-822 Date Format, local time zone
is_public Number 0 = unpublished (default), 1 = published
status Yes String A = active (default), X = canceled with pay, C = canceled without pay
user_defined_id String Game ID field, visible in application
external_id Number Not used by assignr.com, you can use this however you want
longitude Yes Number as a decimal, East = positive, West = negative
latitude Yes Number as a decimal, North = positive number, South = negative number
home_team_id Yes Number
home_team_name Yes String 90 Find or Create
away_team_id Yes Number
away_team_name Yes String 90 Find or Create
game_type_id Number
game_type_name String 90 Find or Create
league_id Number
league_name String 90 Find or Create
venue_id Number
venue_name String 90 Find or Create
age_group_id Yes Number
age_group_name Yes String 90 Find or Create
gender_id Number
gender_name String 90 Find or Create
pattern_id Yes Number
pattern_name Yes String 90 Find only (will not create a new pattern without an exact match)
published_comment String 1000
unpublished_comment String 1000
existing_assignments Repeating Element
  id Yes Number assignr.com primary key for assignment
  lock_version Yes Number Optimistic Locking
  position_name Yes String Name of position
  updated_at Yes String RFC-822 Date Format, local time zone
  user_id Number User ID of the assigned referee
  name Yes String Name of the assigned referee
  sort_order Yes Number Sort order of assignment record

Notes

  • When a new game is created, corresponding records for Teams, Game Types, Venues, Leagues, and Genders will be created as needed.
  • For all of the "Find or Create" fields, you may change the ID field, or the name field, but not both.
  • The officiating pattern is not a "Find or Create" field. If pattern_name or pattern_id is specified, and it matches an existing pattern, the game will be created. Otherwise, the game will not be created, since the pattern is a required field.
  • The is_public and status field are required, however, if they are omitted, they will automatically be set to their respective default values.
  • localized_date and localized_time accept a wide variety of date formats. We use the chronic library to parse the date and time. Many different date formats are acceptable:

    • Date Formats: 3/14, 3/14/2011, 2011-03-14, March 14, "March 14, 2011", Mar 14
    • Time Formats: 3:00 PM, 15:00, 3pm, 3:00pm, 3:00 pm
  • To ensure that the date and time are transmitted in an unambiguous manner, we recommend the following date / time format (example shown is March 14, 2011, 1:30pm):

    • Date: 2011-03-14
    • Time: 13:30

Notification Triggers

  • A change in published status (is_public) from unpublished to published will send any unsent referee notifications.
  • A change in published status (is_public) from published to unpublished will, from a referee’s perspective, remove the game from their schedule. They will be notified that they have been removed from the game.
  • Any change in localized_date, localized_time, or venue_id / venue_name will trigger notifications AND will require the referee to re-confirm the game.
  • To cancel a game, change the status field from Active ("A") to either Canceled With Pay ("X") or Canceled Without Pay ("C"). This will trigger notifications to all assigned referees.
  • A change in an unpublished game will not trigger any notifications.
  • A change to a game occurring in the past will also not trigger any notifications.

Validations

  • Each game must be unique with respect to date, time, venue, and active/canceled status.
  • A referee may not be assigned to more than one position for a given game.
  • The user_defined_id field is an alphanumeric field that is visible from within assignr.com. It is an optional field, but if it is provided, it must be unique for the given site.
  • The external_id field is a numeric field that you may use for any purpose. If you are linking assignr.com to a game scheduling service, you may use this field to store your corresponding game primary key in this field.
  • A change of officiating pattern cannot "bump out" an assigned referee. For example, if a game has a pattern that requires two officials, and both positions are assigned, the pattern cannot be changed to a pattern that only requires one referee.

Retrieve a list of games (INDEX)

Return a paginated list of games. Limit is 50 games per request.

Sample Response: GET /games.xml

<?xml version="1.0" encoding="UTF-8"?>
<games>
  <game>
    <id>26845</id>
    <start_time>Sat, 06 Mar 2010 08:00:00 -0500</start_time>
    <end_time>Sat, 06 Mar 2010 08:59:00 -0500</end_time>
    <localized_date>Mar 6 2010</localized_date>
    <localized_time>8:00 AM</localized_time>
    <lock_version>0</lock_version>
    <created_at>2010-03-12 11:46:56 -0500</created_at>
    <updated_at>2010-03-12 11:46:56 -0500</updated_at>
    <is_public>0</is_public>
    <status>A</status>
    <user_defined_id/>
    <external_id/>
    <longitude/>
    <latitude/>
    <home_team_name>Arizona Rush 94 Swoosh</home_team_name>
    <home_team_id>27249</home_team_id>
    <away_team_name>TVSC Premier 94</away_team_name>
    <away_team_id>27250</away_team_id>
    <game_type_name>Youth</game_type_name>
    <game_type_id>15</game_type_id>
    <league_name>Pima Cup</league_name>
    <league_id>227</league_id>
    <venue_name>Port Evangeline Church</venue_name>
    <venue_id>3575</venue_id>
    <age_group_name>U 17 </age_group_name>
    <age_group_id>2032</age_group_id>
    <gender_name>Girls</gender_name>
    <gender_id>228</gender_id>
    <pattern_name>5 officials</pattern_name>
    <pattern_id>18</pattern_id>
    <published_comment>This is a comment everyone can see</published_comment>
    <unpublished_comment>This is a comment only assignors can see</unpublished_comment>        
    <existing_assignments>
      <id>61167</id>
      <lock_version>0</lock_version>
      <position_name>Referee</position_name>
      <user_id/>
      <name/>
      <updated_at/>
      <sort_order>1</sort_order>
    </existing_assignments>
    <existing_assignments>
      <id>61168</id>
      <lock_version>0</lock_version>
      <position_name>Umpire</position_name>
      <user_id/>
      <name/>
      <updated_at/>
      <sort_order>2</sort_order>
    </existing_assignments>
    <existing_assignments>
      <id>61169</id>
      <lock_version>0</lock_version>
      <position_name>Head Linesman</position_name>
      <user_id/>
      <name/>
      <updated_at/>
      <sort_order>3</sort_order>
    </existing_assignments>
    <existing_assignments>
      <id>61170</id>
      <lock_version>0</lock_version>
      <position_name>Line Judge</position_name>
      <user_id/>
      <name/>
      <updated_at/>
      <sort_order>4</sort_order>
    </existing_assignments>
    <existing_assignments>
      <id>61171</id>
      <lock_version>0</lock_version>
      <position_name>Back Judge</position_name>
      <user_id/>
      <name/>
      <updated_at/>
      <sort_order>5</sort_order>
    </existing_assignments>
  </game>
  <game>
    <id>26639</id>
    <start_time>Sat, 06 Mar 2010 08:00:00 -0500</start_time>
    <end_time>Sat, 06 Mar 2010 08:59:00 -0500</end_time>
    <localized_date>Mar 6 2010</localized_date>
    <localized_time>8:00 AM</localized_time>
    <lock_version>1</lock_version>
    <created_at>2010-03-12 11:46:11 -0500</created_at>
    <updated_at>2010-09-21 21:28:21 -0400</updated_at>
    <is_public>0</is_public>
    <status>A</status>
    <user_defined_id/>
    <external_id/>
    <longitude/>
    <latitude/>
    <home_team_name>U10C THUNDERCATS</home_team_name>
    <home_team_id>27122</home_team_id>
    <away_team_name>Region 1 Wizards</away_team_name>
    <away_team_id>27119</away_team_id>
    <game_type_name>Youth</game_type_name>
    <game_type_id>15</game_type_id>
    <league_name>Pima Cup</league_name>
    <league_id>227</league_id>
    <venue_name>Port Paxton Church</venue_name>
    <venue_id>3557</venue_id>
    <age_group_name>U 10</age_group_name>
    <age_group_id>2024</age_group_id>
    <gender_name>Boys</gender_name>
    <gender_id>229</gender_id>
    <pattern_name>5 officials</pattern_name>
    <pattern_id>18</pattern_id>
    <existing_assignments>
      <id>60137</id>
      <lock_version>1</lock_version>
      <position_name>Referee</position_name>
      <user_id>1992</user_id>
      <name>Jakubowski, Manuel</name>
      <updated_at>Tue, 28 Feb 2012 23:02:00 -0500</updated_at>
      <sort_order>1</sort_order>
    </existing_assignments>
    <existing_assignments>
      <id>60138</id>
      <lock_version>1</lock_version>
      <position_name>Umpire</position_name>
      <user_id>7276</user_id>
      <name>Huels, Rahsaan</name>
      <updated_at>Tue, 28 Feb 2012 23:02:00 -0500</updated_at>
      <sort_order>2</sort_order>
    </existing_assignments>
    <existing_assignments>
      <id>60139</id>
      <lock_version>1</lock_version>
      <position_name>Head Linesman</position_name>
      <user_id>7287</user_id>
      <name>Ratke, Micheal</name>
      <updated_at>Tue, 28 Feb 2012 23:02:00 -0500</updated_at>
      <sort_order>3</sort_order>
    </existing_assignments>
    <existing_assignments>
      <id>60140</id>
      <lock_version>0</lock_version>
      <position_name>Line Judge</position_name>
      <user_id/>
      <name/>
      <updated_at/>
      <sort_order>4</sort_order>
    </existing_assignments>
    <existing_assignments>
      <id>60141</id>
      <lock_version>0</lock_version>
      <position_name>Back Judge</position_name>
      <user_id/>
      <name/>
      <updated_at/>
      <sort_order>5</sort_order>
    </existing_assignments>
  </game>

  <!-- ... repeats for up to 50 games .. -->
  <page>1</page>
  <pages>31</pages>
  <count>1524</count>
</games>

Sample Response: GET /games.json

{
    "page":1,
    "pages":31,
    "count":1524,
    "games":
    [
        {
            "id":26845,
            "start_time":"Sat, 06 Mar 2011 08:00:00 -0500",
            "end_time":"Sat, 06 Mar 2011 08:59:00 -0500",
            "localized_date":"Mar 6 2011",
            "localized_time":"8:00 AM",
            "created_at":"Fri, 12 Feb 2011 11:46:56 -0500",
            "updated_at":"Fri, 12 Feb 2011 11:46:56 -0500",
            "is_public":0,
            "status":"A",
            "home_team_name":"Arizona Rush 94 Swoosh",
            "home_team_id":27249,
            "away_team_name":"TVSC Premier 94",
            "away_team_id":27250,
            "game_type_name":"Youth",
            "game_type_id":15,
            "league_name":"Pima Cup",
            "league_id":227,
            "venue_name":"Port Evangeline Church",
            "venue_id":3575,
            "age_group_name":"U 17 ",
            "age_group_id":2032,
            "gender_name":"Girls",
            "gender_id":228,
            "pattern_name":"5 officials",
            "pattern_id":18,                
            "published_comment": "This is a comment everyone can see",
            "unpublished_comment": "Only assignors will see this comment",                
            "existing_assignments":
            [
                {
                    "id":61167,
                    "lock_version":0,
                    "position_name":"Referee"
                },
                {
                    "id":61168,
                    "lock_version":0,
                    "position_name":"Umpire"
                },
                {
                    "id":61169,
                    "lock_version":0,
                    "position_name":"Head Linesman"
                },
                {
                    "id":61170,
                    "lock_version":0,
                    "position_name":"Line Judge"
                },
                {
                    "id":61171,
                    "lock_version":0,
                    "position_name":"Back Judge"
                }
            ]
        },
        {
            "id":26639,
            "start_time":"Sat, 06 Mar 2011 08:00:00 -0500",
            "end_time":"Sat, 06 Mar 2011 08:59:00 -0500",
            "localized_date":"Mar 6 2011",
            "localized_time":"8:00 AM",
            "created_at":"Fri, 12 Feb 2011 11:46:11 -0500",
            "updated_at":"Tue, 21 Sep 2011 21:28:21 -0400",
            "is_public":0,
            "status":"A",
            "home_team_name":"U10C THUNDERCATS",
            "home_team_id":27122,
            "away_team_name":"Region 1 Wizards",
            "away_team_id":27119,
            "game_type_name":"Youth",
            "game_type_id":15,
            "league_name":"Pima Cup",
            "league_id":227,
            "venue_name":"Port Paxton Church",
            "venue_id":3557,
            "age_group_name":"U 10",
            "age_group_id":2024,
            "gender_name":"Boys",
            "gender_id":229,
            "pattern_name":"5 officials",
            "pattern_id":18,
            "published_comment": "This is a comment everyone can see",
            "unpublished_comment": "Only assignors will see this comment",                
            "existing_assignments":
            [
              {
                  "id":60137,
                  "lock_version":1,
                  "position_name":"Referee",
                  "updated_at":"Tue, 28 Feb 2011 23:02:00 -0500",
                  "name":"Jakubowski, Manuel",
                  "sort_order":1
              },
              {
                  "id":60138,
                  "lock_version":1,
                  "position_name":"Umpire",
                  "updated_at":"Tue, 28 Feb 2011 23:02:00 -0500",
                  "name":"Huels, Rahsaan",
                  "sort_order":2
              },
              {
                  "id":60139,
                  "lock_version":1,
                  "position_name":"Head Linesman",
                  "updated_at":"Tue, 28 Feb 2011 23:02:00 -0500",
                  "name":"Ratke, Micheal",
                  "sort_order":3
              },
              {
                  "id":60140,
                  "lock_version":0,
                  "position_name":"Line Judge",
                  "sort_order":4
              },
              {
                  "id":60141,
                  "lock_version":0,
                  "position_name":"Back Judge",
                  "sort_order":5
              }
            ]
        },
        ... repeats for up to 50 games ...
    ]
}

Sort Order

The default sort order for games is date ascending (past to future), start time ascending (morning to evening), and venue ascending (A-Z). To change the sort order, append one or more "sort" parameters to the request URL. For example, this request will sort the results by date, then by venue, then by start time.

GET /games.xml?sort[0]=date&sort[1]=search_venue&sort[2]=start_time

You can append up to ten sort parameters, numbered 0 through 9. The following fields can be specified in your sort parameters:

  • date
  • start_time
  • search_venue
  • search_age_group
  • search_pattern
  • status
  • is_public
  • search_gender
  • search_home_team
  • search_away_team
  • search_league
  • search_game_type
  • user_defined_id

By default, the sort order will be ascending. To specify a descending sort order, append a hyphen to the sort parameter. As an example, this will sort by date descending order, then by time.

GET /games.xml?sort[0]=-date&sort[2]=start_time

Retrieve a specific game (SHOW)

The following commands will retrieve the game details for a specific game.

Sample Response: GET /games/123.xml

<?xml version="1.0" encoding="UTF-8"?>
<game>
  <id>26639</id>
  <start_time>Sat, 06 Mar 2010 08:00:00 -0500</start_time>
  <end_time>Sat, 06 Mar 2010 08:59:00 -0500</end_time>
  <localized_date>Mar 6 2010</localized_date>
  <localized_time>8:00 AM</localized_time>
  <lock_version>1</lock_version>
  <created_at>2010-03-12 11:46:11 -0500</created_at>
  <updated_at>2010-09-21 21:28:21 -0400</updated_at>
  <is_public>0</is_public>
  <status>A</status>
  <user_defined_id/>
  <external_id/>
  <longitude/>
  <latitude/>
  <home_team_name>U10C THUNDERCATS</home_team_name>
  <home_team_id>27122</home_team_id>
  <away_team_name>Region 1 Wizards</away_team_name>
  <away_team_id>27119</away_team_id>
  <game_type_name>Youth</game_type_name>
  <game_type_id>15</game_type_id>
  <league_name>Pima Cup</league_name>
  <league_id>227</league_id>
  <venue_name>Port Paxton Church</venue_name>
  <venue_id>3557</venue_id>
  <age_group_name>U 10</age_group_name>
  <age_group_id>2024</age_group_id>
  <gender_name>Boys</gender_name>
  <gender_id>229</gender_id>
  <pattern_name>5 officials</pattern_name>
  <pattern_id>18</pattern_id>
  <published_comment>This is a comment everyone can see</published_comment>
  <unpublished_comment>This is a comment only assignors can see</unpublished_comment>        
  <existing_assignments>
    <id>60137</id>
    <lock_version>1</lock_version>
    <position_name>Referee</position_name>
    <user_id>1992</user_id>
    <name>Jakubowski, Manuel</name>
    <updated_at>Tue, 28 Feb 2012 23:02:00 -0500</updated_at>
    <sort_order>1</sort_order>
  </existing_assignments>
  <existing_assignments>
    <id>60138</id>
    <lock_version>1</lock_version>
    <position_name>Umpire</position_name>
    <user_id>7276</user_id>
    <name>Huels, Rahsaan</name>
    <updated_at>Tue, 28 Feb 2012 23:02:00 -0500</updated_at>
    <sort_order>2</sort_order>
  </existing_assignments>
  <existing_assignments>
    <id>60139</id>
    <lock_version>1</lock_version>
    <position_name>Head Linesman</position_name>
    <user_id>7287</user_id>
    <name>Ratke, Micheal</name>
    <updated_at>Tue, 28 Feb 2012 23:02:00 -0500</updated_at>
    <sort_order>3</sort_order>
  </existing_assignments>
  <existing_assignments>
    <id>60140</id>
    <lock_version>0</lock_version>
    <position_name>Line Judge</position_name>
    <user_id/>
    <name/>
    <updated_at/>
    <sort_order>4</sort_order>
  </existing_assignments>
  <existing_assignments>
    <id>60141</id>
    <lock_version>0</lock_version>
    <position_name>Back Judge</position_name>
    <user_id/>
    <name/>
    <updated_at/>
    <sort_order>5</sort_order>
  </existing_assignments>
</game>

Sample Response: GET /games/123.json

{
    "game":
    {
        "id":26639,
        "start_time":"Sat, 06 Mar 2011 08:00:00 -0500",
        "end_time":"Sat, 06 Mar 2011 08:59:00 -0500",
        "localized_date":"Mar 6 2011",
        "localized_time":"8:00 AM",
        "created_at":"Fri, 12 Feb 2011 11:46:11 -0500",
        "updated_at":"Tue, 21 Sep 2011 21:28:21 -0400",
        "is_public":0,
        "status":"A",
        "home_team_name":"U10C THUNDERCATS",
        "home_team_id":27122,
        "away_team_name":"Region 1 Wizards",
        "away_team_id":27119,
        "game_type_name":"Youth",
        "game_type_id":15,
        "league_name":"Pima Cup",
        "league_id":227,
        "venue_name":"Port Paxton Church",
        "venue_id":3557,
        "age_group_name":"U 10",
        "age_group_id":2024,
        "gender_name":"Boys",
        "gender_id":229,
        "pattern_name":"5 officials",
        "pattern_id":18,
        "published_comment": "This is a comment everyone can see",
        "unpublished_comment": "Only assignors will see this comment",                
        "existing_assignments":
        [
            {
                "id":60137,
                "lock_version":1,
                "position_name":"Referee",
                "updated_at":"Tue, 28 Feb 2011 23:02:00 -0500",
                "name":"Jakubowski, Manuel",
                "sort_order":1
            },
            {
                "id":60138,
                "lock_version":1,
                "position_name":"Umpire",
                "updated_at":"Tue, 28 Feb 2011 23:02:00 -0500",
                "name":"Huels, Rahsaan",
                "sort_order":1
            },
            {
                "id":60139,
                "lock_version":1,
                "position_name":"Head Linesman",
                "updated_at":"Tue, 28 Feb 2011 23:02:00 -0500",
                "name":"Ratke, Micheal",
                "sort_order":1
            },
            {
                "id":60140,
                "lock_version":0,
                "position_name":"Line Judge",
                "sort_order":1
            },
            {
                "id":60141,
                "lock_version":0,
                "position_name":"Back Judge",
                "sort_order":1
            }
        ]
    }
}

Create a Game (CREATE)

To create a game, use the POST command to /games.xml or /games.json.

The following status codes can be returned:

  • 201 Created: Successfully created a game. The response body will have an XML or JSON representation of the game you created.
  • 403 Unprocessable Entity: The game failed one or more validation checks.

Sample Request Body: POST /games.xml

<game>
  <localized_date>Mar 6 2010</localized_date>
  <localized_time>8:00 AM</localized_time>
  <is_public>0</is_public>
  <user_defined_id/>
  <external_id/>
  <home_team_name>U10C THUNDERCATS</home_team_name>
  <away_team_name>Region 1 Wizards</away_team_name>
  <game_type_name>Youth</game_type_name>
  <league_name>Pima Cup</league_name>
  <venue_name>Golf Links West</venue_name>
  <age_group_name>U 10</age_group_name>
  <gender_name>Boys</gender_name>
  <pattern_name>3 Referees</pattern_name>
</game>

Sample Request Body: POST /games.json

{"game":
  {
      "localized_date":"Mar 6 2010",
      "localized_time":"8:00 AM",
      "is_public":0,
      "home_team_name":"U10C THUNDERCATS",
      "away_team_name":"Region 1 Wizards",
      "game_type_name":"Youth",
      "league_name":"Pima Cup",
      "venue_name":"Golf Links West",
      "age_group_name":"U 10",
      "gender_name":"Boys",
      "pattern_name":"3 Referees"
  }
}

Update a Game (UPDATE)

To update a game, send a PUT command to /games/123.xml or /games/123.json. The request body should be XML, JSON, or a URL encoded string. If you are only updating a specific field, you can just include the fields you wish to change. For example, if you only want to cancel a game, the request can look like this:

PUT /games/123.xml
<game><status>X</status></game>

PUT /games/123.xml
game[status]=X

PUT /games/123.json
{"game":{"status":"X"}}

Upon successful update of the record, the response code returned will be 200 (OK).

Sample Request: PUT /games/123.xml

The existing_assignments attributes are repeating attributes. existing_assignments only need to be included if you are modifying the assigned referees for a game.

In this example, the first three assignments (60138, 60139, and 60140) are changing the assigned referee. The last two assignments (60140, 60141) are removing any assigned referees.

<?xml version="1.0" encoding="UTF-8"?>
<game>
  <localized_date>Mar 9 2011</localized_date>
  <localized_time>9:15 AM</localized_time>
  <is_public>1</is_public>
  <existing_assignments>
    <id>60137</id>
    <lock_version>1</lock_version>
    <user_id>1992</user_id>
  </existing_assignments>
  <existing_assignments>
    <id>60138</id>
    <lock_version>1</lock_version>
    <user_id>7276</user_id>
  </existing_assignments>
  <existing_assignments>
    <id>60139</id>
    <lock_version>1</lock_version>
    <user_id>7287</user_id>
  </existing_assignments>
  <existing_assignments>
    <id>60140</id>
    <lock_version>0</lock_version>
    <user_id></user_id>
  </existing_assignments>
  <existing_assignments>
    <id>60141</id>
    <lock_version>0</lock_version>
    <user_id></user_id>
  </existing_assignments>
</game>

Delete a Game (DELETE)

To delete a game, issue a DELETE command to the game's URL:

DELETE /games/123.json

The server will respond with a status code 200 (OK) if the game was deleted, otherwise you will see an error response (422 Unprocessable Entity). No response body is rendered.

Validation Errors

If you try to create, update, or delete a game, and the change that you want to make validates one or more assignr.com validation rules, assignr.com will respond with a 422 Unprocessable Entity error. The response body will contain details about the error, like this:

<?xml version="1.0" encoding="UTF-8"?>
<error>
  <messages>
    <message>Venue already has a game scheduled at this day and time</message>
    <message>Game ID already exists</message>
  </messages>
</error>

If JSON is requested, it will look like this:

{

"error":[
    { "message": "Venue already has a game scheduled at this day and time" },
    { "message": "Game ID already exists" }
]    

}