Skip to content

Instantly share code, notes, and snippets.

@brcooley

brcooley/api-lolesports-com_docs.md

Last active August 5, 2022 16:35
Show Gist options
  • Save brcooley/8429583561c47b248f80 to your computer and use it in GitHub Desktop.
Save brcooley/8429583561c47b248f80 to your computer and use it in GitHub Desktop.
Download ZIP
lolesports.com unofficial api docs
Raw
api-lolesports-com_docs.md

Unofficial documentation

This is an unofficial documentation for the internal lolesports.com api.

This documentation is uncomplete and currently only show all information I got so far. Please help me complete and correct this documentation.

Top level domain

The domain for the intern lolesports.com api is http://api.lolesports.com/api/.

There is also an api at http://na.lolesports.com/api/swagger#!/api/ but I feel like this is a bit outdated.

Api calls

leagues

Parameters:

  • id
  • slug

Example(s):

Top-level schema

{
  leagues: [
    leagues.0: {
      leagues.0.abouts: Object
      leagues.0.drupalId: Int
      leagues.0.region: Unknown
      leagues.0.updatedAt: String
      leagues.0.slug: String
      leagues.0.names: Object
      leagues.0.logoUrl: String
      leagues.0.id: Int
      leagues.0.createdAt: String
      leagues.0.name: String
    }
  ]
}

scheduleItems

Parameters:

  • leagueId (Required)

Example(s):

Top-level schema

{
  scheduleItems: [
    scheduleItems.0: {
      scheduleItems.0.league: String
      scheduleItems.0.tournament: String
      scheduleItems.0.tags: Object
      scheduleItems.0.scheduledTime: String
      scheduleItems.0.content: String
      scheduleItems.0.bracket: String
      scheduleItems.0.id: String
      scheduleItems.0.match: String
    }
  ]
  players: [
    players.??: Unknown
  ]
  highlanderTournaments: [
    highlanderTournaments.0: {
      highlanderTournaments.0.leagueReference: String
      highlanderTournaments.0.standings: Object
      highlanderTournaments.0.endDate: String
      highlanderTournaments.0.description: String
      highlanderTournaments.0.roles: Object
      highlanderTournaments.0.title: String
      highlanderTournaments.0.queues: Object
      highlanderTournaments.0.gameMode: Object
      highlanderTournaments.0.rosteringStrategy: Object
      highlanderTournaments.0.breakpoints: Object
      highlanderTournaments.0.league: String
      highlanderTournaments.0.liveMatches: List
      highlanderTournaments.0.rosters: Object
      highlanderTournaments.0.brackets: Object
      highlanderTournaments.0.matchType: Object
      highlanderTournaments.0.gameIds: List
      highlanderTournaments.0.startDate: String
      highlanderTournaments.0.id: String
      highlanderTournaments.0.platformIds: List
      highlanderTournaments.0.published: Boolean
    }
  ]
  teams: [
    teams.0: {
      teams.0.homeLeague: String
      teams.0.altLogoUrl: Unknown
      teams.0.name: String
      teams.0.players: List
      teams.0.acronym: String
      teams.0.updatedAt: String
      teams.0.teamPhotoUrl: String
      teams.0.slug: String
      teams.0.starters: List
      teams.0.bios: Object
      teams.0.logoUrl: String
      teams.0.foreignIds: Object
      teams.0.id: Int
      teams.0.createdAt: String
      teams.0.subs: List
    }
  ]
}

teams

Parameters:

  • slug (Required)
  • tournament (Required)

Example(s):

Top-level schema

{
  scheduleItems: [
    scheduleItems.??: Unknown
  ]
  teamStatsHistories: [
    teamStatsHistories.0: {
      teamStatsHistories.0.kills: Int
      teamStatsHistories.0.deaths: Int
      teamStatsHistories.0.timestamp: Int
      teamStatsHistories.0.team: Int
      teamStatsHistories.0.game: String
      teamStatsHistories.0.championIds: List
      teamStatsHistories.0.assists: Int
      teamStatsHistories.0.win: Boolean
      teamStatsHistories.0.id: String
      teamStatsHistories.0.match: String
      teamStatsHistories.0.opponent: Int
    }
  ]
  teams: [
    teams.0: {
      teams.0.homeLeague: String
      teams.0.altLogoUrl: Unknown
      teams.0.name: String
      teams.0.players: List
      teams.0.acronym: String
      teams.0.updatedAt: String
      teams.0.teamPhotoUrl: String
      teams.0.slug: String
      teams.0.starters: List
      teams.0.bios: Object
      teams.0.logoUrl: String
      teams.0.foreignIds: Object
      teams.0.id: Int
      teams.0.createdAt: String
      teams.0.subs: List
    }
  ]
  players: [
    players.0: {
      players.0.roleSlug: String
      players.0.teamRosterStat: String
      players.0.name: String
      players.0.firstName: String
      players.0.photoUrl: String
      players.0.lastName: String
      players.0.region: String
      players.0.updatedAt: String
      players.0.birthdate: Unknown
      players.0.slug: String
      players.0.bios: Object
      players.0.socialNetworks: Object
      players.0.hometown: String
      players.0.champions: List
      players.0.foreignIds: Object
      players.0.id: Int
      players.0.createdAt: String
    }
  ]
  teamStatsSummaries: [
    teamStatsSummaries.0: {
      teamStatsSummaries.0.kdaRatio: Float
      teamStatsSummaries.0.averageWinLength: Int
      teamStatsSummaries.0.firstDragonKillRatioRank: Int
      teamStatsSummaries.0.averageWinLengthRank: Int
      teamStatsSummaries.0.teamId: String
      teamStatsSummaries.0.averageDamageByPosition: Object
      teamStatsSummaries.0.firstDragonKillRatio: Float
      teamStatsSummaries.0.firstTowerRatioRank: Int
      teamStatsSummaries.0.kdaRatioRank: Int
      teamStatsSummaries.0.firstTowerRatio: Float
    }
  ]
  teamRosterStats: [
    teamRosterStats.0: {
      teamRosterStats.0.averageKillParticipation: Float
      teamRosterStats.0.summonerName: String
      teamRosterStats.0.playerId: String
      teamRosterStats.0.averageAssists: Float
      teamRosterStats.0.championIds: List
      teamRosterStats.0.averageDeaths: Float
      teamRosterStats.0.averageKills: Float
      teamRosterStats.0.gamesPlayed: Int
    }
  ]
  highlanderTournaments: [
    highlanderTournaments.0: {
      highlanderTournaments.0.leagueReference: String
      highlanderTournaments.0.standings: Object
      highlanderTournaments.0.description: String
      highlanderTournaments.0.roles: Object
      highlanderTournaments.0.title: String
      highlanderTournaments.0.rosters: Object
      highlanderTournaments.0.queues: Object
      highlanderTournaments.0.gameMode: Object
      highlanderTournaments.0.rosteringStrategy: Object
      highlanderTournaments.0.seedingStrategy: Object
      highlanderTournaments.0.liveMatches: List
      highlanderTournaments.0.bracketType: Object
      highlanderTournaments.0.brackets: Object
      highlanderTournaments.0.matchType: Object
      highlanderTournaments.0.gameIds: List
      highlanderTournaments.0.id: String
      highlanderTournaments.0.platformIds: List
      highlanderTournaments.0.published: Boolean
    }
  ]
}

players

Parameters:

  • slug (Required)
  • tournament (Required)

Example(s):

Top-level schema

{
  scheduleItems: [
    scheduleItems.??: Unknown
  ]
  playerStatsSummaries: [
    playerStatsSummaries.0: {
      playerStatsSummaries.0.csPerTenMinutes: Float
      playerStatsSummaries.0.killParticipationRank: Int
      playerStatsSummaries.0.playerId: String
      playerStatsSummaries.0.kdaRatio: Float
      playerStatsSummaries.0.killParticipation: Float
      playerStatsSummaries.0.mostPlayedChampions: List
      playerStatsSummaries.0.csPerTenMinutesRank: Int
      playerStatsSummaries.0.kdaRatioRank: Int
    }
  ]
  playerStatsHistories: [
    playerStatsHistories.0: {
      playerStatsHistories.0.championId: Int
      playerStatsHistories.0.kills: Int
      playerStatsHistories.0.deaths: Int
      playerStatsHistories.0.playerId: String
      playerStatsHistories.0.timestamp: Int
      playerStatsHistories.0.team: Int
      playerStatsHistories.0.kdaRatio: Int
      playerStatsHistories.0.game: String
      playerStatsHistories.0.killParticipation: Int
      playerStatsHistories.0.assists: Int
      playerStatsHistories.0.win: Boolean
      playerStatsHistories.0.csPerTenMin: Float
      playerStatsHistories.0.id: String
      playerStatsHistories.0.match: String
      playerStatsHistories.0.opponent: Int
    }
  ]
  teams: [
    teams.0: {
      teams.0.homeLeague: String
      teams.0.altLogoUrl: Unknown
      teams.0.name: String
      teams.0.players: List
      teams.0.acronym: String
      teams.0.updatedAt: String
      teams.0.teamPhotoUrl: String
      teams.0.slug: String
      teams.0.starters: List
      teams.0.bios: Object
      teams.0.logoUrl: String
      teams.0.foreignIds: Object
      teams.0.id: Int
      teams.0.createdAt: String
      teams.0.subs: List
    }
  ]
  players: [
    players.0: {
      players.0.photoUrl: String
      players.0.hometown: String
      players.0.playerStatsSummary: String
      players.0.updatedAt: String
      players.0.subOnTeams: List
      players.0.id: Int
      players.0.createdAt: String
      players.0.roleSlug: String
      players.0.champions: List
      players.0.bios: Object
      players.0.socialNetworks: Object
      players.0.scheduleItems: List
      players.0.playerStatsHistory: List
      players.0.photoInformation: Object
      players.0.foreignIds: Object
      players.0.slug: String
      players.0.name: String
      players.0.firstName: String
      players.0.lastName: String
      players.0.region: String
      players.0.birthdate: Unknown
      players.0.teams: List
      players.0.starterOnTeams: List
    }
  ]
  highlanderTournaments: [
    highlanderTournaments.0: {
      highlanderTournaments.0.leagueReference: String
      highlanderTournaments.0.description: String
      highlanderTournaments.0.roles: Object
      highlanderTournaments.0.title: String
      highlanderTournaments.0.rosters: Object
      highlanderTournaments.0.queues: Object
      highlanderTournaments.0.gameMode: Object
      highlanderTournaments.0.rosteringStrategy: Object
      highlanderTournaments.0.seedingStrategy: Object
      highlanderTournaments.0.liveMatches: List
      highlanderTournaments.0.bracketType: Object
      highlanderTournaments.0.brackets: Object
      highlanderTournaments.0.matchType: Object
      highlanderTournaments.0.gameIds: List
      highlanderTournaments.0.id: String
      highlanderTournaments.0.platformIds: List
      highlanderTournaments.0.published: Boolean
    }
  ]
}

highlanderTournaments

Parameters:

  • league (Required)

Example(s):

Top-level schema

{
  highlanderTournaments: [
    highlanderTournaments.0: {
      highlanderTournaments.0.leagueReference: String
      highlanderTournaments.0.standings: Object
      highlanderTournaments.0.endDate: String
      highlanderTournaments.0.description: String
      highlanderTournaments.0.roles: Object
      highlanderTournaments.0.title: String
      highlanderTournaments.0.queues: Object
      highlanderTournaments.0.gameMode: Object
      highlanderTournaments.0.rosteringStrategy: Object
      highlanderTournaments.0.breakpoints: Object
      highlanderTournaments.0.league: String
      highlanderTournaments.0.liveMatches: List
      highlanderTournaments.0.rosters: Object
      highlanderTournaments.0.brackets: Object
      highlanderTournaments.0.matchType: Object
      highlanderTournaments.0.gameIds: List
      highlanderTournaments.0.startDate: String
      highlanderTournaments.0.id: String
      highlanderTournaments.0.platformIds: List
      highlanderTournaments.0.published: Boolean
    }
  ]
}

highlanderMatchDetails

Parameters:

  • tournamentId (Required)
  • matchId (Required)

Example(s):

Top-level schema

{
  scheduleItems: [
    scheduleItems.0: {
      scheduleItems.0.league: String
      scheduleItems.0.tournament: String
      scheduleItems.0.tags: Object
      scheduleItems.0.scheduledTime: String
      scheduleItems.0.content: String
      scheduleItems.0.bracket: String
      scheduleItems.0.id: String
      scheduleItems.0.match: String
    }
  ]
  videos: [
    videos.0: {
      videos.0.slug: Unknown
      videos.0.reference: String
      videos.0.locale: String
      videos.0.label: Unknown
      videos.0.source: String
      videos.0.game: String
      videos.0.updatedAt: String
      videos.0.id: Int
      videos.0.createdAt: String
    }
  ]
  htmlBlocks: [
    htmlBlocks.??: Unknown
  ]
  gameIdMappings: [
    gameIdMappings.0: {
      gameIdMappings.0.gameHash: String
      gameIdMappings.0.id: String
    }
  ]
  teams: [
    teams.0: {
      teams.0.homeLeague: String
      teams.0.altLogoUrl: Unknown
      teams.0.name: String
      teams.0.players: List
      teams.0.acronym: String
      teams.0.updatedAt: String
      teams.0.teamPhotoUrl: String
      teams.0.slug: String
      teams.0.starters: List
      teams.0.bios: Object
      teams.0.logoUrl: String
      teams.0.foreignIds: Object
      teams.0.id: Int
      teams.0.createdAt: String
      teams.0.subs: List
    }
  ]
  players: [
    players.0: {
      players.0.roleSlug: String
      players.0.name: String
      players.0.firstName: String
      players.0.photoUrl: String
      players.0.lastName: String
      players.0.region: String
      players.0.updatedAt: String
      players.0.birthdate: Unknown
      players.0.slug: String
      players.0.bios: Object
      players.0.socialNetworks: Object
      players.0.hometown: String
      players.0.champions: List
      players.0.liveGameTeam: Int
      players.0.foreignIds: Object
      players.0.id: Int
      players.0.createdAt: String
    }
  ]
}

tournamentPlayerStats

Parameters:

  • tournamentId (Required)

Example(s):

Top-level schema

{
  stats: [
    stats.0: {
      stats.0.teamSlug: String
      stats.0.name: String
      stats.0.kills: Int
      stats.0.deaths: Int
      stats.0.kda: Float
      stats.0.csPerMin: Float
      stats.0.playerSlug: String
      stats.0.killParticipation: Float
      stats.0.assists: Int
      stats.0.team: String
      stats.0.cs: Int
      stats.0.position: String
      stats.0.gamesPlayed: Int
      stats.0.id: Int
      stats.0.minutesPlayed: Int
    }
  ]
}

articles

Parameters:

  • language
  • from

Example(s):

Top-level schema

{
  articles: [
    articles.0: {
      articles.0.author: String
      articles.0.locale: String
      articles.0.externalScripts: List
      articles.0.bodySmall: Unknown
      articles.0.customTemplate: String
      articles.0.category: Object
      articles.0.uuid: String
      articles.0.title: String
      articles.0.tuuid: String
      articles.0.media: Object
      articles.0.comments: Object
      articles.0.type: String
      articles.0.status: Int
      articles.0.redirect: Unknown
      articles.0.tags: Unknown
      articles.0.nid: String
      articles.0.path: Object
      articles.0.bodyFull: String
      articles.0.shortTitle: String
      articles.0.language: String
      articles.0.created: String
      articles.0.showIn: Unknown
      articles.0.region: String
      articles.0.changed: String
      articles.0.published: String
      articles.0.bodyMedium: Unknown
      articles.0.backdrop: List
    }
  ]
}

marquees

Parameters:

  • locale (Required)

Example(s):

Top-level schema

{
  marqueeItems: [
    marqueeItems.0: {
      marqueeItems.0.priority: Int
      marqueeItems.0.marqueeId: Int
      marqueeItems.0.updatedAt: String
      marqueeItems.0.tier: Int
      marqueeItems.0.article: String
      marqueeItems.0.id: Int
      marqueeItems.0.createdAt: String
    }
  ]
  articles: [
    articles.0: {
      articles.0.author: String
      articles.0.locale: String
      articles.0.externalScripts: List
      articles.0.bodySmall: Unknown
      articles.0.customTemplate: String
      articles.0.category: Object
      articles.0.uuid: String
      articles.0.title: String
      articles.0.tuuid: String
      articles.0.media: Object
      articles.0.comments: Object
      articles.0.type: String
      articles.0.status: Int
      articles.0.redirect: Unknown
      articles.0.tags: Unknown
      articles.0.nid: String
      articles.0.path: Object
      articles.0.bodyFull: String
      articles.0.shortTitle: String
      articles.0.language: String
      articles.0.created: String
      articles.0.showIn: Unknown
      articles.0.region: String
      articles.0.changed: String
      articles.0.published: String
      articles.0.bodyMedium: Unknown
      articles.0.backdrop: List
    }
  ]
  marquees: [
    marquees.0: {
      marquees.0.marqueeItems: List
      marquees.0.locale: String
      marquees.0.publishDate: String
      marquees.0.id: Int
      marquees.0.updatedAt: String
      marquees.0.slug: String
      marquees.0.createdAt: String
    }
  ]
}

htmlBlocks

Parameters:

  • None

Example(s):

Top-level schema

{
  htmlBlocks: [
    htmlBlocks.0: {
      htmlBlocks.0.locale: String
      htmlBlocks.0.content: String
      htmlBlocks.0.contentType: String
      htmlBlocks.0.compositeId: String
    }
  ]
}

videos

Paramters:

  • None

Example(s):

Top-level schema

{
  videos: [
    videos.0: {
      videos.0.slug: Unknown
      videos.0.reference: String
      videos.0.locale: String
      videos.0.label: Unknown
      videos.0.source: String
      videos.0.game: String
      videos.0.updatedAt: String
      videos.0.id: Int
      videos.0.createdAt: String
    }
  ]
}

streamgroups

Parameters:

  • None

Example(s):

Top-level schema

{
  streams: [
    streams.??: Unknown
  ]
  highlanderTournaments: [
    highlanderTournaments.??: Unknown
  ]
  streamgroups: [
    streamgroups.0: {
      streamgroups.0.showAd: Boolean
      streamgroups.0.showBanner: Boolean
      streamgroups.0.showSchedule: Boolean
      streamgroups.0.title: String
      streamgroups.0.nowPlaying: String
      streamgroups.0.adLargeImage: Unknown
      streamgroups.0.slug: String
      streamgroups.0.showStat: Boolean
      streamgroups.0.live: Boolean
      streamgroups.0.streams: List
      streamgroups.0.updatedAt: String
      streamgroups.0.showSocial: Boolean
      streamgroups.0.bannerId: Unknown
      streamgroups.0.regionPriority: Unknown
      streamgroups.0.adSmallImage: Unknown
      streamgroups.0.id: Int
      streamgroups.0.createdAt: String
      streamgroups.0.adUrl: Unknown
    }
  ]
  players: [
    players.??: Unknown
  ]
  teams: [
    teams.??: Unknown
  ]
}
Raw
generate_schema.py
# Helper functions to generate a schema from an input json file.
# Sample usage:
# >>> x = json.load(open('path/to/json_file.json', 'r')
# >>> jschema(x)
def jschema(json_obj, max_depth=3):
'''Takes a json object and returns a schema with type information.'''
def rgt(json_obj, level, field_name):
if level > max_depth:
return
elif level == max_depth:
term_print(field_name, json_obj, level)
return
if isinstance(json_obj, types.ListType):
lprint('{}: ['.format(field_name), level)
if len(json_obj) == 0:
term_print(field_name + '.??', None, level + 1)
else:
rgt(json_obj[0], level + 1, field_name + '.0')
lprint(']', level)
elif isinstance(json_obj, types.DictType):
lprint('{}: {{'.format(field_name), level)
if len(json_obj.keys()) == 0:
term_print(field_name + '.??', None, level)
for k in json_obj.keys():
rgt(json_obj[k], level + 1, field_name + '.' + k)
lprint('}', level)
else:
term_print(field_name, json_obj, level)
rgt(json_obj, 0, '')
def lprint(string_to_print, level):
print('{}{}'.format(' ' * level, string_to_print))
def term_print(field_name, json_obj, level):
pretty_types = {
types.BooleanType: 'Boolean',
types.IntType: 'Int',
types.UnicodeType: 'String',
types.StringType: 'String',
types.DictType: 'Object',
types.ListType: 'List',
types.NoneType: 'Unknown',
}
lprint('{}: {}'.format(field_name, pretty_types[type(json_obj)]), level)
@wyatt-p
Copy link

wyatt-p commented Jan 2, 2020

Does anyone know the limitations of the api in terms of request limits?

@SeanDrum
Copy link

Has Riot changed scheduleItems? I try to hit

http://api.lolesports.com/api/v1/scheduleItems?leagueId=2 (LCS)
or
http://api.lolesports.com/api/v1/scheduleItems?leagueId=3 (LEC)

But I don't see the latest tournaments added for Spring 2020. If you can't get this data you can't get the match list and that's the top of the stack for extracting data as far as I can tell.

@tsevenhuysen
Copy link

tsevenhuysen commented Jan 27, 2020 •
edited
Loading

The lolesports API is no longer being maintained as of 2020. Sorry!

I've been speaking with people at Riot about alternatives but so far the only thing you can do is find match histories on a wiki.

I might start posting links of MH URLs on Oracle's Elixir if I won't get in trouble for it.

@SeanDrum
Copy link

SeanDrum commented Jan 27, 2020 •
edited
Loading

[EDIT after you edited your response - I know the MHs are already hosted on Leaguepedia's Runes page https://lol.gamepedia.com/LCS/2020_Season/Spring_Season/Runes so unless they have a special get out of jail free card I think this is admissable]

Tim, thanks so much for your response. Big fan of your work, btw.

I know there's still bits of the public APIs that work because the matchhistory pages are still active. Could you clue me in to how so many folks still getting this data seemingly programmatically (Oracle's Elixir, Leaguepedia, E1 Fantasy). Any insight into how the new API works (if publicly available) would be absolutely wonderful. Otherwise, I have to assume the "big players" have exclusive access through an agreement with Riot?

@tsevenhuysen
Copy link

Basically, any commercial use (such as E1 Fantasy) is coming through a new paid API.

Any community access (OE, GoL.gg, wikis) is coming directly from contacts at Riot, who are doing the best they can to help out in the absence of an official community-facing solution.

So for non-commercial/community projects there is no programmatic solution at the moment. I hope there will be soon!

@xaxaxa111111
Copy link

Hi Tim, have you found any resources for lpl with play-by-play matches? Thanks :) I saw your website and it's cool you offer free match data. great work!

@SeanDrum
Copy link

SeanDrum commented Mar 15, 2020 •
edited
Loading

My understanding is at least LCS and LEC are hosted on a completely different cluster of servers than the infrastructure that hosts regular SoloQ etc. data and stats. I think Riot refers to them as "realms" but I'm not sure. That's why you can't just access esports data the same way you can any other account, the server cluster is different. LPL is a completely different infrastructure still, hosted by Tencent and not Riot. Last I checked (about 6 months ago) the official LPL website has a JSON-based RESTful API to power the stats on their pages. You could figure out how that works and get the data specifically for the LPL that way. Most of the fields are in Chinese so that's fun. :-)

As to how Tim manages to get that data? My guess it's a combination of manual and tapping the official LPL page.

I took a quick list in my bookmarks and I found these notes:
LPL Search by Year
http://apps.game.qq.com/lol/match/apis/searchBMatchInfo_bak.php?p8=5&p1=&p9=2017-07-06%2000:00:00&p10=2018-07-13%2023:59:59&p6=3&page=1&pagesize=100&r1=retObj&_=1530899983861

API Search for matches (bMatchId)
http://apps.game.qq.com/lol/match/apis/searchBMatchInfo_bak.php?p8=&p1=&p9=2018-07-06%2000:00:00&p10=2018-07-13%2023:59:59&p6=3&page=1&pagesize=10&r1=retObj&_=1530899983861

Get a list of games in this series
http://apps.game.qq.com/lol/match/apis/searchSMatchList.php?p0=3563

The actual data you want:
http://apps.game.qq.com/lol/match/apis/searchMatchInfo_s.php?p0=4390&r1=MatchInfo&_=1530896680313

@tsevenhuysen
Copy link

@xaxaxa111111 You can use the info SeanDrum shared if you have any programming familiarity. :)

@xaxaxa111111
Copy link

wow great find @SeanDrum. I will check it. Thanks for the information. Btw, I found this website thought you might get interested. https://www.wanplus.com/event/907.html

@chevidal45
Copy link

Hi I am new to this, I would like to be able to access the data of a game in real time of LEC or a game of some regional league. Does anyone have any idea if this is possible?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment