API Documentation

Introduction

The OSAA provides an application programming interface (API) to access database information. The basic premise is that data should be shared. The OSAA collects a vast amount of information from member schools that third parties find interesting. This data include schedules, scores, teams, rankings, and other information. This API provides a programmatic approach to accessing raw data.

Terms of Service

This service is provided "as is" and the OSAA disclaims all warranties with regard to this service including all implied warranties of merchantability and fitness. In no event shall the OSAA be liable for any special, direct, indirect, or consequential damages or any damages whatsoever resulting from loss of use, data or profits, whether in an action of contract, negligence or other tortuous action, arising out of or in connection with the use or performance of this service.

The OSAA reserves the right to create, remove, update, and delete any component or module of this service at any time without prior notice.

Access is restricted to registered IP addresses or requests with an authenticated API access key. To acquire access, please contact Gibby Reynolds, OSAA IT Systems Administrator, (503) 682.6722 x228, gibbyr@osaa.org.

Notice: During state championships, this API service may be temporarily unavailable. During peak usage times, the API may return an HTTP status code of 500. This protocol was enacted to mitigate heavy server loads during busy website periods.

Data Ownership & Attribution

Information provided through this API is owned by the Oregon School Activities Association. By accessing this API, the OSAA grants a limited, non-exclusive, non-sublicensable, non-transferable, non-assignable license under the OSAA's intellectual property rights to permit access to data through this API to develop, test, support a program/application or to research, display, view, and generally manipulate data however the third-party chooses. Third-parties cannot distribute OSAA API access or allow access to the stand-alone APIs (e.g. mirror API services or porting OSAA data through a third-party developed API). The OSAA does not claim ownership of any third-party applications that utilize OSAA data available through this API.

The OSAA appreciates attribution by third-parties that acknowledge their data source. It is requested that third-parties attribute the Oregon School Activities Association, or just OSAA, as the source of data. When API data is used or deployed in a digital program, application, or webpage, a reference hyper-link to www.osaa.org is appreciated.

Support

All documentation relating to using the API can be found on this page. This page includes detailed instructions as well as examples for use. Technical support and questions can be directed toward Gibby Reynolds, OSAA IT Systems Administrator, (503) 682.6722 x228, gibbyr@osaa.org.

Questions regarding integration or data usage are not supported by the OSAA. Comments regarding inaccurate schedules or contest scores or requests to change or update information relating to schedules and scores should be referred to the schools' athletic directors.

Availability & Data Formatting

This API can only be used to access information via HTTP GET method requests. All other HTTP methods are denied. The OSAA intends to protect its database and vet individuals entering information by restricting editing privilege to authenticated users. This API cannot be used to insert records or modify data contained within the OSAA database; the API only allows data reads.

Data regarding schedules, scores, and teams only pertain to team sports (football, volleyball, soccer, basketball, baseball, and softball.) Individual sports and activities are not supported through this API.

This API returns all data in JSON format. JSON data can be viewed in a browser or in most HTTP response capturing programs. Regardless of the existence of an HTTP accept header, data will only be returned as "application/json". Some data fields may contain comma separated lists (CSL) as a string data-type.

All responses will be returned as a JSON array, even API requests for single data elements (as an array with one item). A custom HTTP response header is added to each return, named Content-Count, that contains the number of returned items in the array. In the event of an error, the value will be zero.

Data specifications for a particular node are included in the "Nodes" section. In the node list, the conceptual data element is explained with URL accessors for requesting related node information. Underneath the URL access handles, the item's return variables are listed with the name of the field, its data-type, and a brief explanation of that field. An example of accessing that node's handle is contained in the gray box showing the handle, returned JSON data, and the HTTP response headers.

The accuracy of information from the database is not guaranteed. Schools are responsible for inputing schedules before the first allowable contest date, updating their schedules, and inputting scores by 10:00pm the day of the contest. Data may also be cached for a period of time to help reduce server load and database hits.

Definitions

The following terms are used in throughout this API documentation. This vocabulary is used by the OSAA and is provided for reference.

Boolean: A boolean data type can have three values: true, false, or null. If a value's data type is described as a boolean, you can expect one of those three values. Null boolean values represent an unknown or uninitiated state and should not be misinterpreted as false.
Classification: A group designator for schools based on annual enrollment. The OSAA currently groups schools into six classifications. Classifications include 6A, 5A, 4A, 3A, 2A, and 1A.
Date/Time: Dates and times are stored as strings with "YYYY-MM-DD HH:MM:SS" formating (ISO 8601). This data is saved as a DATETIME format, not a TIMESTAMP which means values can range from "1000-01-01 00:00:00" to "9999-12-31 23:59:59". All times are stored relative to Pacific Time (PT). Contests can return a time_zones value by slug. Time zones do not factor in daylight savings time. In such cases, those different time zones should be calculated with their respective offset relative to Pacific Time. For example, a contest with a start_at value of "2014-05-15 13:00:00" and a time_zone of "MT", then the contest starts at 2:00pm Mountain Time, but is saved in the database as 1:00pm Pacific Time. Contest times that are at midnight ("00:00:00") should be handled as TBD.
Division: A division is a group of one or more classifications that are combined in order to allow for fair competition. Some sports are not offered by every school. In such cases, some classifications are combined to form one division. Divisions with combined classifications list both classifications with a forward slash. For example, the "3A/2A/1A" division is sanctioned for competitions between schools in the 3A, 2A, or 1A classification.
League: Schools are assigned a regular league based on geographical area with other schools in the same classification. This assignment is made for a four-year block. Within each activity's division, teams are placed into leagues, usually coinciding with their regularly assigned league. In some instances (i.e. combined activity divisions that span more than one classification or in other special cases) special districts are created for grouping teams across regular districts. The term "Special District" is another word for a league with teams spanning regular leagues.

Leagues are commonly referred to by name. However, names change and take up unnecessary space. The database references leagues by slug. League slugs are composed of the division, followed by a hyphen, followed by the league's number within that division. For example, 1A-7 is the slug for the 7th league in the 1A division, currently named "Old Oregon League". Special district league slugs include "SD" after the hyphen; i.e., 2A/1A-SD3 is "Special District 3" in the 2A/1A division.
Level: There are two levels of competition, listed in order: varsity (V) and sub-varsity. Sub-varsity levels are subdivided into four levels: Junior Varsity (JV), Junior Varsity #2 (JV2), Freshman (FR), and Freshman #2 (FR2).
ID: Any id field is guaranteed to be a unique, auto-incremented, positive whole number of the integer data-type. All nodes have an id.
School Year: A school year is the academic school year for high schools in Oregon that starts in August and ends in June. If a school year is represented with only 4 digits, then it references the school year starting in that year. For example, 2014 refers to the 2014-2015 school year which starts in August, 2014 and ends in June 2015.
Slug: A slug is a unique identifier, usually of the string data-type and acts much like an id.

Common Filter Parameters

Some API requests requires access to past information or a specific subset of a node's collection. Common filter parameters can be appended to the end of a node's handle as a query string.

Level: level=[V|JV|JV2|FR|FR2]

By default, this optional parameter's value is automatically set to V (varsity). To get a different level, specify the level parameter as defined in the Definitions section.
School Year: year=[YYYY]

By default, this optional parameter's value is automatically set to the current school year. To request data pertaining to a different school year, use this parameter with a four digit integer value of the school year. (School years are defined in the Definitions section.)
Since: since=[YYYY-MM-DD|YYYY-MM-DD HH:MM:SS]

If the request contains an optional "since" parameter for a node that accepts it, then the returned items will be limited to those that were updated or created on or after the specified date or date-time combination. If only a date is provided (YYYY-MM-DD), then the time will default to midnight (00:00:00); i.e. the parameter value of "since=2017-05-20 00:00:00" will be handled the same as "since=2017-05-20".
Staff: staff=[1]

If the request contains an optional "staff" parameter for the schools node, then the returned items will contain school staff. Looking up school staff can consume additional time, so school objects, by default do not include administrative school staff nor team coaches. Including this parameter with any value will trigger the node to return a school item with the school_staff and team_staff object properties.
Spread: spread=[1]

If the request contains an optional "spread" parameter for the news feed node, then the returned list of news items be limited to only two consecutive news articles in a row from the same news outlet. This helps to spread the number of authors apart and helps limit news outlets from "padding" their appearances by publishing many articles at the same time. Including this parameter with any value will trigger the node to spread out news items.

Nodes

The API allows access to data relating to the nodes including Activities, Schools, Teams, Schedules, Contests, Leagues, OSAAtoday, and News Feeds. Details on accessing the API handles for each available node is described below. (Note: all information returned will be in a JSON array.)

Activities - An activity is a team sport sanctioned by the OSAA. To get a list of all activities or a specific activity with a given slug:

Optional Parameters
year

https://www.osaa.org/api/activities
https://www.osaa.org/api/activities/{slug}

id	integer	Unique identification number
slug	string	A unique, three character abbreviation
name	string	Name of the activity
type	string	Type of the activity (`TS` = Team Sport, `IS` = Individual Sport, `ACT` = Activity)
terminology	object	JSON object of the terminology strings for the activity (`sport` is the base sport/activity, `contest` is what a head to head competition is referred to as, `surface` is the physical playing surface, `venue` is the common name of the facility hosting a contest, `officials` is the base term that describes the official for the activity/sport)
divisions	array	JSON array of strings of the sanctioned divisions
year	integer	The school year for which this information applies

https://www.osaa.org/api/activities/fbl?year=2014

[{"id":101,
"slug":"FBL",
"name":"Football",
"type":"TS"
"terminology":{"sport":"football",
                 "contest":"game"
                 "surface":"field"
                 "venue":"field"
                 "officials":"official"},
"divisions":["6A",
               "5A",
               "4A",
               "3A",
               "2A",
               "1A"],
"year":2014}]

HTTP/1.1 200 OK
Connection: Close
Content-Type: application/json
Content-Length: 220
Content-Count: 1

Schools - A school is an OSAA full member school that hosts at least one activity. To get a list of all schools or a specific school with a given short name (slug) or id number:

Optional Parameters
year, staff

https://www.osaa.org/api/schools
https://www.osaa.org/api/schools/{slug}
https://www.osaa.org/api/schools/{id}

id	integer	Unique identification number
name	string	Full name of the school
short_name	string	Shortened name of the school with common words removed or abbreviated
type	string	The school type (public, private, or charter)
classification	string	School's classification
league	string	School's regularly assigned league
league_full_name	string	The name of the school's regularly assigned league including the league slug
league_name	string	The name of the school's regularly assigned league without the league slug
mascot	object	JSON object of school's mascot(s) containing (`main`, `alternate`, `url`) strings
colors	array	JSON array of the school's colors (up to three) containing JSON objects with (`name`, `hex`) strings
adm	integer	ADM, or enrollment, number of students for this school reported for the school year
year	integer	The school year for which this information applies
activities	object	*JSON object, associative array indexed by activity slug with values of JSON objects with (`activity_name`, `activity_sport`, `activity_program_id`, `activity_program_name`, `division`, `league`, `league_full_name`, `league_name`, and `teams`)
social_media	object	JSON array of the school's social media handles containing JSON objects with (`platform`, `handle`, `link`) strings
school_staff	object	**JSON object, associative array of administrative school staff containing JSON objects with (`name`, `email`, `phone`) strings - requires `staff` optional parameter to be provided
team_staff	object	***JSON object, associative array of activity program head coaches containing JSON objects with (`name`, `email`, `phone`) strings - requires `staff` optional parameter to be provided

https://www.osaa.org/api/schools/Corvallis?staff=1

[{"id":12,
"name":"Corvallis High School",
"short_name":"Corvallis",
"type":"Public",
"classification":"5A",
"league":"5A-2 (2018-2021)",
"league_full_name":"5A-2 Mid-Willamette Conference",
"league_name":"Mid-Willamette Conference",
"mascot":{"main":"Spartans",
            "alternate":null,
            "url":"https://www.osaa.org/images/logo?school=12"},
"colors":[{"name":"Columbia Blue","hex":"#75B2DD"},
            {"name":"Navy","hex":"#000080"},
            {"name":"White","hex":"#FFFFFF"}],
"adm":1117,
"year":2018,
"activities":{"FBL":{"activity_name":"Football",
                       "activity_sport":"Football",
                       "activity_program_id": 24042,
                       "activity_program_name": "Corvallis",
                       "division": "5A",
                       "league": "5A-SD3 (2018-2021)",
                       "league_full_name": "5A-SD3 Special District 3",
                       "league_name": "Special District 3",
                       "teams":[{"id":39635,"level":"V"},
                                {"id":45060,"level":"JV"},
                                {"id":45067,"level":"FR"}]},
                ...},
"social_media":[{"platform":"FACEBOOK","handle":"@HHH","link":"https://www.facebook.com/HHH"},
                  {"platform":"TWITTER","handle":"@HHH","link":"https://www.twitter.com/HHH"},
                  {"platform":"INSTAGRAM","handle":"@HHH","link":"https://www.instagram.com/HHH"}],
"school_staff":{"Principal":{"name":"First Last","email":"email@domain","phone":"(###) ###-#### x#####"},
                  "Athletic Director":{"name":null,"email":null,"phone":null},
                  "AD Secretary":{"name":null,"email":null,"phone":null}},
"team_staff":{"FBL":{"name":null,"email":null,"phone":null},
                "VBL":{"name":null,"email":null,"phone":null}, ...}}]

HTTP/1.1 200 OK
Connection: Close
Content-Type: application/json
Content-Length: 8516
Content-Count: 1

*The activities associate array lists every OSAA sanctioned activity that this school offers within the specified school year. Index keys of the array are the 3-character activity slug. Values of the array are JSON objects containing the following fields:

activity_name	string	The name of the activity offered
activity_sport	string	The name of the activity's sport (i.e. "Swimming" is the sport for activities named "Boys Swimming" and "Girls Swimming")
activity_program_id	integer	The unique ID number of this school's activity program. An activity program is a record identifying which activities are offered by which schools and in which school year. On the OSAA website, team pages default to the highest level of team and are indexed by activity program ID (i.e. https://www.osaa.org/teams/24225 lists Glencoe's 2018 Volleyball program and shows V, JV, JV2, and F teams)
activity_program_name	string	This is the name of the activity program. This name is usually the school's `short_name`, however, if the activity program is a coop program, then the `activity_program_name` will be a combination of all involved schools' `short_name` separated by a "/"
division	string	The classification of division (combined classifications) in which this activity program and its teams operate
league	string	The league slug in which this activity program and its teams have been assigned for this activity
league_full_name	string	The name of the program's assigned league including the league slug
league_name	string	The name of program's assigned league without the league slug
teams	array	JSON array representing all of the team levels offered by this school for this activity, (`id`, `level`)

**Only included if staff optional parameter is provided with some value. Administrative staff information is provided by the school. The school_staff object is an associative array, returned as a JSON object. Staff are returned as objects with each array index/object property corresponding to the respective role/title as follows:

"Princiapl", "Athletic Director", "AD Secretary"

***Only included if staff optional parameter is provided with some value. Team staff information is provided by the school. The team_staff object is an associative array, returned as a JSON object. Only the team's first varsity level head coach will be displayed, if any. Staff are returned as objects with each array index/object property corresponding to the respective activity program slug. All activity programs the school offers/participates in the year will be listed.

Staff objects contain three properties: name, email, and phone. Names are returned in "First Last" format. Email addresses, if provided and publicly available, will be listed; otherwise, null is returned. Phone numbers, if provided for office/work and are publicly available will be listed in "(####) ###-#### x#####" format; otherwise, null is returned.

Teams - A team is an instance of an activity program for a school competing at a specific level. To get a list of all teams, a specific team by id number, all teams pertaining to an activity slug, all teams for a specific school, or a specific team with a school/activity slug combination:

Optional Parameters
level, year

https://www.osaa.org/api/teams
https://www.osaa.org/api/teams/{id}
https://www.osaa.org/api/teams/{activity}
https://www.osaa.org/api/teams/{school}
https://www.osaa.org/api/teams/{school}/{activity}

id	integer	Unique identification number
activity_program_id	integer	Unique identification number for the team's activity program
school	integer	Unique identification number of the team's host school
name	string	Name (school or coop name)
level	string	Competition level
activity	string	Sport
division	string	Division in which this team competes
league	string	League this team is assigned to, if any
league_full_name	string	League this team is assigned to, if any, with its full names including league slug
league_name	string	League this team is assigned to, if any, with just the name of the league
year	integer	The school year for which this information applies
social_media	object	JSON array of the team specific social media handles containing JSON objects with (`platform`, `handle`, `link`) strings. If no team specific media handles are specified, then the school's social media handles are displayed, if any.
overall_record	string	Record of all contests won, lost, and/or tied; wins-losses-ties
league_record	string	Record of league contests won, lost, and/or tied; wins-losses-ties
league_finish	integer	Final league placement, if any
osaa_rank	integer	*Team's OSAA ranking compared to other teams in the division
apr	integer	*Adjusted playoff ranking, if any
rpi_rank	integer	*Team's RPI ranking compared to other teams' RPI values in the division
rpi	float	*Rating percentage index; range [0, 1]
wwp	float	*Weighted winning percentage; range [0, 1]
owp	float	*Opponents' winning percentage; range [0, 1]
colley_rank	integer	*Team's Colley ranking compared to other teams' Colley values in the division
colley	float	*Colley rating
roster	array	**JSON array of the roster of players containing JSON objects
photo_url	string	Full URL path to the team photo, if any
updated_at	string	Date/time of when the team's information was last updated
calculated_at	string	Date/time of when the team's ranking specific information was last calculated

https://www.osaa.org/api/teams/9552

[{"id":9552,
"activity_program_id":6081,
"school":177,
"name":"Philomath",
"level":"V",
"activity":"BBX",
"division":"4A",
"league":"4A-4 (2014-2017)",
"league_full_name":"4A-4 Oregon West Conference",
"league_name":"Oregon West Conference",
"year":2014,
"social_media":[{"platform":"FACEBOOK","handle":"@HHH","link":"https://www.facebook.com/HHH"},
                  {"platform":"TWITTER","handle":"@HHH","link":"https://www.twitter.com/HHH"},
                  {"platform":"INSTAGRAM","handle":"@HHH","link":"https://www.instagram.com/HHH"}],
"overall_record":"22-2-0",
"league_record":"9-1-0",
"league_finish":"1",
"osaa_rank":2,
"apr":2,
"rpi_rank":2,
"rpi":0.680189636748686,
"wwp":0.928571428571429,
"owp":0.546445594997978,
"colley_rank":1,
"colley":0.949374037551917,
"roster":[{"home_number":"4",
             "away_number":"4",
             "is_captain":null,
             "name":"Jack Doe",
             "position":"G",
             "position_2":"",
             "grade":"12",
             "height":"5-9",
             "weight":""}, ... ],
"team_photo":"https://www.osaa.org/images/team_photos/9552.jpg",
"updated_at":"2015-03-05 09:00:01",
"calculated_at":"2015-02-24 22:44:30"}]

HTTP/1.1 200 OK
Connection: Close
Content-Type: application/json
Content-Length: 2453
Content-Count: 1

*The OSAA uses a modified RPI and a Colley rankings system. These systems are only used to calculate bracket matchups and team placements for the teams that have qualified for the OSAA Championships.

For more information on team rankings, please refer to the Rankings Frequently Asked Questions.

**Rosters are returned as a JSON array of JSON objects. Each object represents a participant on the team and will contain the following values:

home_number

Integer - participant's home jersey number, if any

away_number

Integer - participant's away jersey number, if any

is_captain

Boolean - true if the participant is a team captain, false or null otherwise

name

String - full name of the participant, expected to be in "First Last" format

position

String - abbreviation for the position this participant fills on the team, if any

position_2

String - abbreviation for the second or alternate position this participant fills on the team, if any

grade

Integer - grade in school for this participant (9 = freshman, 10 = sophomore, 11 = junior, 12 = senior)

height

String - participant's height, if any; expected to be in "FT-IN" format of two integers, i.e. "6-0" represents 6 feet and 0 inches in height

weight

Integer - participant's weight, in US pounds, if any and only for the sport of football

Schedules - A schedule is a collection of contests or meets for a specific team. Schedules are referenced by team ID.: Optional Parameters
since

https://www.osaa.org/api/schedules/{id}

See Contests or Meets node for data definitions. The type of object returned in the array depends on the team's activity. Team sport activities return an array of contests. Individual sport activities return an array of meets. A schedule returns an array of contests* for the given team ID or meets** in which the given team ID is involved with.

*Schedules will include all contests input by the schools. For tracking purposes, soft deleting is supported. Contests that have been deleted and removed from a schedule will have a status of DEL. Deleted contests should be treated as non-existent as they are not recoverable (i.e. once a contest is deleted, it will not be reinstated.)

**Schedules will include all meets input by the schools. For tracking purposes, soft deleting is supported. Teams that have dropped out of a meet will have an is_dropped flag that indicates that team is no longer participating in the meet. Dropped teams should not be treated as non-existent as they are recoverable (i.e. once a team is dropped, it may or may not be reinstated.)

Note: This feature has yet to be implemented.

Contests - A contest is an instance of two teams competing against each other in a team sport activity on a certain date. A single contest can be accessed by ID number. A collection of contests for a specific activity can be returned or narrowed down to contests for that activity on a specific date. Contests for any activity on a specific date and/or of a specific contest type can also be accessed.

Optional Parameters
type¹, level, year, since

https://www.osaa.org/api/contests/{id}
https://www.osaa.org/api/contests/{activity}
https://www.osaa.org/api/contests/{activity}/{date}
https://www.osaa.org/api/contests/{date}

id	integer	Unique identification number
year	integer	The school year for which this information applies
activity	string	Sport
type	string	¹Type of the activity
round	string	²Playoff round
htt_school_fund	string	Ticketing school/organization fund name
htt_event_name	string	Ticketing event name
tickets_url	string	URL to purchase tickets for this contest
is_osaa_hosted	boolean	True if the playoff contest is hosted by the OSAA, otherwise false
division	string	Division, highest division if teams compete at different divisions
is_cross_division	boolean	True if the teams compete at different divisions, false if teams are in the same division
level	string	Competition level, highest level if teams compete at different levels
is_cross_level	boolean	True if the teams compete at different levels, false if teams are in the same level
league	string	League slug, if this contest is a league contest
is_scoreable	boolean	True if this contest will yield a score, false if the contest does not allow a score to be entered
status	string	³Scheduling status of the event
time_zone	string	Time zone slug
start_at	string	Date/time of when the contest starts
postpone_at	string	Date/time of when the contest is postponed to
location	string	Alternate contest location, if any; if none, contest is held at home team's school
address	object	JSON object of the contest location's address, if specified; contains (`name`, `line_1`, `line_2`, `city`, `state`, `zip`) strings
is_neutral	boolean	True if the contest's location is a neutral site, false otherwise; used in rankings calculations
is_tournament	boolean	True if the contest is part of a tournament, false otherwise
tournament	string	Name of the tournament, if any
is_endowment	boolean	True if the contest is an endowment game, false otherwise
home	object	⁴JSON object of the home team, contains (`id`, `school_id`) integer, (`name`, `score`, `sub_scores`) strings, (`is_win`, `is_tie`, `is_forfeit`, `is_recordable`, `is_league_recordable`, `is_rankable`) booleans, and (`weight`, `points`) floats
away	object	⁴JSON object of the away team, contains (`id`, `school_id`) integer, (`name`, `score`, `sub_scores`) strings, (`is_win`, `is_tie`, `is_forfeit`, `is_recordable`, `is_league_recordable`, `is_rankable`) booleans, and (`weight`, `points`) floats
is_forfeit	integer	⁵If not null, this contest was forfeited by the losing team (in which case refer to the contest's comments for more information)
is_swap_designation	boolean	True if teams swapped designation; i.e. home team bats first, false otherwise; used in rankings calculations for baseball and softball contests only
oos_record	string	Out-of-state opponent's record, if any, in W-L or W-L-T format
oos_updated_at	string	Date/time of when the out-of-state opponent's record information was last updated, if applicable
comments	string	Comments or notes about this contest, if any
overtime_notes	string	Details entered if the contest went into overtime, extra innings, or extra sets
updated_at	string	Date/time of when the contest's information was last updated
created_at	string	Date/time of when this contest was created

https://www.osaa.org/api/contests/14043

[{"id":14043,
"year":2013,
"activity":"VBL",
"type":"PO",
"round":"F",
"division":"6A",
"is_cross_division":false,
"level":"V",
"is_cross_level":false,
"league":null,
"is_scoreable":true,
"status":"DONE",
"time_zone":"PT",
"start_at":"2013-11-09 20:30:00",
"postpone_at":null,
"location":"Court 1",
"address":{"name":"Liberty High School",
             "line_1":"7445 NE Wagon Dr",
             "line_2":"",
             "city":"Hillsboro",
             "state":"OR",
             "zip":"97124"},
"is_neutral":false,
"is_tournament":false,
"tournament":null,
"is_endowment":false,
"home":{"id":3218,
          "school_id":226,
          "name":"Central Catholic",
          "score":"1",
          "sub_scores":"29,25,12,22",
          "is_win":false,
          "is_tie":false,
          "is_forfeit":false,
          "is_recordable":true,
          "is_league_recordable":false,
          "is_rankable":false,
          "weight":1.2,
          "points":0},
"away":{"id":556,
          "school_id":38,
          "name":"Lakeridge",
          "score":"3",
          "sub_scores":"31,23,25,25",
          "is_win":true,
          "is_tie":false,
          "is_forfeit":false,
          "is_recordable":true,
          "is_league_recordable":false,
          "is_rankable":false,
          "weight":1.2,
          "points":1.2},
"is_forfeit":null,
"is_swap_designation":false,
"oos_record":null,
"oos_updated_at":null,
"comments":null,
"overtime_notes":null,
"updated_at":"2013-11-09 22:26:55",
"created_at":"2013-10-28 18:25:04"}]

HTTP/1.1 200 OK
Connection: Close
Content-Type: application/json
Content-Length: 1163
Content-Count: 1

¹All contests have one and only one contest type. Queries can optionally be filtered by contest type, like contest level. Contest types are returned by their slug and are defined as follows:

Jamboree (a practice or partial contest, will not have a score)

Season 1 (a 2020-21 contest scheduled during COVID-19 modified season 1)

Pool Play (a volleyball match that is not counted in rankings or contest limitations but included in tournaments)

Exhibition (an unranked contest that only counts toward overall record)

Alumni (an unranked contest that only counts toward overall record played between a school's team and alumni members)

Non-League (a ranked contest between opponents from different leagues)

League (a ranked contest between opponents from the same league)

LPO

League Playoff (a ranked contest between opponents from the same league that does not count toward the teams' league records)

Play-In (an unranked contest that only counts toward overall record)

Playoff (an unranked contest that is part of the OSAA Championships and is counted on the overall record)

²If the contest type is a playoff contest (PO), then the round slug represents which round in the playoffs the contest is scheduled. Rounds are as follows:

First (first playoff round)

Second (second playoff round)

Third (third playoff round)

Quarterfinal (third to last playoff round)

Semifinal (second to last round, playing for Final/Consolation)

Final (final round, playing for #1/#2)

Semiconsolation (second to last consolation round, playing for Consolation/#5-#6)

Consolation (final consolation round, playing for #3/#4)

Special (special playoff round)

Special 2 (special round #2)

³All contests have one and only one event status. The event status will be returned by its slug, defined as follows:

PND

Pending (event is waiting for confirmation or authorization with no guarantee that it will be played)

DEL

Deleted (the event has been deleted from a schedule; soft delete support)

SCHD

Scheduled (event is confirmed to take place on the scheduled start date/time)

CXL

Canceled (event had been scheduled, but it never started so it has since been canceled; CXL contests can be rescheduled, but only as a new event)

PPD

Postponed (event delayed to a future date/time; a PPD contest will revert to SCHD at midnight on the day the contest was originally scheduled)

LIVE

Live (event has started and awaiting a score to be entered)

DONE

Done (the event had started and is now over; usually a LIVE contest changes to DONE once a score is entered)

⁴Contest team data returned for home and away teams includes several items. Most items pertain to rankings calculations. A more in-depth explanation of those data items is below:

Integer - team's unique identification number, if any (OOS teams do not have id numbers)

school_id

Integer - the team's host school unique identification number, if any (OOS teams do not have school_id numbers)

name

String - team's display name; OOS teams have their state in parentheses, lower level team has its level in square brackets if cross level

score

String - team's final, overall score

sub_scores

String - team's final, sub-score (period scores, quarter scores, innings, sets, etc.)

is_win

Boolean - true if this team won the contest, false if the team did not win (could be a loss of a tie)

is_tie

Boolean - true if the contest was tied

is_forfeit

Boolean - true if this team forfeited the contest

is_recordable

Boolean - true if the contest counts towards this team's overall record

is_league_recordable

Boolean - true if the contest counts towards this team's league record

is_rankable

Boolean - true if the contest counts towards this team's ranking

weight

Float - the overall game weight or potential impact for this team

points

Float - the number of points (0 up to the weight) this team earned for its win/loss/tie

⁵Contests return an integer value for null for the field is_forfeit. If the contest is over, then the losing team will have an indicator flag, also named is_forfeit which can be treated as a boolean to determine which team forfeited. The contest's is_forfeit value represents what type of forfeit if the contest was forfeited by a team. If the value is null, then the contest was not a forfeit. The contest type determines if the contest is included in the rankings or not based off of rankings policies. The following forfeit types correspond to their ID number:

null

This contest was not a forfeiture

The contest was forfeited for some other reason or for an uncategorized reason. Refer to contest notes for circumstances regarding this forfeiture. This contest will be excluded from the rankings.

The contest was forfeited because a team used a player who was an ineligible participant. The result of the contest was not changed by this forfeiture, the team that forfeited had already lost the contest. This contest will count in the rankings because the outcome did not change.

The contest was forfeited because a team used a player who was an ineligible participant. The result of the contest was changed by this forfeiture, the team that forfeited had originally won the contest but now must record a loss. This contest will be excluded from the rankings.

The contest was forfeited because a team used a player who participated during their period of suspension because of a previous ejection. The result of the contest was not changed by this forfeiture, the team that forfeited had already lost the contest. This contest will count in the rankings because the outcome did not change.

The contest was forfeited because a team used a player who participated during their period of suspension because of a previous ejection. The result of the contest was changed by this forfeiture, the team that forfeited had originally won the contest but now must record a loss. This contest will be excluded from the rankings.

The contest was forfeited because a team used a pitcher who exceeded their pitch limitation. The result of the contest was not changed by this forfeiture, the team that forfeited had already lost the contest. This contest will count in the rankings because the outcome did not change.

The contest was forfeited because a team used a pitcher who exceeded their pitch limitation. The result of the contest was changed by this forfeiture, the team that forfeited had originally won the contest but now must record a loss. This contest will be excluded from the rankings.

The contest was forfeited because a team used a player who exceeded their daily participation limitation. The result of the contest was not changed by this forfeiture, the team that forfeited had already lost the contest. This contest will count in the rankings because the outcome did not change.

The contest was forfeited because a team used a player who exceeded their daily participation limitation. The result of the contest was changed by this forfeiture, the team that forfeited had originally won the contest but now must record a loss. This contest will be excluded from the rankings.

The contest was forfeited because a team used a player who exceeded their weekly participation limitation. The result of the contest was not changed by this forfeiture, the team that forfeited had already lost the contest. This contest will count in the rankings because the outcome did not change.

The contest was forfeited because a team used a player who exceeded their weekly participation limitation. The result of the contest was changed by this forfeiture, the team that forfeited had originally won the contest but now must record a loss. This contest will be excluded from the rankings.

The contest was forfeited because a team used a player who exceeded their seasonal participation limitation. The result of the contest was not changed by this forfeiture, the team that forfeited had already lost the contest. This contest will count in the rankings because the outcome did not change.

The contest was forfeited because a team used a player who exceeded their seasonal participation limitation. The result of the contest was changed by this forfeiture, the team that forfeited had originally won the contest but now must record a loss. This contest will be excluded from the rankings.

The contest was forfeited because a team used a non-certified coach. The result of the contest was not changed by this forfeiture, the team that forfeited had already lost the contest. This contest will count in the rankings because the outcome did not change.

The contest was forfeited because a team used a non-certified coach. The result of the contest was changed by this forfeiture, the team that forfeited had originally won the contest but now must record a loss. This contest will be excluded from the rankings.

The contest was forfeited because a team used a coach during their period of suspension because of an ejection, the coach was not out of sight and sound, or the coach refused to leave sight and sound after being ejected. The result of the contest was not changed by this forfeiture, the team that forfeited had already lost the contest. This contest will count in the rankings because the outcome did not change.

The contest was forfeited because a team used a coach during their period of suspension because of an ejection, the coach was not out of sight and sound, or the coach refused to leave sight and sound after being ejected. The result of the contest was changed by this forfeiture, the team that forfeited had originally won the contest but now must record a loss. This contest will be excluded from the rankings.

The contest was forfeited because a team did not have enough participants in order to continue. The result of the contest was not changed by this forfeiture, the team that forfeited had already lost or was already losing at the time the contest was stopped. This contest will count in the rankings because the outcome did not change.

The contest was forfeited because a team did not have enough participants in order to continue. The result of the contest was changed by this forfeiture, the team that forfeited had originally won the contest or was winning at the time the contest was stopped but now must record a loss. This contest will be excluded from the rankings.

The contest was forfeited because a team did not have enough participants in order to play. The team forfeited prior to competition; the contest was never started. This contest will be excluded from the rankings.

The contest was forfeited because a team did not have enough coaches in order to continue. The result of the contest was not changed by this forfeiture, the team that forfeited had already lost or was already losing at the time the contest was stopped. This contest will count in the rankings because the outcome did not change.

The contest was forfeited because a team did not have enough coaches in order to continue. The result of the contest was changed by this forfeiture, the team that forfeited had originally won the contest or was winning at the time the contest was stopped but now must record a loss. This contest will be excluded from the rankings.

The contest was forfeited because a team did not have enough coaches in order to play. The team forfeited prior to competition; the contest was never started. This contest will be excluded from the rankings.

The contest was forfeited because a team did not finish the contest. The result of the contest was not changed by this forfeiture, the team that forfeited was already losing at the time the contest was stopped. This contest will count in the rankings because the outcome did not change.

The contest was forfeited because a team did not finish the contest. The result of the contest was changed by this forfeiture, the team that forfeited was winning at the time the contest was stopped and now must record a loss. This contest will be excluded from the rankings.

The contest was forfeited because a team was absent from the contest, the team dropped out of a tournament, or the team dropped from a committed schedule. The team forfeited prior to competition; the contest was never started. This contest will be excluded from the rankings.

The contest was forfeited because a team was unable to complete because of limitations from the practice model rule. The team forfeited prior to competition; the contest was never started. This contest will be excluded from the rankings.

The contest was forfeited because a team exceeded its contest schedule limitation. The result of the contest was not changed by this forfeiture, the team that forfeited had already lost the contest. This contest will count in the rankings because the outcome did not change.

The contest was forfeited because a team exceeded its contest schedule limitation. The result of the contest was changed by this forfeiture, the team that forfeited had originally won the contest but now must record a loss. This contest will be excluded from the rankings.

Leagues - This node has a handle for accessing regular leagues and activity/league instances. To narrow down a collection of regular leagues or activity/league instances to a specific league, use the optional league parameter. The value of this parameter should be the league slug.

Optional Parameters
year, league

https://www.osaa.org/api/leagues
https://www.osaa.org/api/leagues/{activity}

id	integer	Unique identification number
slug	string	Unique identification string composed of the division and league number within that division
name	string	Full name of the league
divisions	array	JSON array of division slug strings spanned by this league
year	integer	The school year for which this information applies
schools	array	*JSON array of schools, if any, in this league containing JSON objects with (`id`, `short_name`) pairs
activity	string	*Activity slug, if any, for this league
teams	array	*JSON array of teams, if any, in this activity league containing JSON objects with (`id`, `name`) pairs

https://www.osaa.org/api/leagues/bsc?league=5A-1

[{"id":24,
"slug":"5A-1",
"name":"5A-1 Northwest Oregon Conference",
"divisions":["5A"],
"year":2013,
"schools":null,
"activity":"BSC",
"teams":[{"id":91,"name":"Putnam"},
           {"id":824,"name":"Sandy"},
           {"id":1271,"name":"Parkrose"},
           {"id":1818,"name":"Sherwood"},
           {"id":2332,"name":"St. Helens"},
           {"id":3001,"name":"Wilsonville"},
           {"id":4270,"name":"Liberty"},
           {"id":4432,"name":"Milwaukie \/ Milwaukie Acad. of the Arts"}]}]

HTTP/1.1 200 OK
Connection: Close
Content-Type: application/json
Content-Length:
Content-Count: 1

*Leagues can be associated with or without an activity. If activity is not provided (null), then the collection returned will be regular league assignments and not activity specific. In such cases, an array of schools is returned with each collection item. Those listed schools are normally assigned to that league. The activity field and teams array will be null.

If the activity field is not null, then the league is an activity specific league. Each league returned in the collection will have a list of teams that are assigned to that specific activity/league combination and the schools array will be null. Only varsity level teams are returned.

OSAAtoday Feed - This node has a handle for accessing news articles published via OSAAtoday. These OSAAtoday articles are displayed on the OSAA website home page and at www.osaa.org/today. Articles are available in this node going back for two weeks and up to a maximum of 25 articles are returned if no specific article id is provided. A specific article can also be retrieved by its unique id.

https://www.osaa.org/api/osaa-today
https://www.osaa.org/api/osaa-today/{id}

id	integer	Article's unique identification number
author	object	*JSON object containing author information with (`id`, `name`, `outlet`, `title`, `photo_url`, `email`, `articles_url`, and `social_media`) variables
title	string	The name of the news article
sub_title	string	The optional sub-title, or by-line, of the article
tags	array	A list of tag strings that categorize the article
body	string	**The content of the article's body
link	string	The URL link to the news article on the OSAA website
mobile_link	string	The URL link to the news article on the OSAA mobile website, designed for smaller screens
photo_url	string	The URL link to the article's main photo, if any
photo_caption	string	The optional photo caption, if any
published_at	string	Date/time of when the article was published to the OSAAtoday feed
updated_at	string	Date/time of when the article was last updated in the OSAA database

https://www.osaa.org/api/osaa-today/17

[{"id":17,
"author":{"id":5,
            "name":"Jerry Ulmer",
            "outlet":"OSAAtoday",
            "title":"Author",
            "photo_url":"https://www.osaa.org/images/articles/author_5_jerry_ulmer.jpg",
            "email":"[email protected]",
            "articles_url": "https://www.osaa.org/today/author/5/Jerry_Ulmer",
            "social_media":[{"platform":"FACEBOOK","handle":"@HHH","link":"https://www.facebook.com/HHH"},
                            {"platform":"TWITTER","handle":"@HHH","link":"https://www.twitter.com/HHH"},
                            {"platform":"INSTAGRAM","handle":"@HHH","link":"https://www.instagram.com/HHH"}]},
"title":"Football thriving in Dufur as Rangers seek historic four-peat",
"sub_title":"Dufur goes after another 1A title with one of its fastest teams",
"tags":["Football","1A","Dufur"],
"body":"<p>Article body content including HTML tags and in-line styles.</p>",
"link":"https://www.osaa.org/today/article/17/view?title=Football+thriving...",
"mobile_link":"https://www.osaa.org/mobile/today/17",
"photo_url":"https://www.osaa.org/images/articles/17.jpg",
"photo_caption":"Caption",
"published_at":"2018-08-10 11:55:04",
"updated_at":"2018-08-13 13:10:56"}]

HTTP/1.1 200 OK
Connection: Close
Content-Type: application/json
Content-Length: 5250
Content-Count: 1

*The author JSON object contains the author's information. Object parameters include the following fields:

id	integer	The author's unique identification number
name	string	The name of the author
outlet	string	The name of the outlet, or organization, to which this author is associated
title	string	the author's position, title, or role with their outlet
photo_url	string	The fully qualified URL to the author's profile picture
email	string	The author's email address
articles_url	string	The fully qualified URL to the list of OSAAtoday articles published by this author
social_media	array	JSON array listing the author's social media handles. Each handle includes (`platform`, `handle`, `link`) strings

**The body field contains HTML code for the main content of the article. This field will be null if the request returns an array of OSAAtoday articles. Content data will only be included for a specific article request.

News Feed - This node has a handle for accessing OSAA related news items from various Oregon news outlets. These news items are displayed on the OSAA website. News items are seeded into the OSAA database three times a day: 0600, 1200, and 1800. The optional spread parameter, if provided, will limit news outlets to 2 consecutive articles.

Optional Parameters
spread

https://www.osaa.org/api/news-feed

id	integer	Unique identification number
source	string	The name of the news outlet, without spaces, and uniquely identifies the news source
author	string	The displayable name of the news source
title	string	The name of the news article
link	string	The URL link to the news article, usually pointing to the news outlet that hosts the article
published_at	string	Date/time of when the news article was published by the news source
updated_at	string	Date/time of when the news item was last updated in the OSAA database
created_at	string	Date/time of when this news item was created in the OSAA database

https://www.osaa.org/api/news-feed

[{"id":46433,
"source":"LongviewDailyNews",
"author":"Longview Daily News",
"title":"Sample News Item for OSAA",
"link":"https://www.somenewswebsite/articles/sports/some_page",
"published_at":"2018-07-12 20:12:00",
"updated_at":"2018-07-13 12:00:05",
"created_at":"2018-07-13 12:00:05"}]

HTTP/1.1 200 OK
Connection: Close
Content-Type: application/json
Content-Length: 12345
Content-Count: 1

OSAA Application Programming Interface