OSAA Application Programming Interface
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, email@example.com.
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, firstname.lastname@example.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 in a timely fashion. Data may also be cached for a period of time to help reduce server load and database hits.
The following terms are used in throughout this API documentation. This vocabulary is used by the OSAA and is provided for reference.
- 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.
- 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.
- 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_zonesvalue 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_atvalue of "2014-05-15 13:00:00" and a
time_zoneof "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.
- 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.
- 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.
- 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).
- 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.
- A slug is a unique identifier, usually of the string data-type and acts must 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.
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
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.)
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".
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
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.
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.)