GearN Server | Rest Api references | Group | Get Statistics Leaderboard Around Group

Overview

Get a leaderboard centered around the group’s rank for a specific statistic.

Client

Require permission rules group.getStatisticsLeaderboardAroundGroup.selfEnable. See PermissionRules

HTTP

POST /api/rJson/group/client/getStatisticsLeaderboardAroundGroup

Request Headers

Name	Type	Required	Description
Auth-Token	string	true	A token used to authenticate the user. It is issued after successful login from the client type authenticate (e.g., loginByAccount, loginWithCustomId, etc.) or when an admin logs in via the GearN Dashboard. This token identifies the request sender and determines their access level.
Secret-Key	string	true	The SecretKey in SecretInfo with role must is Player.
Game-Id	string		Optional if the gameId in the SecretInfo use in headers Secret-Key has assign a valid value, if not, let unique identifier of the game this request is targeting.
Content-Type	string	true	application/json

Request Body

Code	Type	Required	Description
groupId	string	true	Unique identifier of the group targeted by the request. (10 characters)
key	string	true	Key parameter. (2 - 32 characters)
infoRequestParam	InfoRequestParam	true	InfoRequestParam parameter. See InfoRequestParam
skip	number int		Skip parameter. (from 0) (Default: 0)
limit	number int		Limit parameter. (from 1 to 100) (Default: 10)
loadFromCache	boolean		LoadFromCache parameter. (Default: true)
catalogId	string		Identifier of the item catalog used for inventory operations. (2 - 32 characters)

Server

Require permission rules group.getStatisticsLeaderboardAroundGroup.serverSelfEnable. See PermissionRules

HTTP

POST /api/rJson/group/server/getStatisticsLeaderboardAroundGroup

Request Headers

Name	Type	Required	Description
Secret-Key	string	true	The SecretKey in SecretInfo with role must is Admin.
Game-Id	string		Optional if the gameId in the SecretInfo use in headers Secret-Key has assign a valid value, if not, let unique identifier of the game this request is targeting.
Content-Type	string	true	application/json

Request Body

Code	Type	Required	Description
groupId	string	true	Unique identifier of the group targeted by the request. (10 characters)
key	string	true	Key parameter. (2 - 32 characters)
infoRequestParam	InfoRequestParam	true	InfoRequestParam parameter. See InfoRequestParam
skip	number int		Skip parameter. (from 0) (Default: 0)
limit	number int		Limit parameter. (from 1 to 100) (Default: 10)
loadFromCache	boolean		LoadFromCache parameter. (Default: true)
catalogId	string		Identifier of the item catalog used for inventory operations. (2 - 32 characters)

Admin

Require permission rules group.getStatisticsLeaderboardAroundGroup.adminSelfEnable. See PermissionRules

HTTP

POST /api/rJson/group/admin/getStatisticsLeaderboardAroundGroup

Request Headers

Name	Type	Required	Description
Secret-Key	string	true	The SecretKey in SecretInfo with role must is Admin.
Game-Id	string		Optional if the gameId in the SecretInfo use in headers Secret-Key has assign a valid value, if not, let unique identifier of the game this request is targeting.
Content-Type	string	true	application/json

Request Body

Code	Type	Required	Description
groupId	string	true	Unique identifier of the group targeted by the request. (10 characters)
key	string	true	Key parameter. (2 - 32 characters)
infoRequestParam	InfoRequestParam	true	InfoRequestParam parameter. See InfoRequestParam
skip	number int		Skip parameter. (from 0) (Default: 0)
limit	number int		Limit parameter. (from 1 to 100) (Default: 10)
loadFromCache	boolean		LoadFromCache parameter. (Default: true)
catalogId	string		Identifier of the item catalog used for inventory operations. (2 - 32 characters)

Response Body

200 Ok

Code	Type	Required	Description
returnCode	ReturnCode	true	Additional metadata that can be attached to any request. Especially useful when working with advanced features such as EventCallbackScript. See ReturnCode
debugMessage	string		A developer-oriented message that provides additional context useful for debugging and internal logging. This field is not intended for end-users and may include stack traces, validation failures, or internal error diagnostics.
invalidRequestParameters	InvalidMember[]		Just had data when the returnCode is InvalidRequestParameters.A list of members that failed validation or could not be processed during the request. Each entry typically includes identifying information and an error reason. This is useful for partial success scenarios where some members are accepted and others are rejected. See InvalidMember
parameters	ResponseData		Just had data when the returnCode is Ok. A dynamic set of key-value pairs included in the response to provide additional context or metadata. These parameters may vary depending on the operation and typically contain optional fields such as timestamps, identifiers, or computed values relevant to the result. See ResponseData

ReturnCode

Name	Code	Description
SecretInvalid	-10	The selected secret key is missing, wrong, or does not match the current route/game context.
MaxSizeRequestReject	-9	The serialized request payload exceeded the maximum size accepted by the backend.
MaxRequestReject	-8	The backend rejected the request because the current caller exceeded a request-rate limit.
MaxCCUReject	-7	The backend rejected the request because the current concurrent-user/session limit was exceeded.
OperationNotAuthorized	-6	The target operation exists, but the caller is not authorized for the selected role or target resource.
InvalidRequestParameters	-5	The request shape or one or more request-member values are invalid. When available, inspect `invalidMembers` for field-level details.
OperationInvalid	-4	The requested operation code is unknown or is not valid for the selected request type/role.
InternalServerError	-3	The backend hit an unhandled internal failure before producing a valid business response.
OperationNotAllow	-2	The operation is known and the secret key is valid, but the permission rules attached to the current secret key do not allow this operation in the current target context. This usually maps to missing `selfEnable`, `otherSelfEnable`, `serverSelfEnable`, or `adminSelfEnable` permission for the resolved request.
OperationTimeout	-1	The request timed out before a response was received. This code may be synthesized by the SDK timeout layer as well as returned by the backend.
UnknownError	0	The request failed, but no more specific low-level return code was mapped.
Ok	1	The request completed successfully at protocol level and produced a response payload. Callers must still validate the business `errorCode` in that payload.

ResponseData

Code	Type	Required	Description
errorCode	ErrorCode		A string that represents the status of the operation. It indicates whether the request was successful or failed due to a specific error condition. See ErrorCode
results	GroupLeaderboardResponseData[]	true	Results field in GetStatisticsLeaderboardResponseData. See GroupLeaderboardResponseData
tsCreate	number		Include the timestamp of group creation.

InfoRequestParam

Flags to specify which optional fields should be included in the group response.

Code	Type	Description
catalogId	boolean	CatalogId field in InfoRequestParam. (Default: false)
members	boolean	Members field in InfoRequestParam. (Default: false)
removeStatus	boolean	RemoveStatus field in InfoRequestParam. (Default: false)
segments	boolean	Include group segments in the response. (Default: false)
customDatas	boolean	Include custom key-value data in the response. (Default: false)
displayName	boolean	Include the group’s display name in the response. (Default: false)
avatar	boolean	Include the group’s avatar reference or URL. (Default: false)
tsCreate	boolean	Include the timestamp of group creation. (Default: false)
tags	boolean	Include tags assigned to the group. (Default: false)
groupCurrencies	boolean	Include current virtual currency balances of the group. (Default: false)
groupStatistics	boolean	Include statistics stored on the group profile. (Default: false)
groupDatas	boolean	GroupDatas field in InfoRequestParam. (Default: false)
groupInventories	boolean	GroupInventories field in InfoRequestParam. (Default: false)
groupDataKeys	string[]	GroupDataKeys field in InfoRequestParam.
groupCurrencyKeys	string[]	GroupCurrencyKeys field in InfoRequestParam.
groupStatisticsKeys	string[]	GroupStatisticsKeys field in InfoRequestParam.
customDataKeys	string[]	CustomDataKeys field in InfoRequestParam.
tagKeys	string[]	TagKeys field in InfoRequestParam.
itemCatalogIds	string[]	ItemCatalogIds field in InfoRequestParam.

GroupLeaderboardResponseData

Entry in a leaderboard containing rank and score information for a group.

Code	Type	Required	Description
position	number	true	Position field in GroupLeaderboardResponseData.
backupValue	number		BackupValue field in GroupLeaderboardResponseData.
groupId	string	true	Unique identifier for the group.
infoResponseParameters	InfoResponseParameters	true	InfoResponseParameters field in GroupLeaderboardResponseData. See InfoResponseParameters

InfoResponseParameters

Contains optional metadata fields returned in group data responses.

Code	Type	Description
catalogId	string	CatalogId field in InfoResponseParameters.
members	GenericModels.MemberItem[]	Members field in InfoResponseParameters. See GenericModels.MemberItem
removeStatus	GenericModels.RemoveStatusItem	RemoveStatus field in InfoResponseParameters. See GenericModels.RemoveStatusItem
segments	string[]	Include group segments in the response.
customDatas	GenericModels.DataItem[]	Include custom key-value data in the response. See GenericModels.DataItem
displayName	string	Include the group’s display name in the response.
avatar	GenericModels.AvatarItem	Include the group’s avatar reference or URL. See GenericModels.AvatarItem
tsCreate	number	Include the timestamp of group creation.
tags	GenericModels.TagItem[]	Include tags assigned to the group. See GenericModels.TagItem
groupDatas	GenericModels.DataItem[]	GroupDatas field in InfoResponseParameters. See GenericModels.DataItem
groupCurrencies	GenericModels.CurrencyItem[]	Include current virtual currency balances of the group. See GenericModels.CurrencyItem
groupStatistics	GenericModels.StatisticsItem[]	Include statistics stored on the group profile. See GenericModels.StatisticsItem
groupInventories	GenericModels.InventoryItem[]	GroupInventories field in InfoResponseParameters. See GenericModels.InventoryItem

Generic.MemberItem

Represents a lightweight relation item pointing to a group member.

Code	Type	Required	Description
memberId	string	true	Member identifier of the related group member.
status	number	true	Member relation status. Map this value with the public member-status enum when available.

Generic.RemoveStatusItem

Represents soft-remove metadata for an entity.

Code	Type	Required	Description
tsRemove	number	true	Removal timestamp when the entity was soft-removed.
reason	string		Removal reason when the backend provides one.

Generic.DataItem

Represents an arbitrary key-value data entry.

Code	Type	Required	Description
key	string	true	Data entry key used to identify the payload.
value	any	true	Raw value returned by the backend. This may be a primitive, `GNHashtable`, `GNArray`, or plain object-like data.

Generic.AvatarItem

Represents a generic avatar payload.

Code	Type	Required	Description
type	number	true	Backend-defined avatar type identifier. The public SDK currently does not export a dedicated avatar enum.
value	string	true	Avatar value, typically a URL, file id, or provider-specific string.

Generic.TagItem

Represents a key-value tag entry.

Code	Type	Required	Description
key	string	true	Tag key used to identify the metadata entry.
value	string	true	Tag value associated with `key`.

Generic.CurrencyItem

Represents one currency entry.

Code	Type	Required	Description
key	string	true	Currency key such as the configured currency code or logical name.
value	number	true	Numeric balance of the currency identified by `key`.

Generic.StatisticsItem

Represents one statistics entry.

Code	Type	Required	Description
key	string	true	Statistic key such as the configured metric name.
value	number	true	Numeric value of the statistic identified by `key`.

Generic.InventoryItem

Represents a lightweight relation item pointing to an inventory item.

Code	Type	Required	Description
itemId	string	true	Inventory item identifier of the related item entity.
catalogId	string	true	Catalog identifier associated with the related inventory item.
classId	string	true	Class identifier associated with the related inventory item.

ErrorCode

Name	Code	Description
Ok	1	The business operation completed successfully.
KeyNotFound	9	The requested key does not exist in the target data set.

InvalidMember

Code	Type	Description
code	string	The parameterCode invalid.
invalidMemberType	InvalidMemberType	The invalid member type of this parameterCode. See InvalidMemberType

InvalidMemberType

Name	Code	Description
UnknownError	1	The backend rejected the member but did not map it to a more specific validation category.
DataRequired	2	The member is required but missing.
TypeInvalid	3	The member type does not match the expected runtime type.
StringNull	4	A required string member is null or empty when null is not allowed.
StringMinLength	5	A string member is shorter than the configured minimum length.
StringMaxLength	6	A string member is longer than the configured maximum length.
NumberMinValue	7	A numeric member is lower than the configured minimum value.
NumberMaxValue	8	A numeric member is higher than the configured maximum value.
NumberMustInt	9	A numeric member must be an integer but received a non-integer value.
GNHashtableNull	10	A required `GNHashtable` member is null.
GNHashtableMinLength	11	A `GNHashtable` member contains fewer entries than allowed.
GNHashtableMaxLength	12	A `GNHashtable` member contains more entries than allowed.
GNArrayNull	13	A required `GNArray` member is null.
GNArrayMinLength	14	A `GNArray` member contains fewer items than allowed.
GNArrayMaxLength	15	A `GNArray` member contains more items than allowed.