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

"id": 61

"availableLanguages": ["en", "en-gb", "es-mx", "es-es", "pt", "de", "fr", "it", "pl", "ru", "ja", "ko", "zh-tw", "zh-cn"]

"name": "The Overwatch League"

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

"game": "OVERWATCH"

"logo": "https://bnetcmsus-a.akamaihd.net/cms/page_media/JEUWQ6CN33BR1507857496436.svg"

"competitorType": "TEAM"

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

"id": 4523

"divisionId": 80

"handle": "fuel.6990"

"name": "Boston Uprising"

"abbreviatedName": "ATL"

"hasFallback": false

"location": "Boston, MA"

"website": "https://fuel.overwatchleague.com"

"placement": 1

"advantage": 0

GET /ranking

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

Ranking Data Dictionary

"comparisons": ["MATCH_DIFFERENTIAL","MATCH_GAME_DIFFERENTIAL","GAME_HEAD_TO_HEAD_DIFFERENTIAL", "MATCH_HEAD_TO_HEAD_DIFFERENTIAL", "ADVANTAGE"]

 "totalMatches": 280

 "matchesConcluded": 16

"playoffCutoff": 6

GET /standings

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

Standings Data Dictionary

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" }]

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

"id": 3380

 "availableLanguages": [ "en" ]

"handle": "taimou.6010"

"name": "Taimou"

"homeLocation": "Juankoski"

"game": "OVERWATCH"

"familyName": "Kettunen"

"givenName": "Timo"

"nationality": "FI"

"headshot": "https://bnetcmsus-a.akamaihd.net/cms/gallery/DFRBV085AX601550194285520.png"

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

GET /live-match

Returns information regarding an ongoing live match.

Live Match Data Dictionary

GET /schedule

Returns the schedule for the current Overwatch League season.

Schedule Data Dictionary

"id": "2019"

"startDate": "02-14-2019"

"endDate": "08-27-2019"

"endDateMS": 1566975540000

"series": 181

GET /streams

Returns Overwatch League's stream information

Streams Data Dictionary

GET /vods

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

VODs Data Dictionary

GET /maps

Returns all of the available maps in Overwatch.

Maps Data Dictionary

GET /news

Returns Overwatch League news nformation.

News Data Dictionary