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. To acquire access, please contact Gibby Reynolds, OSAA IT Systems Administrator, (503) 682.6722 x228, .

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, .

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 will 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 contain comma separated lists (CSL) in 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.

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 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.

Date

date=[YYYY-MM-DD]

To limit collections containing items with a date, you can specify the date parameter. Specify the desired date in YYYY-MM-DD format.

*/ ?>

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.)

Nodes

The API allows access to data relating to the nodes including Activities, Schools, Teams, Contests, and Leagues. 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

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

id	integer	Unique identification number
slug	string	A unique, three character abbreviation
name	string	Name of the activity
divisions	array	JSON array of strings of the sanctioned divisions
year	integer	The school year for which this information applies

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

[{"id":101,"slug":"FBL","name":"Football","divisions":["6A","5A","4A","3A","2A","1A"],"year":2014}]

HTTP/1.1 200 OK
Connection: Close
Content-Type: application/json
Content-Length: 99
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

http://www.osaa.org/api/schools
http://www.osaa.org/api/schools/{slug}
http://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
classification	string	School's classification
league	string	School's regularly assigned league
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
year	integer	The school year for which this information applies

http://www.osaa.org/api/schools/Corvallis

[{"id":12,
  "name":"Corvallis High School",
  "short_name":"Corvallis",
  "classification":"5A",
  "league":"5A-2",
  "mascot":{"main":"Spartans",
            "alternate":null,
            "url":"http://www.osaa.org/images/logo?school=12"},
  "colors":[{"name":"Columbia Blue","hex":"#75B2DD"},
            {"name":"Navy","hex":"#000080"},
            {"name":"White","hex":"#FFFFFF"}],
  "year":2013]}

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

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

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

id	integer	Unique identification number
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
year	integer	The school year for which this information applies
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

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

[{"id":9552,
  "name":"Philomath",
  "level":"V",
  "activity":"BBX",
  "division":"4A",
  "league":"4A-4 (2014-2017)",
  "year":2014,
  "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":"http://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 for a specific team. Schedules are referenced by team ID.

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

See Contests node for data definitions. A schedule returns an array of contests* for the given team ID.

*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.)

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 can also be accessed.

Optional Parameters
level, year

http://www.osaa.org/api/contests/{id}
http://www.osaa.org/api/contests/{activity}
http://www.osaa.org/api/contests/{activity}/{date}
http://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
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
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) 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) 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	boolean	True if this contest was forfeited by the losing team (in which case refer to comments for more information), false otherwise
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

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

[{"id":14043,
  "year":2013,
  "activity":"VBL",
  "type":"PO",
  "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",
  "is_neutral":false,
  "is_tournament":false,
  "tournament":null,
  "is_endowment":false,
  "home":{"id":3218,
          "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,
          "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":false,
  "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: 994
Content-Count: 1

*All contests have one and only one contest type. Contest types are returned by their slug and are defined as follows:

J

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

EX

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

A

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

NL

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

L

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)

PI

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

PO

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

**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:

id

Integer - team's unique identification number, if any (OOS teams do not have 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

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

http://www.osaa.org/api/leagues
http://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

http://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.