Cloudy LoL Stats API

Welcome! This is the official documentation for my Cloudy LoL Stats API. I created this project to provide comprehensive, detailed statistics from professional League of Legends matches.

I designed this API to be simple, accessible, and powerful, allowing you to retrieve data on players, teams, champions, and specific matches with flexible filtering options.

Getting Started

Base URL

All API endpoints are relative to the following base URL:

https://cloudylol-api.up.railway.app

Authentication

My Cloudy LoL Stats API is completely open and does not require an API key or any form of authentication. You can start making requests right away.

Note: Please use my API responsibly to ensure it remains available for everyone.

API Endpoints

Metadata

Get Metadata

This endpoint returns aggregated information about the data available in my API, such as lists of all available leagues, years, teams, and total entity counts. I find this useful for populating filter options in a user interface.

GET /stats/metadata

Example Request (cURL):

curl --location 'https://cloudylol-api.up.railway.app/stats/metadata'

Example Response (200 OK):

{
  "leagues": [
    "LCK", "LPL", "LEC", "LCS", "MSI", "WCS"
  ],
  "years": [
    2023, 2024
  ],
  "splits": [
    "Summer", "Spring", "MSI", "Worlds", "Winter"
  ],
  "teams": [
    "T1", "Gen.G", "G2 Esports", "Fnatic", "JDG Intel Esports Club", "Bilibili Gaming"
  ],
  "playerCount": 850,
  "championCount": 167
}

Champions

Query Champion Statistics

This endpoint returns a list of aggregated statistics for champions. I made it highly flexible so it can be filtered by numerous parameters, including direct champion matchups.

GET /stats/champions

Query Parameters:

Name	Type	Required	Description
`champion`	string	No	Exact champion name (case-insensitive). Example:`Azir`.
`vsChampion`	string	No	Filters stats against a specific opponent champion. Requires the `champion` parameter.
`position`	string	No	Champion’s role. Possible values:`Top`, `Jungle`, `Mid`, `ADC`, `Support`.
`league`	string	No	League abbreviation. Example:`LEC`.
`year`	number	No	The season year. Example:`2024`.
`split`	string	No	The season split. Example:`Spring`.
`team`	string	No	Filters by matches played by a specific team. Example:`T1`.
`player`	string	No	Filters by matches played by a specific player. Example:`Faker`.
`startDate`	string	No	Start date for the data range in `YYYY-MM-DD` format.
`endDate`	string	No	End date for the data range in `YYYY-MM-DD` format.

Example Request (Specific Matchup):

curl --location 'https://cloudylol-api.up.railway.app/stats/champions?champion=Azir&vsChampion=Orianna&position=Mid'

Example Response (200 OK):

[
  {
    "champion": "Azir",
    "position": "Mid",
    "games_played": 25,
    "wins": 15,
    "losses": 10,
    "win_rate_pct": 60.0,
    "avg_kills": 3.1,
    "avg_deaths": 2.2,
    "avg_assists": 5.8,
    "kda": 4.0,
    "avg_kp_pct": 68.5,
    "avg_dpm": 650.1,
    "avg_damage_share_pct": 28.2,
    "avg_dtpm": 450.7,
    "avg_dmitpm": 310.2,
    "avg_cspm": 9.8,
    "avg_gpm": 455.0,
    "avg_gold_share_pct": 23.1,
    "avg_wpm": 0.8,
    "avg_wcpm": 0.35,
    "avg_vspm": 1.2,
    "avg_gold_diff_at_10": 150,
    "avg_xp_diff_at_10": 210,
    "avg_cs_diff_at_10": 8,
    "avg_gold_diff_at_15": 280,
    "avg_xp_diff_at_15": 350,
    "avg_cs_diff_at_15": 12
  }
]

Matches

Find Matches

This allows you to search for a list of match summaries based on a variety of filters. You can use the team parameter twice to find head-to-head results between two teams.

GET /stats/matches

Query Parameters:

Name	Type	Required	Description
`team`	string or array	No	Provide one team name for its matches, or two team names for head-to-head matchups.
`player`	string	No	Player name involved in the match.
`champion`	string	No	Champion name played in the match.
`league`	string	No	League abbreviation.
`year`	number	No	The season year.
`split`	string	No	The season split.
`startDate`	string	No	Start date in `YYYY-MM-DD` format.
`endDate`	string	No	End date in `YYYY-MM-DD` format.
`limit`	number	No	Maximum number of matches to return. Default:`50`, Max: `200`.

Example Request (Head-to-Head):

curl --location 'https://cloudylol-api.up.railway.app/stats/matches?team=G2%20Esports&team=Fnatic'

Example Response (200 OK):

[
  {
    "gameid": "ESPORTSTMNT01_3335749",
    "league": "LEC",
    "year": 2024,
    "split": "Spring",
    "date": "2024-03-24 18:03:18",
    "patch": "14.05",
    "blue_team": "G2 Esports",
    "red_team": "Fnatic",
    "blue_win": 1,
    "red_win": 0,
    "gamelength": 2105
  },
  {
    "gameid": "ESPORTSTMNT01_3329712",
    "league": "LEC",
    "year": 2024,
    "split": "Spring",
    "date": "2024-03-11 20:53:39",
    "patch": "14.04",
    "blue_team": "Fnatic",
    "red_team": "G2 Esports",
    "blue_win": 0,
    "red_win": 1,
    "gamelength": 1850
  }
]

Get Recent Matches

Returns a list of the most recent matches, sorted by date.

GET /stats/matches/recent

Query Parameters:

Name	Type	Required	Description
`limit`	number	No	Number of matches to return. Default: 10.

Example Request:

curl --location 'https://cloudylol-api.up.railway.app/stats/matches/recent?limit=3'

Get Match Details by ID

This returns detailed, player-by-player data for a single match, identified by its unique gameId.

GET /stats/matches/{gameId}

Path Parameters:

Name	Type	Description
`gameId`	string	The unique ID of the match. Example:`ESPORTSTMNT01_3335749`.

Example Request:

curl --location 'https://cloudylol-api.up.railway.app/stats/matches/ESPORTSTMNT01_3335749'

Example Response (200 OK): The response is an array containing an object for each player in the match.

[
  {
    "game_id": "ESPORTSTMNT01_3335749",
    "side": "Blue",
    "position": "top",
    "player_name": "BrokenBlade",
    "team_name": "G2 Esports",
    "champion": "K'Sante",
    "kills": 3,
    "deaths": 1,
    "assists": 6,
    "dpm": 345.6,
    "gold_diff_at_15": 450
  },
  {
    "game_id": "ESPORTSTMNT01_3335749",
    "side": "Blue",
    "position": "jng",
    "player_name": "Yike",
    "team_name": "G2 Esports",
    "champion": "Xin Zhao",
    "kills": 5,
    "deaths": 2,
    "assists": 8
  }
]

Error Handling

My API uses standard HTTP status codes to indicate the success or failure of a request.

200 OK: The request was successful.
404 Not Found: The requested resource could not be found (e.g., a gameId that does not exist).
422 Unprocessable Entity: The request was well-formed but contained validation errors (e.g., an incorrect data type for a parameter).
500 Internal Server Error: An unexpected error occurred on my server. If you encounter this error consistently, please let me know.

Example Error Response (404 Not Found):

{
  "statusCode": 404,
  "message": "Match with ID EXAMPLE_ID not found",
  "error": "Not Found"
}

Support & Feedback

I'm always looking to improve this project! If you find a bug, have a feature request, or have a question, the best way to reach me is by sending a DM on Twitter.

Twitter: @Cloudylol19

Name		Name	Last commit message	Last commit date
Latest commit History 15 Commits
src		src
.env.example		.env.example
.gitignore		.gitignore
.prettierrc		.prettierrc
README.md		README.md
doc.md		doc.md
eslint.config.mjs		eslint.config.mjs
nest-cli.json		nest-cli.json
package-lock.json		package-lock.json
package.json		package.json
tsconfig.build.json		tsconfig.build.json
tsconfig.json		tsconfig.json

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

Cloudy LoL Stats API

Table of Contents

Getting Started

Base URL

Authentication

API Endpoints

Metadata

Get Metadata

Champions

Query Champion Statistics

Matches

Find Matches

Get Recent Matches

Get Match Details by ID

Error Handling

Support & Feedback

About

Uh oh!

Releases

Packages

Uh oh!

Contributors

Uh oh!

Languages

Folders and files

Latest commit

History

Repository files navigation

Cloudy LoL Stats API

Table of Contents

Getting Started

Base URL

Authentication

API Endpoints

Metadata

Get Metadata

Champions

Query Champion Statistics

Matches

Find Matches

Get Recent Matches

Get Match Details by ID

Error Handling

Support & Feedback

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages