Skip to content

Latest commit

 

History

History
396 lines (325 loc) · 24.7 KB

README.md

File metadata and controls

396 lines (325 loc) · 24.7 KB
Raw

Overwatch League API Community Documentation

A community analysis of the Overwatch League API.

PRs Welcome

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

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!