Guild Data - swgoh-utils/swgoh-comlink GitHub Wiki

1. Getting the guild data
2. Returned guild data
3. getGuilds Endpoint
4. Tips for usage

To retrieve guild data from the api you will need to use the /guild endpoint. You will need to have the guild id in order to locate and return the guild profile. There are two ways to find the guild id; grabbing the "guildId" from either the /player endpoint or finding the guild using the /getGuilds endpoint.

Once you have the guild id the request body will look like this:

{
  "payload":{
        "guildId": "jrl9Q-_CRDGdMyNjTQH1rQ",
        "includeRecentGuildActivityInfo": true
  },
  "enums": false
}

includeRecentActivityInfo
Specifies whether you want more details on member and event activity within the guild. Selecting false will return a smaller payload for those looking to just get a list of player ids for each member so they can get their rosters, while true will return the most recent activity for gear donations, daily activities contributions, raid ticket contributions, raid contribution, and territory war contributions. Only activity within the last 60 days will display for Territory Wars, Raids, and Territory Battles with Territory Battles displaying the data from the run that had the most stars earned. Member contributions will only show current value for the duration between the Guild Reset, once the Guild Reset time hits all current values will go back to 0.

The returned data will look similar to this:

{
  "member": [],
  "inviteStatus": [],
  "raidStatus": [],
  "raidResult": [],
  "territoryBattleStatus": [],
  "guildEvents": [],
  "territoryBattleResult": [],
  "territoryWarStatus": [],
  "roomAvailable": [],
  "arcadeRaidStatus": [],
  "stat": [],
  "recentRaidResult": [],
  "recentTerritoryWarResult": [],
  "profile": {},
  "inventory": null,
  "progress": null,
  "nextChallengeRefresh": ""
}

member: List of each member in the guild with brief details about them. See below for details.
inviteStatus: Currently not returned.
raidStatus: Currently not returned.
raidResult: Currently not returned.
territoryBattleStatus: Currently not returned.
guildEvents: Currently not returned.
territoryBattleResult: Currently not returned.
territoryWarStatus: Currently not returned.
roomAvailable: Currently not returned.
arcadeRaidStatus: Currently not returned.
stat: Currently not returned.
recentRaidResult: List containing information for the last attempt for each raid. See below for details.
recentTerritoryWarResult: List of the past 8 Territory Wars with details on your guild sccore, opponents guild score, and the amount of total Galactic Power from all signed up members.
profile: Object containing details about the guild. See below for details.
inventory: Currently not returned.
progress: Currently not returned.
nextChallengesRefresh: The guild reset time for Guild Activities.

NOTE: Any field marked as currently not returned means that the data within them can only be returned if the account requesting that information is within the guild. Comlink has no way of signing in to a specific account and therefore can only grab the public guild data and not any of the private guild data people can only see while in the guild.

The returned data will look similar to this:

{
  "memberContribution": [],
  "seasonStatus": [],
  "playerId": "p5dB_6irTVuIWWUoTky3qT",
  "playerName": "Kidori",
  "playerLevel": 85,
  "memberLevel": 3,
  "guildXp": 0,
  "lastActivityTime": "1674843042000",
  "squadPower": 206096,
  "guildJoinTime": "1611264476",
  "galacticPower": "4324722",
  "playerTitle": "PLAYERTITLE_SEPARATIST_COMMANDER",
  "playerPortrait": "PLAYERPORTRAIT_SMUG3",
  "lifetimeSeasonScore": "978389",
  "leagueId": "CARBONITE"
}

memberContribution: Details about the member's most recent contribution to donations, raid tickets, and guild activities and their lifetime values.
Type:
1 = Guild Activities (Guild Tokens Contributed)
2 = Raid Tickets
3 = Gear Dontations
seasonStatus: A list of the last three Grand Arena seasons that contains information about start and end times, points, league, and division.
playerId: The player's assigned GUID.
playerName: The player's in-game name.
playerLevel: The player's level.
memberLevel: The current rank of the player within the guild.
guildXp: Not currently used or returned.
lastActivityTime: The epoch time in seconds that the player last logged into the game.
squadPower: The total Galactic Power of the member's Squad Arena team.
guildJoinTime: The epoch time in seconds that the player joined the guild.
galacticPower: The total Galactic Power of all units the member has.
playerTitle: The player's selected in-game title.
playerPortrait: The player's selected in-game portrait.
lifetimeSeasonScore: The lifetime GAC score for the player. This is no longer used as the old GAC system no longer exists.
leagueId: The name of the current GAC league the member is in.

The returned data will look similar to this:

{
  "messageCriteriaKey":  []
  "raidLaunchConfig": […]
  "guildEventTracker": […]
  "id": "jrl9Q-_CRDGdMyNjTQH1rQ"
  "name": "MΔW"
  "externalMessageKey": "#1 TW guild. 40 *s & 50/…619 or Chiss#0066 MΔW-C"
  "logoBackground": ""
  "enrollmentStatus": 2
  "trophy": 0
  "memberCount": 50
  "memberMax": 50
  "level": 1
  "rank": 0
  "levelRequirement": 20
  "raidWin": 0
  "leaderboardScore": "0"
  "bannerColorId": "red_white"
  "bannerLogoId": "guild_icon_empire"
  "guildGalacticPower": "595835461"
  "chatChannelId": "guild-{jrl9Q-_CRDGdMyNjTQH1rQ}"
  "guildType": ""
  "guildGalacticPowerForRequirement": "595835461"
}

raidLaunchConfig: List of each raid with information on auto launching, join period duration, and if it is on sim.
guildEventTracker: List of Territory Battles completed within the last 60 days that includes information on number of stars obtained, end time, and the id for the Territory Battle. Only shows the details for the specific Territory Battle where the highest obtained stars were acheived for it.
id: The GUID for the guild.
name: The name of the guild.
externalMessageKey: The public guild message about the guild.
memberCount: Current number of members in the guild.
memberMax: Max number of members that can be in the guild.
levelRequirement: Required Player Level to join the guild.
guildGalacticPower: Total amount of Galactic Power for all members of the guild.

The returned data will look similar to this:

{
  "raidMember": [],
  "raidId": "rancor_challenge",
  "identifier": {},
  "duration": "80813",
  "progress": 0,
  "endTime": "1674584862",
  "outcome": 1
}

raidMember: List of all guild members and summary of their performance in the raid. Includes the player id, damage dealt (memberProgress), and rank for that raid.
raidId: The id used to identify the raid.
identifier: Identifiers used in the campaign collection to identify the raid.
duration: The amount of time in seconds it took to defeat the raid.
progress: Currently not used.
endTime: The epoch time in seconds that the raid ended at.
outcome: The result of the raid attempt where 1 = Completed, 2 = Expired, 3 = In Progress, 4 = Abandoned, 5 = Simmed and 0 = Not attempted

The difficulty of the raid is specified in the "identifier" within "campaignMissionId" where DIFF01 to DIFF06 typically represent Tier 1-6 unless there is only 1 difficulty for the raid, and HEROIC80 and HEROIC85 are both Heroic tiers.

The /getGuilds endpoint allows for searching for a guild by name or by criteria. The searches are not case sensitive and will find every guild, up to the set count limit (max 10,000), that contains the search name or meets the search criteria. The results will also not be in any specific order so most relevant results will not always be at the top. Only the profile portion of guild data is returned for each found guild in the response.

The type of filter to use must be indicated and payload properties must only include the appropriate properties for that filter. It is important to note that this endpoint utilizes the Guild Search feature within the game and is designed to return the same results you would find using it within the game. For details on the request parameters see Getting Started.

The request body for name searches should look like the following:

{
 "payload": {
   "filterType": 4,
   "count": 10,
   "name": "HothSkiPatrol"
 },
 "enums": false
}

The request body for criteria searches should look like the following:

{
 "payload": {
   "filterType": 5,
   "count": 10,
   "searchCriteria": {
     "minMemberCount": 25,
     "maxMemberCount": 45,
     "minGuildGalacticPower": 430000000,
     "maxGuildGalacticPower": 430000000,
     "recentTbParticipatedIn": ["T05D"],
     "includeInviteOnly": true
   }
 },
 "enums": false
}

1. Getting guild rosters

If you do not have the guild id you will first need to use the /player endpoint using the known allycode and grab the "guildId" from the response. Once you have the guild id you will then need to use the /guild endpoint and parse the "member" field for each members "playerId". You would then have to send each player id to the /player endpoint to grab the rest of the guild members rosters. It is a good practice to go ahead and save the first player response to the guild roster and excluding it from the list you grab from the guild endpoint so you are not calling the same profile more than once.

2. Getting daily Raid Tickets and Guild Activities

Daily member contributions such as Raid Tickets, Donations and Guild Activities will reset back to 0 every day at the Guild Reset time. In order to retrieve the counts you will need to call the /guild endpoint and grab the results as close to the Guild Reset time as possible and then store the results some where. All lifetime values update with current values which updates immediately in the game. However, Guild Activities does not update current value when the Guild Tokens are earned, instead the displayed daily amount corresponds to collecting the previous daily guild activity reward from your in-game inbox. If someone skips collecting it then they will show 0 daily Guild Tokens earned until they collect it.

First you will need to know when the Guild Reset is, this is given in Epoch Time in the "nextChallengesRefresh" field. When you are ready to get the results you will need to go through each index in "member" grabbing the entries within "memberContribution" that have a "type" = 2 for Raid Tickets and "type" = 1 for Guild Tokens earned from completing Guild Activities. You will find the amounts within the "currentValue" field.

Alternatively if you have the history of it saved you can just grab the values once a day to compare using a similar formula to (lifetimeValue - currentValue) - previousLifetime. Then, lifetimeValue - currentValue would then become the new previousLifetime for the next calculation.

3. Tracking raid participation

After grabbing the guild data from the /guild endpoint you will need to parse the "recentRaidResult" field searching the "raidId" field for the appropriate raids to track. Once you have found the raid you will need to go through each index in "raidMember" grabbing their "playerId" and "memberProgress" which indicates total damage done for all completed phases. Only ended raids that have been successfully completed will be displayed in this field so this can not be used to track live raid progress.