API | Ranking | Battle League | Legend League | Guild Battle | Grand War
The API domain is https://api.mentemori.icu/
[world_id] parameters are four digit integers of the following format: SWWW
S: Server. 1 = Japan, 2 = Korea, 3 = Asia, 4 = North America, 5 = Europe, 6 = GlobalWWW: World number. For example, W10 is 010Example: Korea W4 is 2004.
0 may be passed in for [world_id] parameters to fetch data for all worlds at once.
[wgroup_id] parameters are world group IDs. These can be found from the /wgroups endpoint.
[server] parameters are one of: jp1, jp2, jp3, jp4, jp5, kr1, kr2, ap1, ap2, us1, eu1, gl1, gl2.
All endpoints return a payload of the following format:
{
"status": 200,
"timestamp": 1600000000,
"data": ...
}
status HTTP status codetimestamp Timestamp of data returned (not request time)data Endpoint-dependent payload/worldsList of worlds with data available, as well as what data is available.
"data": [
{
"world_id": 1001,
"ranking": true,
"temple": false,
"localgvg": true
},
...
]
world_id: Four-digit world IDranking: Whether there is up to date data for the player_ranking, guild_ranking, and arena endpointstemple: Whether there is up to date data for the temple endpointlocalgvg: Whether there is up to date data for the localgvg endpoint/wgroupsList of world groups, as well as what data is available.
"data": [
{
"group_id": 1,
"worlds": [1001, 1002, 1003, 1004],
"legendleague": true,
"globalgvg": true
},
...
]
group_id: World group IDworlds: List of world IDs for worlds in the grouplegendleague: Whether there is up to date data for the legend endpointglobalgvg: Whether there is up to date data for the globalgvg endpoints/[world_id]/player_ranking/latestPlayer rankings for a world. Includes BP, Player Rank, Story, and Tower rankings.
"data": {
"world_id": 1001,
"rankings": {
"bp": [
{ "id": 123456789001, "name": "Player", "bp": 100000000 },
...
],
"rank": [
{ "id": 123456789001, "name": "Player", "rank": 400 },
...
],
"quest": [
{ "id": 123456789001, "name": "Player", "quest_id": 700 },
...
],
"tower": [
{ "id": 123456789001, "name": "Player", "tower_id": 800 },
...
],
"tower_blue": [
{ "id": 123456789001, "name": "Player", "tower_id": 800 },
...
]
"tower_red": [
{ "id": 123456789001, "name": "Player", "tower_id": 800 },
...
]
"tower_green": [
{ "id": 123456789001, "name": "Player", "tower_id": 800 },
...
]
"tower_yellow": [
{ "id": 123456789001, "name": "Player", "tower_id": 800 },
...
]
},
"player_info": {
"123456789001": {
"id": 123456789001,
"name": "Player",
"bp": 1000000000",
"rank": 400,
"quest_id": 700,
"tower_id": 800,
"icon_id": 21,
"guild_id": 987654321001,
"guild_name": "Guild",
"guild_join_time": 1600000000000,
"guild_position": 1,
"prev_legend_league_class": 5
},
...
}
}
world_id: Four-digit world IDrankings: ranking data
bp: Ranking data by BP in descending orderrank: Ranking data by Player Rank in descending orderquest: Ranking data by Story stage in descending order
quest_id: Story stage. 1-12 is 12, 2-1 is 13, etc.tower: Ranking data by Tower floor in descending ordertower_blue: Ranking data by Tower of Azure floor in descending ordertower_red: Ranking data by Tower of Crimson floor in descending ordertower_green: Ranking data by Tower of Emerald floor in descending ordertower_yellow: Ranking data by Tower of Amber floor in descending orderWorlds for which elemental tower rankings have not been unlocked will return an empty array for those fields.
player_info: additional player info for players that appeared in rankings. Dictionary with player id as key.
id: Player ID. Last three digits are world number.name: Player Namebp: BPrank: Player Rankquest_id: Quest ID. 1-12 is 12, 2-1 is 13, etc.tower_id: Tower flooricon_id: Character ID of player iconguild_id: Guild IDguild_name: Guild Nameguild_join_time: Time of joining guild (unix time in milliseconds)guild_position: Position in guild. 1 = Master, 2 = Chief, 3 = Memberprev_legend_league_class: Previous Legend League Class. 1 = Chevalier, 2 = Paladin, 3 = Grand Cross, 4 = Royal Rank, 5 = Legend Rank, 6 = World Ruler./[world_id]/guild_ranking/latestGuild rankings for a world. Includes BP, Guild Level, and Guild Stock rankings.
"data": {
"world_id": 1001,
"rankings": {
"bp": [
{ "id": 987654321001, "name": "Guild", "bp": 100000000 },
...
],
"level": [
{ "id": 987654321001, "name": "Guild", "level": 20 },
...
],
"stock": [
{ "id": 987654321001, "name": "Guild", "stock": 14400 },
...
]
},
"guild_info": {
"987654321001": {
"id": 987654321001,
"name": "Guild",
"bp": 10000000000",
"level": 20,
"stock": 14400,
"exp": 1405123,
"num_members": 34,
"leader_id": 123456789001,
"leader_name": "Player",
"policy": 1,
"description": "Just another guild",
"free_join": false,
"bp_requirement": 999999999
},
...
}
}
world_id: Four-digit world IDrankings: ranking data
bp: Ranking data by BP in descending orderlevel: Ranking data by Guild Level in descending orderstock: Ranking data by Guild Stock in descending orderguild_info: additional guild info for guilds that appeared in rankings. Dictionary with guild id as key.
id: Guild ID. Last three digits are world number.name: Guild Namebp: Guild BPlevel: Guild Levelstock: Guild Stockexp: Guild Experiencenum_members: Number of membersleader_id: Guild Master's Player IDleader_name: Guild Master's Namepolicy: Guild Activity Policy. 0 = Unspecified, 1 = Play Casually, 2 = Play to Get Stronger, 3 = Play for Supremacy, 4 = Play to Hang Out, 5 = Beginners Welcomedescription: Guild Descriptionfree_join: Whether a player can join without approvalbp_requirement: BP Requirement/[world_id]/temple/latestTemple data for a world.
"data": {
"world_id": 1001,
"quest_ids": [208001, 308003, 408006, 408009]
}
world_id: Four-digit world IDquest_ids: Array of IDs for the current raids in temple/[world_id]/arena/latestBattle League data for a world.
/[world_id]/localgvg/latestGuild Battle data for a world.
"data": {
"world_id": 1001,
"castles": [
{
"CastleId": 1,
"GuildId": 123456789001,
"AttackerGuildId": 0,
"AttackPartyCount": 0,
"DefensePartyCount": 120,
"GvgCastleState": 0,
"UtcFallenTimeStamp": 0
},
...
],
"guilds": {
"123456789001": "Guild",
...
}
}
world_id: Four-digit world IDcastles: castle data
CastleId: Castle IDGuildId: ID of guild that held this castle at the start of the dayAttackerGuildId: ID of guild that declared on this castle todayAttackPartyCount: Number of parties attacking this castleDefenseGuildId: Number of parties defending this castleGvgCastleState: State of battle at this castle. 0 = none, 1 = declared/in battle, 2 = fallen, 3 = counterattack, 4 = counterattack successfulUtcFallenTimeStamp: milliseconds since 1 January 1970, 00:00:00 server timeguilds: names of guilds that may appear in guild war today. Mapping from guild id to guild name.
/wg/[wgroup_id]/legend/latestLegend League data for a world group.
/wg/[wgroup_id]/globalgvg/[class]/[block]/latestGrand War data for a block. [class] should be one of 1 = Elite Class, 2 = Expert Class, or 3 = Grand Master. [block] should be one of 0 = A, 1 = B, 2 = C, 3 = D.
"data": {
"matching_number": 1102,
"castles": [
{
"CastleId": 1,
"GuildId": 123456789001,
"AttackerGuildId": 0,
"AttackPartyCount": 0,
"DefensePartyCount": 120,
"GvgCastleState": 0,
"UtcFallenTimeStamp": 0
},
...
],
"guilds": {
"123456789001": "Guild",
...
}
}
matching_number: Matching Number for this block. General format is GGC0B where GG is the world group ID, C is the class, and B is the block.castles: castle data
CastleId: Castle IDGuildId: ID of guild that held this castle at the start of the dayAttackerGuildId: ID of guild that declared on this castle todayAttackPartyCount: Number of parties attacking this castleDefenseGuildId: Number of parties defending this castleGvgCastleState: State of battle at this castle. 0 = none, 1 = declared/in battle, 2 = fallen, 3 = counterattack, 4 = counterattack successfulUtcFallenTimeStamp: milliseconds since 1 January 1970, 00:00:00 server timeguilds: names of guilds that may appear in guild war today. Mapping from guild id to guild name.
/[server]/destiny_log/latestInvocation of Chance logs for a server.
"data": [
{
"Name": "MaintenanceMori",
"UserItem": {
"ItemCount": 1,
"ItemId": 41,
"ItemType": 6,
}
},
...
]
Name: Player nameUserItem: Information for the item rolled
ItemCount: Number of copies. This is either 1 (character) or 30000 (diamonds).ItemId: Item ID. This is either the character ID or 1 (diamonds).ItemType: Item type. This is either 6 (character) or 1 (diamonds)./[server]/stars_guidance_log/latestInvocation of The Stars' Guidance logs for a server.
"data": [
{
"Name": "MaintenanceMori",
"UserItem": {
"ItemCount": 1,
"ItemId": 41,
"ItemType": 6,
}
},
...
]
Name: Player nameUserItem: Information for the item rolled
ItemCount: Number of copies. This is either 1 (character) or 30000 (diamonds).ItemId: Item ID. This is either the character ID or 1 (diamonds).ItemType: Item type. This is either 6 (character) or 1 (diamonds)./gvgRealtime Guild Battle and Grand War data.
This endpoint uses WebSockets, obeying the protocol described below. All frames are binary frames, and all integers follow little-endian encoding.
A stream ID is a 4-byte integer containing:
This stream ID should be encoded in little-endian. For example, the stream ID 0x17810015 corresponds to Guild Battle Castle 21 on World 6017. This is sent/received over the network as the 4-byte sequence 0x15 0x00 0x81 0x17.
After connecting to the endpoint, clients should send one or more stream IDs indicating which castles it wishes to listen for updates on. Using Castle ID = 0 here will subscribe the client to all changes in the corresponding instance of Guild Battle/Grand War.
A client may send the stream ID of a stream it is currently listening on to unsubscribe itself from that stream.
For Grand War, the World ID used when subscribing/unsubscribing should be 0. Guild Information Messages will set the world ID corresponding to the world of the guild.
The server will send two types of messages: guild information messages and castle status messages. These messages can be distinguished by the Castle ID field of the included stream IDs -- guild information messages always have Castle ID = 0.
Note that all guild IDs sent contain only the first 9 digits of the full guild ID. The last 3 digits are always equal to the last three digits of the world ID.
A single WebSocket message may contain one or more of the two types of messages.
Structures:
struct StreamId {
uint32_t castle_id: 5;
uint32_t block: 3;
uint32_t group: 8;
uint32_t gvg_class: 3;
uint32_t world_id: 13;
};
struct GuildInformation {
struct StreamId stream_id;
uint32_t guild_id;
uint8_t guild_name_len;
char guild_name[];
};
struct CastleStatus {
struct StreamId stream_id;
uint32_t guild_id;
uint32_t attacker_guild_id;
uint32_t utc_fallen_timestamp;
uint16_t defense_count;
uint16_t attack_count;
uint8_t state;
uint8_t reserved[3];
};