Overwatch League API Community Documentation

A community analysis of the Overwatch League API.

Disclaimer

The Overwatch League API is not officially supported by Blizzard, and is subject to change at any time. The documentation for the API is developed by the community, and may or may not be complete. Use at your own risk.

Contributing

Join our Unofficial Discord Server you want to contribute, ask questions, or share projects using the OWL API!

You can also create an issue or a PR. Before creating an issue,please ensure that it hasn't already been reported/suggested, and double-check the documentation. See the contribution guide if you'd like to submit a PR.

Let's get in touch on Twitter or Discord if you have any questions or comments!

Getting Started

The Overwatch League is on a mission to celebrate fans and afford them opportunities to become champions through a professional esports ecosystem that embraces passion and rewards excellence. This API enables developers to have real time information about teams, players, match updates, and much more!

The API is a RESTful Resource

Overwatch League API endpoints conform to the design principles of Representational State Transfer (REST). This API uses the JSON data format for responses.

The API is HTTP-based over SSL

A GET request is required to retrieve data from the Overwatch League API. Methods that submit, change or destroy data require a POST. A DELETE request is also accepted for methods that destroy data. API methods that require a particular HTTP method will return an error if not invoked using the correct endpoint or style.

Root URL

You can access the base API here at https://api.overwatchleague.com (China: https://api.overwatchleague.cn). Upon entering you'll see the following easter egg:

GET /

{
    "the world": "could always use more heroes"
}

API Endpoints Overview

Here are the endpoints used to access Overwatch League's information such as player information, match updates, league standings, news reports, and much more. This document will be going over these objects in more detail.

Endoints and Objects

User Endpoints

GET /login
GET /auth/bnet/callback?code=:code
GET /user
GET /user/favorites
POST /user/favorites
POST /user/favorites/order
DELETE /user/favorites/:id

Team Endpoints

GET /v2/teams
GET /v2/teams/:id
GET /ranking
GET /standings

Player Endpoints

GET /players
GET /players/:id

Match Endpoints

GET /matches
GET /matches/:id
GET /live-match
GET /schedule
GET /streams
GET /vods
GET /maps
GET /news

Additonal Endpoints

GET /playlist/owl-app-playlist
GET /about

Objects

• Account
• Blog
• Bracket
• Colors
• Competitor
• Game
• Game Mode
• Live Match
• Logo
• Match
• Next Match
• Player
• Records
• VOD

Endpoint Locales

Reponses can be returned in several locales (a language and region identidier). The data will then be returned in the specified language.

• Locales
  • de_DE - German
  • en_US - English (United States)
  • en_GB - English (Great Britain)
  • es_ES - Spanish (Spain)
  • es_MX - Spanish (Mexico)
  • fr_FR - French
  • it_IT - Italian
  • pt_BR - Portuguese
  • pl_PL - Polish
  • ru_RU - Russian
  • ko_KR - Korean
  • ja_JP - Japanese
  • zh_TW - Chinese (Taiwan)
  • zh_CH - Chinese (China)
    • It is recommended to use the root URL for China listed above.

API Endpoint Guides

Here this guide will go over in detail each use of the above endpoints.

Authentication Endpoints

The following endpoints involve authenticating a Battle.net account, and authorizatino code use:

GET /login

• Redirects clients to the Battle.net login page.
• NOTE: This may direct you to a page that cannot be opened by your browser if you are already logged into your Battle.net account.

GET /auth/bnet/callback?code=:code

• Callback
• code - Battle.net authorization code

User Endpoints

The following endpoints retrieve user information.

GET /user

• Returns Uaer info. Token required.

GET /user/favorites

• Returns the User's favorite Overwatch League Teams.

POST /user/favorites

• Adds an Overwatch League Team to a User's Favorite Teams collection.

POST /user/favorites
{
  "id" : "4525",
  "tags" : [
    "owl"
  ],
  "franchise" : "overwatch"
}

POST /user/favorites/order

• Updates the order of the User's favorite teams.

POST /user/favorites/order
{
    "ids": [
        "4525"
    ]
}

DELETE /user/favorites/:id

Deletes a favorite team from a User.

Team Endpoints

The following endpoints retrieve information for Overwatch League Teams.

Team IDs

Each Overwatch League Team has a unique integer identifier (ID) which can be found upon visiting each team page on https://overwatchleague.com. For example, at the end of this URL is the ID for Atlanta Reign:

https://overwatchleague.com/en-us/teams/7698

We see that Atlanta Reign's ID following /teams/ is 7698. We can use this to retrieve information about Atlanta Reign's players, statistics, and more.

Below is a table of all team IDs for retrieving information for specific teams:

Team	ID
Atlanta Reign	7698
Boston Uprising	4402
Chengdu Hunters	7692
Dallas Fuel	4523
Florida Mayhem	4407
Guangzhou Charge	7699
Hangzhou Spark	7693
Houston Outlaws	4525
London Spitfire	4410
Los Angeles Gladiators	4406
Los Angeles Valiant	4405
New York Excelsior	4403
Paris Eternal	7694
Philadelphia Fusion	4524
San Francisco Shock	4404
Seoul Dynasty	4409
Shanghai Dragons	4408
Toronto Defiant	7695
Vancouver Titans	7696
Washington Justice	7697

GET /v2/teams

Returns all competing Overwatch League teams.

Teams Data Dictionary

Attribute	Type	Description
id	Int64	The unique integer for this League season. Example: "id": 61
availableLanguages	Array of String	Indicates a list of country and language codes. Example: "availableLanguages": ["en", "en-gb", "es-mx", "es-es", "pt", "de", "fr", "it", "pl", "ru", "ja", "ko", "zh-tw", "zh-cn"] Languages: Engish, English (Great Britian), Spanish (Mexico), Spanish (Spain), Portuguese, German, French, Italian, Polish, Russian, Japanese, Korean, Chinese (Taiwan), Chinease (China)
name	String	The name of the League. Example: "name": "The Overwatch League"
description	String	A summary of the Overwatch League. Example: "description": "The Overwatch League is on a mission to celebrate fans and afford them opportunities to become champions through a professional esports ecosystem that embraces passion and rewards excellence."
competitors	Array of Competitor Object	Competitors are Overwatch League Teams competing in the current Overwatch League Season. Additionally, see Competitor Object for more info.
game	String	The String representation of the game being played. Example: "game": "OVERWATCH"
logo	String	A URL leading to the Overwatch League Logo. Example: "logo": "https://bnetcmsus-a.akamaihd.net/cms/page_media/JEUWQ6CN33BR1507857496436.svg"
competitorType	String	Describes the type of Competitors competing in the Overwatch League. Example: "competitorType": "TEAM"
owl_division	Array of Division Objects	The Divisions making up the Overwatch League. Example: owl_divisions": [ {   "id": "79",   "string": "owl.teams.divisions.atlantic",   "name": "Atlantic Division",   "abbrev": "ATL" }, {   "id": "80",   "string": "owl.teams.divisions.pacific",   "name": "Pacific Division",   "abbrev": "PAC" }]

GET /v2/teams/:id

Returns information for a single Overwatch League Team given a Team ID. For exmaple, to retrieve information about Boston Uprising we can add Boston Uprising's ID at the end of the URL:

https://api.overwatchleague.com/v2/teams/4402

Team Data Dictionary

Attribute	Type	Description
id	Int64	The unique integer identifier for the Overwatch League Team. Example: "id": 4523
divisionId	Int64	The unique integer identifier for the Team's Overwatch League Division. The Atlanatic Division has an id of 79, and the Pacific Division's id is 80. Example: "divisionId": 80
handle	String	A String representation of an Overwatch League team's handle. Example: "handle": "fuel.6990"
name	String	A String representation of an Overwatch League team's name. Example: "name": "Boston Uprising"
abbreviatedName	String	A String representation of an Overwatch League team's 3 letter abbreviated name. Example: "abbreviatedName": "ATL"
logo	Logo Object	A Logo object containing an Overwatch League team's logo in SVG and PNG formats.
hasFallback	Boolean	Indicates whether or not a team has media queries which specific browsers cannot handle, such as logo files and headshot files. Example: "hasFallback": false
location	String	A String representation of an Overwatch League team's base location. Example: "location": "Boston, MA"
players	Array of Player Object	A Player roster for a competing Overwatch League Team. Additionally, see Player Object for more info.
website	String	A String representation of an Overwatch League team's website url. Example: "website": "https://fuel.overwatchleague.com"
placement	Int64	The current standing of an Overwatch League Team. Example: "placement": 1
advantage	Int64	An integer indicating the advantage an Overwatch League Team has over its competitors. Example: "advantage": 0
records	Records Object	A Records object containing an Overwatch League team's league records. See Records object for more info.

GET /ranking

Returns an Array of Competitors ordered by placement in the Overwatch League.

Ranking Data Dictionary

Attribute	Type	Description
content	Array of Competitor Object	An Array of Competitors competing in the current Overwatch League Season
comparisons	Array of String	An Array containing the differentials used to rank all Overwatch League Competitors. Example: "comparisons": ["MATCH_DIFFERENTIAL","MATCH_GAME_DIFFERENTIAL","GAME_HEAD_TO_HEAD_DIFFERENTIAL", "MATCH_HEAD_TO_HEAD_DIFFERENTIAL", "ADVANTAGE"]
totalMatches	Int64	Total numbers of matches to be played in the current Overwatch League season. Example: "totalMatches": 280
matchesConcluded	Int64	The number of matches that have been played in the current Overwatch League season. Example: "matchesConcluded": 16
playoffCutoff	Int64	The number of teams eligible to compete in the Overwatch League Playoffs. Example: "playoffCutoff": 6

GET /standings

Returns an Array of Competitors ordered by placement in the Overwatch League.

Standings Data Dictionary

Attribute	Type	Description
owl_divisions	Array of Division Object	Contains all the divisions for the current Overwatch League Season. Example: owl_divisions": [ {   "id": "79",   "string": "owl.teams.divisions.atlantic",   "name": "Atlantic Division",   "abbrev": "ATL" }, {   "id": "80",   "string": "owl.teams.divisions.pacific",   "name": "Pacific Division",   "abbrev": "PAC" }]
playoff_separators	Array of Int64	An Array of Integers indicating the stages for the current season of the Overwatch League Playoffs
season	Array of Competitor Objects	A season is comprised of Competitors organized in Divisions. This will return two groups of Competitor arrays inside a parent Division object.
ranks	Array of Competitor Objects	An Array of Competitors sorted by current standinds in the Overwatch League. Comparison values include match differentials, match game differentials, game head to head differentials, match head to head differentials, and advantage.

Player Endpoints

The following endpoints retrieve information for Overwatch League Teams.

GET /players

Returns a Array of Player Objects representing players competitng in the current Overwatch League season.

GET /players/:id

Returns a single Overwatch League Player when given the Player's ID.

Player Data Dictionary

Attribute	Type	Description
id	Int64	A unique integer identifier for an Overwatch League Player. Example: "id": 3380
availableLanguages	Array of Strings Objects	An array of language abbreviations indicating the avaliable languas for player information. Example: "availableLanguages": [ "en" ]
handle	String	The name of the Player's Battle.net account. Example: "handle": "taimou.6010"
name	String	The Player's Overwatch username. Example: "name": "Taimou"
homeLocation	String	The Player's hometown. Example: "homeLocation": "Juankoski"
accounts	Array of Account Objects	An array containing all of the Player's social media accounts.
game	String	The name of the game associated with the Player. Example: "game": "OVERWATCH"
attributes	Attribute Object	An Object containing information about a Player's most played heroes, player number, preferred slot, and role.
attributesVersion	String	A String representation of the attribute version.
familyName	String	The Player's last name. Example: "familyName": "Kettunen"
givenName	String	The Player's first name. Example: "givenName": "Timo"
nationality	String	A two letter abbrevition denoting the player's home country. Example: "nationality": "FI"
headshot	String	A String represenation of a Player's headshot URL. Example: "headshot": "https://bnetcmsus-a.akamaihd.net/cms/gallery/DFRBV085AX601550194285520.png"
teams	Array of Competitor Objects	An array of the Player's teams
stats	Object	An object consisting of the Players average stats per 10 minutes(i.e. eliminations, deaths, hero damage, healing, final blows), total time played in the Overwatch League, and top heroes.
statRank	Object	An object consisting of the Players stat ranks. Ranked stats include stats per 10 minutes (i.e. eliminations, deaths, hero damage, healing, final blows) and total time played in the Overwatch League.
team	Object	An object consisting of the Player's Team information.

Match Endpoints

The following endpoints retrieve information for Overwatch League Matches.

GET /matches

Returns an array of Match objects. This denotes all matches in the Overwatch League.

GET /matches/:id

Returns information about a single Overwatch League Match given a Match ID.

Match Data Dictionary

Attribute	Type	Description
id	Int64	The unique Integer identifier for a singel Overwatch League Match
competitors	Array of Competitor Objects	An Array containing the information of two competitng teams for an Overwatch League Match.
scores	Array of Int64	An array containing the currents scores for two Overwatch League Competitors respectively.
conclusionValue	Int64	The number of games for a single Overwatch League Match
conclusionStrategy	String	A string representation of an Overwatch League Match conclusion.
winner	Competitor Object	A Competitor object representing the winning team in an Overwatch League Match.
home	String	A string indicating the home location of a match.
bracket	Bracket Object	A Bracket Object which denotes the tournament infornation and stage information.

GET /live-match

Returns information regarding an ongoing live match.

Live Match Data Dictionary

Attribute	Type	Description
liveMatch	Live Match Object	A Live Match object with information about the current match.
nextMatch	Next Match Object	A Next Match object with information about the next match.

GET /schedule

Returns the schedule for the current Overwatch League season.

Schedule Data Dictionary

Attribute	Type	Description
id	String	A String identifier indicating the year of the current Overwatch League Season. Example: "id": "2019"
startDate	String	A String representing the start date of the current Overwatch League season. Example: "startDate": "02-14-2019"
endDate	String	A String representing the end date of the current Overwatch League season. Example: "endDate": "08-27-2019"
endDateMS	Int64	An Integer representing the end date of the current Overwatch League season. Example: "endDateMS": 1566975540000
seriesId	Int64	A unique integer identifier for the Overwatch League series. Example: "series": 181
stages	Array of Stage Objects	A list of all stages for the Overwatch League

GET /streams

Returns Overwatch League's stream information

Streams Data Dictionary

Attribute	Type	Description
id	Int64	A unique integer identifier for the Overwatch League's stream.
name	String	The stream title.
slug	String	The partt of a URL which identifies the Overwatch League stream on the stream's site.
subtitle	String	The sub text for the stream.
description	String	The current stream description.
stream_name	String	The name of the stream's host channel.
is_hidden	Boolean	Indicates if a stream information is hidden or not on the Overwatch League website.
image_6_9_small	String	A URL of the Overwatch League stream icon.
tags	Array of Strings	A list of tags for the Overwatch League streams.
status	Integer	Indicates whether or not the stream is visible and live
channel_id	Int64	A unique integer identifier for the Overwatch League's Twitch channel.
cdn	String	The name of the cache measurement mechanism for content delivery

GET /vods

Returns a list of videos on demand from https://overwatchleague.com

VODs Data Dictionary

Attribute	Type	Description
status	String	Indicates if the list of vods were retrieved or not.
code	Int64	Indicates if the list of vods were retrieved or not.
data	Array of VOD Objects	A List of available VODs on https://overwatchleague.com

GET /maps

Returns all of the available maps in Overwatch.

Maps Data Dictionary

Attribute	Type	Description
guid	Int128	A Globally Unique Identifier for an Overwatch Map.
name	Name object	An object with the name of a map in different languages.
gameModes	Array of Game Mode Objects	A list of available modes for a map. Each Game Mode has an Id, Name, and Key.
id	String	A string identifier of the map. This is typically the english name of the map.
icon	String	A URL of the map icon.
thumbnail	String	A URL of the map thumbnail.
type	String	The type of map. There are four types of maps used in the Overwatch League: Control, Hybrid, Assault, and Escort.

GET /news

Returns Overwatch League news nformation.

News Data Dictionary

Attribute	Type	Description
totalBlogs	Int64	An integer indicating the total number of blogs published on the Overwatch League website.
pageSize	Int64	The number of blog posts per page.
page	Int64	The current page of blogs as seen on https://overwatchleague.com
totalPages	Int64	The total number of blog post pages available on https://overwatchleague.com
blogs	Array of Blog Objects	A lists of blog posts on a specified page.

---

Thank you for reading! If you have anymore questions or want to share your work, click here to join the server if you haven't already!