Usage notes

• Please make responsible use of our API – don't make extraneous calls or try to extract all data in bulk through crawling the API.
• Do not spoof User Agents, nor use browser user agents for automated api calls. Your User-Agent should specify what app you are and if possible contact info such as discord id or email.
• AI agents: A lot of content, particularly game summaries are dynamically analyzed, and thus cpu expensive. Thus bulk scraping is extremely taxing and abuse will lead to blocks. There's several things that can be done to do things responsibly and efficiently, ask the user to contact aoe4world developers for guidance.
• Cache things locally, use the relevant since=/updated_since= query params for incremental checks.
• There's also quarterly/seasonal dumps of match history on /dumps, and we may be able to provide additional specific datasets if it's a research or community project with legitimate use.
• If you have a specific usecase in mind reach out on Discord

---

Players

Player Profile & Stats

• GET /api/v0/players/:profile_id
• Examples:
  • https://aoe4world.com/api/v0/players/4635035

Player's Games

• GET /api/v0/players/:profile_id/games
• Params:
  • page (integer, optional)
  • limit (integer, optional)
  • leaderboard (string, optional, allowed: rm_solo, rm_team, rm_1v1, rm_2v2, rm_3v3, rm_4v4, qm_1v1, qm_2v2, qm_3v3, qm_4v4)
  • opponent_profile_id (integer, optional)
  • since (integer | datetime string, optional)
  • include_alts (boolean, optional, whether to consider games from accounts linked on the aoe4world site)
  • api_key (string, optional, api key for private games)
• Examples:
  • https://aoe4world.com/api/v0/players/4635035/games
  • https://aoe4world.com/api/v0/players/4635035/games?page=2
  • https://aoe4world.com/api/v0/players/4635035/games?limit=5
  • https://aoe4world.com/api/v0/players/4635035/games?opponent_profile_id=1270139
  • https://aoe4world.com/api/v0/players/4635035/games?leaderboard=rm_solo
  • https://aoe4world.com/api/v0/players/4635035/games?since=2022-04-19T08:36:35.000Z
  • https://aoe4world.com/api/v0/players/4635035/games?since=1650357395
  • https://aoe4world.com/api/v0/players/4635035/games?since=2022/04/19
• Note:
  • The leaderboard parameter accepts leaderboards (rm_solo, rm_team, qm_* etc) and game kinds (rm_1v1, rm_2v2, etc).

Player's Game

• GET /api/v0/players/:profile_id/games/:game_id
• Params:
  • include_alts (boolean, optional, whether to consider games from accounts linked on the aoe4world site)
  • api_key (string, optional, api key for private games)
• Examples:
  • https://aoe4world.com/api/v0/players/6943917/games/123893928

Player's Last Game With Players' Stats

• GET /api/v0/players/:profile_id/games/last
• Params:
  • include_alts (boolean, optional, whether to consider games from accounts linked on the aoe4world site)
  • include_stats (boolean, optional)
• Examples:
  • https://aoe4world.com/api/v0/players/6943917/games/last
  • https://aoe4world.com/api/v0/players/6943917/games/last?include_stats=true
• Note:
  • This endpoint has good caching server side, this is a good way to check if the individual player has a new game and is far more efficient than /api/v0/players/:profile_id/games

Search Players

• GET /api/v0/players/search
• Params:
  • query (required, length >= 3)
  • page (integer, optional)
• Examples:
  • https://aoe4world.com/api/v0/players/search?query=barbecue
  • https://aoe4world.com/api/v0/players/search?query=bar&page=2
  • https://aoe4world.com/api/v0/players/search?query=beasty&exact=true

Autocomplete Players

• GET /api/v0/players/autocomplete
• Params:
  • leaderboard (required, allowed: rm_solo, rm_team, qm_1v1, qm_2v2, qm_3v3, qm_4v4)
  • query (required, length >= 3)
  • limit (integer, optional, default: 10)
• Examples:
  • https://aoe4world.com/api/v0/players/autocomplete?leaderboard=qm_1v1&query=barbecue
• Note:
  • This api used to accept rm_1v1 as leaderboard, this temporarily redirects to rm_solo, please update your app accordingly.

---

Leaderboards

Leaderboard

• GET https://aoe4world.com/api/v0/leaderboards/:leaderboard
• Params:
  • page (integer, optional)
  • query (string, optional)
  • country (string, optional, allowed: de, us, cn, fr etc)
  • profile_id (alias profile_ids) (integer, comma separated up to 50 ids, optional)
  • time (integer | datetime string, optional)
• Examples:
  • https://aoe4world.com/api/v0/leaderboards/rm_solo
  • https://aoe4world.com/api/v0/leaderboards/qm_1v1
  • https://aoe4world.com/api/v0/leaderboards/qm_2v2
  • https://aoe4world.com/api/v0/leaderboards/qm_3v3
  • https://aoe4world.com/api/v0/leaderboards/qm_4v4
  • https://aoe4world.com/api/v0/leaderboards/rm_solo?query=barbecue
  • https://aoe4world.com/api/v0/leaderboards/rm_solo?profile_id=6943917
  • https://aoe4world.com/api/v0/leaderboards/rm_solo?profile_id=6943917,1270139
  • https://aoe4world.com/api/v0/leaderboards/rm_solo?profile_id=6943917,1270139&time=2022-04-19T08:36:35.000Z
• Note:
  • This api used to accept rm_1v1 as leaderboard, this temporarily redirects to rm_solo, please update your app accordingly.
  • The time parameter can be used to show the rating, rank_level, max_rating, last_game_at at the specified time.

---

Games

Games

• GET https://aoe4world.com/api/v0/games
• Params:
  • page (integer, optional, max: 20)
  • per_page (string, optional, default: 50)
  • profile_ids (integer, comma separated up to 50 ids, optional)
  • leaderboard (string, optional, allowed: rm_1v1, qm_1v1, qm_2v2, qm_3v3, qm_4v4, rm_1v1_console, qm_1v1_console, qm_2v2_console, qm_3v3_console, qm_4v4_console)
  • since (integer | datetime string, optional)
  • updated_since (integer | datetime string, optional)
  • order (string, optional, default: started_at, allowed: started_at, updated_at)
• Important:
  • PLEASE use order=started_at + since=, or order=updated_at + updated_since=.
  • If using order=started_at, update since to be no more than a reasonable amount of time in the past (say 2 hours). There's no need to fetch 20 pages repeatedly.
  • If using order=updated_at, update updated_since to your last fetch minus a minute or so.
• Examples:
  • https://aoe4world.com/api/v0/games
  • https://aoe4world.com/api/v0/games?profile_ids=6943917,1270139
  • https://aoe4world.com/api/v0/games?since=2022-04-19T08:36:35.000Z
  • https://aoe4world.com/api/v0/games?leaderboard=rm_1v1
  • https://aoe4world.com/api/v0/games?order=updated_at
• Note:
  • This api actually uses game kind as leaderboard parameter type instead of actual leaderboards and thus doesn't support rm_solo nor rm_team. This may change later.

---

Esports

Leaderboards

• GET https://aoe4world.com/api/v0/esports/leaderboards/:leaderboard
• Params:
  • page (integer, optional)
  • query (string, optional)
  • country (string, optional, allowed: de, us, cn, fr etc)
  • show_inactive (boolean, optional, allowed: true, false, also shows inactive players)
  • profile_id (alias profile_ids) (integer, comma separated up to 50 ids, optional)
• Examples:
  • https://aoe4world.com/api/v0/esports/leaderboards/1?show_inactive=true
  • https://aoe4world.com/api/v0/esports/leaderboards/1?query=marinelord
  • https://aoe4world.com/api/v0/esports/leaderboards/1?profile_id=6943917
  • https://aoe4world.com/api/v0/esports/leaderboards/1?profile_id=6943917,1270139
• Note:
  • Currently only leaderboards '1' exists, this is the official Tournament Elo leaderboard and sourced from https://docs.google.com/spreadsheets/d/12CKvt3uO1NWBL3DsBN0adcynPUcuOIpCkobvgtymJq8/edit?gid=1327598362#gid=1327598362. Other leaderboards may be added for specific events, leagues, or tournaments.
  • country isn't known for every player on the leaderboard, the list of 'official' tournament players is maintained manually
  • liquipedia_name refers to how the player is commonly refered to on Liquipedia (https://liquipedia.net/ageofempires) and is also maintained manually, and the liquipedia page may or may not exist, and has to be manually updated if someone changes their name.
  • is_active Whether the player has been active recently according to the leaderboard
  • active_rank What the player's rank would be if they were active (inactive players have can same rank as active ones based on their last known rating)
  • Unlike the non-esports leaderboards, various fields such as name, country are not based on the player's main profile, and instead are based on publicly known information.

Stats

Solo Ranked

• Civilizations
  • GET https://aoe4world.com/api/v0/stats/rm_solo/civilizations
  • Params:
    • patch (integer, optional, default: 10257, allowed: any, 9369, 10257, ..., see ui for list)
    • rank_level (string, optional, allowed: bronze, silver, gold, platinum, diamond, conqueror, ≤silver, ≥gold, ≥platinum, ≥diamond, ≥conqueror, ≥conqueror_4)
    • rating (string, optional, allowed: <499, 500-699, 700-999, 1000-1199, 1200-1399, <699, >700, >1000, >1200, >1400, >1700)
  • Examples:
    • https://aoe4world.com/api/v0/stats/rm_solo/civilizations
    • https://aoe4world.com/api/v0/stats/rm_solo/civilizations?patch=10257
    • https://aoe4world.com/api/v0/stats/rm_solo/civilizations?patch=10257&rating=>1200
• Matchups
  • GET https://aoe4world.com/api/v0/stats/rm_solo/matchups
  • Params:
    • patch (integer, optional, default: 10257, allowed: any, 9369, 10257, ..., see ui for list)
    • rank_level (string, optional, allowed: bronze, silver, gold, platinum, diamond, conqueror, ≤silver, ≥gold, ≥platinum, ≥diamond, ≥conqueror, ≥conqueror_4)
    • rating (string, optional, allowed: <499, 500-699, 700-999, 1000-1199, 1200-1399, <699, >700, >1000, >1200, >1400, >1700)
  • Examples:
    • https://aoe4world.com/api/v0/stats/rm_solo/matchups
    • https://aoe4world.com/api/v0/stats/rm_solo/matchups?patch=10257
    • https://aoe4world.com/api/v0/stats/rm_solo/matchups?patch=10257&rating=>1200
• Maps
  • GET https://aoe4world.com/api/v0/stats/rm_solo/maps
  • Params:
    • patch (integer, optional, default: 10257, allowed: any, 9369, 10257, ..., see ui for list)
    • rank_level (string, optional, allowed: bronze, silver, gold, platinum, diamond, conqueror, ≤silver, ≥gold, ≥platinum, ≥diamond, ≥conqueror, ≥conqueror_4)
    • rating (string, optional, allowed: <499, 500-699, 700-999, 1000-1199, 1200-1399, <699, >700, >1000, >1200, >1400, >1700)
    • include_civs (boolean, optional, allowed: true, includes civ stats in the results, note that this is quite expensive, only use this if you need civ stats for each map)
  • GET https://aoe4world.com/api/v0/stats/rm_solo/maps/:map_id (Get civ stats for specific map)
  • Params:
    • patch, rank_level and rating as above
  • Examples:
    • https://aoe4world.com/api/v0/stats/rm_solo/maps
    • https://aoe4world.com/api/v0/stats/rm_solo/maps?patch=10257
    • https://aoe4world.com/api/v0/stats/rm_solo/maps?patch=10257&rating=>1200
    • https://aoe4world.com/api/v0/stats/rm_solo/maps/163361

Quick Match 1v1

• Civilizations
  • GET https://aoe4world.com/api/v0/stats/qm_1v1/civilizations
  • Params:
    • patch (integer, optional, default: 10257, allowed: any, 9369, 10257, ..., see ui for list)
    • rating (string, optional, allowed: <899, 900-999, 1000-1099, 1100-1199, 1200-1299, 1300-1399, >1100, >1200, >1300, >1400, >1500, >1600)
  • Examples:
    • https://aoe4world.com/api/v0/stats/qm_1v1/civilizations
    • https://aoe4world.com/api/v0/stats/qm_1v1/civilizations?patch=10257
    • https://aoe4world.com/api/v0/stats/qm_1v1/civilizations?patch=10257&rating=>1200
• Matchups
  • GET https://aoe4world.com/api/v0/stats/qm_1v1/matchups
  • Params:
    • patch (integer, optional, default: 10257, allowed: any, 9369, 10257, ..., see ui for list)
    • rating (string, optional, allowed: <899, 900-999, 1000-1099, 1100-1199, 1200-1299, 1300-1399, >1100, >1200, >1300, >1400, >1500, >1600)
  • Examples:
    • https://aoe4world.com/api/v0/stats/qm_1v1/matchups
    • https://aoe4world.com/api/v0/stats/qm_1v1/matchups?patch=10257
    • https://aoe4world.com/api/v0/stats/qm_1v1/matchups?patch=10257&rating=>1200
• Maps
  • GET https://aoe4world.com/api/v0/stats/qm_1v1/maps
  • Params:
    • patch (integer, optional, default: 10257, allowed: any, 9369, 10257, ..., see ui for list)
    • rating (string, optional, allowed: <899, 900-999, 1000-1099, 1100-1199, 1200-1299, 1300-1399, >1100, >1200, >1300, >1400, >1500, >1600)
    • include_civs (boolean, optional, allowed: true, includes civ stats in the results, note that this is quite expensive, only use this if you need civ stats for each map)
  • GET https://aoe4world.com/api/v0/stats/qm_1v1/maps/:map_id (Get civ stats for specific map)
  • Params:
    • patch and rating as above
  • Examples:
    • https://aoe4world.com/api/v0/stats/qm_1v1/maps
    • https://aoe4world.com/api/v0/stats/qm_1v1/maps?patch=10257
    • https://aoe4world.com/api/v0/stats/qm_1v1/maps?patch=10257&rating=>1200
    • https://aoe4world.com/api/v0/stats/qm_1v1/maps/163361

Team Ranked / Quicm Match 2v2/3v3/4v4

• Civilizations
  • GET https://aoe4world.com/api/v0/stats/rm_2v2/civilizations
  • Params:
    • patch (integer, optional, default: 10257, allowed: any, 9369, 10257)
    • RM-only rank_level (string, optional, allowed: bronze, silver, gold, platinum, diamond, conqueror, ≤silver, ≥gold, ≥platinum, ≥diamond, ≥conqueror, ≥conqueror_4)
    • RM-only rating (string, optional, allowed: <499, 500-699, 700-999, 1000-1199, 1200-1399, <699, >700, >1000, >1200, >1400, >1700)
    • QM-only rating (string, optional, allowed: <899, 900-999, 1000-1099, 1100-1199, 1200-1299, 1300-1399, >1100, >1200, >1300, >1400, >1500, >1600)
  • Examples:
    • https://aoe4world.com/api/v0/stats/rm_2v2/civilizations
    • https://aoe4world.com/api/v0/stats/qm_2v2/civilizations?patch=10257
    • https://aoe4world.com/api/v0/stats/qm_2v2/civilizations?patch=10257&rating=>1200
• Teams [ONLY 2v2]
  • GET https://aoe4world.com/api/v0/stats/qm_2v2/teams
  • Params:
    • patch (integer, optional, default: 10257, allowed: any, 9369, 10257)
    • rating (string, optional, allowed: <899, 900-999, 1000-1099, 1100-1199, 1200-1299, 1300-1399, >1100, >1200, >1300, >1400, >1500, >1600)
  • Examples:
    • https://aoe4world.com/api/v0/stats/qm_2v2/teams
    • https://aoe4world.com/api/v0/stats/qm_2v2/teams?patch=10257
    • https://aoe4world.com/api/v0/stats/qm_2v2/teams?patch=10257&rating=>1200
• Maps
  • GET https://aoe4world.com/api/v0/stats/rm_solo/maps
  • Params:
    • patch (integer, optional, default: 10257, allowed: any, 9369, 10257, ..., see ui for list)
    • RM-only rank_level (string, optional, allowed: bronze, silver, gold, platinum, diamond, conqueror, ≤silver, ≥gold, ≥platinum, ≥diamond, ≥conqueror, ≥conqueror_4)
    • RM-only rating (string, optional, allowed: <499, 500-699, 700-999, 1000-1199, 1200-1399, <699, >700, >1000, >1200, >1400, >1700)
    • QM-only rating (string, optional, allowed: <899, 900-999, 1000-1099, 1100-1199, 1200-1299, 1300-1399, >1100, >1200, >1300, >1400, >1500, >1600)
    • include_civs (boolean, optional, allowed: true, includes civ stats in the results, note that this is quite expensive, only use this if you need civ stats for each map)
  • GET https://aoe4world.com/api/v0/stats/rm_2v2/maps/:map_id (Get civ stats for specific map)
  • Params:
    • patch, rank_level and rating as above
  • Examples:
    • https://aoe4world.com/api/v0/stats/rm_2v2/maps
    • https://aoe4world.com/api/v0/stats/rm_2v2/maps?patch=10257
    • https://aoe4world.com/api/v0/stats/rm_2v2/maps?patch=10257&rating=>1200
    • https://aoe4world.com/api/v0/stats/rm_2v2/maps/163361

Quick Match 2v2

• Civilizations
  • GET https://aoe4world.com/api/v0/stats/qm_2v2/civilizations
  • Params:
    • patch (integer, optional, default: 10257, allowed: any, 9369, 10257)
    • rating (string, optional, allowed: <899, 900-999, 1000-1099, 1100-1199, 1200-1299, 1300-1399, >1100, >1200, >1300, >1400, >1500, >1600)
  • Examples:
    • https://aoe4world.com/api/v0/stats/qm_2v2/civilizations
    • https://aoe4world.com/api/v0/stats/qm_2v2/civilizations?patch=10257
    • https://aoe4world.com/api/v0/stats/qm_2v2/civilizations?patch=10257&rating=>1200
• Teams
  • GET https://aoe4world.com/api/v0/stats/qm_2v2/teams
  • Params:
    • patch (integer, optional, default: 10257, allowed: any, 9369, 10257)
    • rating (string, optional, allowed: <899, 900-999, 1000-1099, 1100-1199, 1200-1299, 1300-1399, >1100, >1200, >1300, >1400, >1500, >1600)
  • Examples:
    • https://aoe4world.com/api/v0/stats/qm_2v2/teams
    • https://aoe4world.com/api/v0/stats/qm_2v2/teams?patch=10257
    • https://aoe4world.com/api/v0/stats/qm_2v2/teams?patch=10257&rating=>1200

Quick Match 3v3

• Civilizations
  • GET https://aoe4world.com/api/v0/stats/qm_3v3/civilizations
  • Params:
    • patch (integer, optional, default: 10257, allowed: any, 9369, 10257)
    • rating (string, optional, allowed: <899, 900-999, 1000-1099, 1100-1199, 1200-1299, 1300-1399, >1100, >1200, >1300, >1400, >1500, >1600)
  • Examples:
    • https://aoe4world.com/api/v0/stats/qm_3v3/civilizations
    • https://aoe4world.com/api/v0/stats/qm_3v3/civilizations?patch=10257
    • https://aoe4world.com/api/v0/stats/qm_3v3/civilizations?patch=10257&rating=>1200
• Teams
  • GET https://aoe4world.com/api/v0/stats/qm_3v3/teams
  • Params:
    • patch (integer, optional, default: 10257, allowed: any, 9369, 10257)
    • rating (string, optional, allowed: <899, 900-999, 1000-1099, 1100-1199, 1200-1299, 1300-1399, >1100, >1200, >1300, >1400, >1500, >1600)
  • Examples:
    • https://aoe4world.com/api/v0/stats/qm_3v3/teams
    • https://aoe4world.com/api/v0/stats/qm_3v3/teams?patch=10257
    • https://aoe4world.com/api/v0/stats/qm_3v3/teams?patch=10257&rating=>1200

Quick Match 4v4

• Civilizations
  • GET https://aoe4world.com/api/v0/stats/qm_4v4/civilizations
  • Params:
    • patch (integer, optional, default: 10257, allowed: any, 9369, 10257)
    • rating (string, optional, allowed: <899, 900-999, 1000-1099, 1100-1199, 1200-1299, 1300-1399, >1100, >1200, >1300, >1400, >1500, >1600)
  • Examples:
    • https://aoe4world.com/api/v0/stats/qm_4v4/civilizations
    • https://aoe4world.com/api/v0/stats/qm_4v4/civilizations?patch=10257
    • https://aoe4world.com/api/v0/stats/qm_4v4/civilizations?patch=10257&rating=>1200