GearN Server | Rest Api references | Master Player | Get Statistics Leaderboard Around Player

Overview

Retrieve leaderboard data based on statisticsleaderboardar.

Client

Require permission rules masterPlayer.getStatisticsLeaderboardAroundPlayer.selfEnable. See PermissionRules

HTTP

POST /api/rJson/masterPlayer/client/getStatisticsLeaderboardAroundPlayer

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
userId	string		The unique identifier of the player. (10 characters)
key	string	true	The key associated with a custom player data entry. (2 - 32 characters)
infoRequestParam	InfoRequestParam	true	Flags and filters used to control the information included in the response. 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)

Server

Require permission rules masterPlayer.getStatisticsLeaderboardAroundPlayer.serverSelfEnable. See PermissionRules

HTTP

POST /api/rJson/masterPlayer/server/getStatisticsLeaderboardAroundPlayer

Request Headers

Name	Type	Required	Description
Secret-Key	string	true	The SecretKey in SecretInfo with role must is Server.
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
userId	string	true	The unique identifier of the player. (10 characters)
key	string	true	The key associated with a custom player data entry. (2 - 32 characters)
infoRequestParam	InfoRequestParam	true	Flags and filters used to control the information included in the response. 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)

Admin

Require permission rules masterPlayer.getStatisticsLeaderboardAroundPlayer.adminSelfEnable. See PermissionRules

HTTP

POST /api/rJson/masterPlayer/admin/getStatisticsLeaderboardAroundPlayer

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
userId	string	true	The unique identifier of the player. (10 characters)
key	string	true	The key associated with a custom player data entry. (2 - 32 characters)
infoRequestParam	InfoRequestParam	true	Flags and filters used to control the information included in the response. 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)

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	MasterPlayerLeaderboardResponseData[]	true	Timestamp when the event occurred. See MasterPlayerLeaderboardResponseData
tsCreate	number		Timestamp when the event occurred.

InfoRequestParam

Parameter object used to control behavior or filters in API calls.

Code	Type	Description
external	boolean	Indicates whether the player is external to the current environment. (Default: false)
segments	boolean	Timestamp when the event occurred. (Default: false)
customDatas	boolean	Custom key-value data defined by the game or system. (Default: false)
displayName	boolean	The public-facing name of the player. (Default: false)
avatar	boolean	URL or identifier of the player's avatar image. (Default: false)
tsCreate	boolean	Timestamp when the event occurred. (Default: false)
tags	boolean	Tag label used to group or filter the player. (Default: false)
playerBan	boolean	Information about whether the player is currently banned. (Default: false)
playerCurrencies	boolean	List of all virtual currencies and their balances. (Default: false)
playerStatistics	boolean	Name or value of the player's statistic. (Default: false)
playerDatas	boolean	Key-value metadata stored in the player's profile. (Default: false)
ipAddressCreate	boolean	IP address from which the player first registered. (Default: false)
countryCode	boolean	Country associated with the player's IP or settings. (Default: false)
email	boolean	The email address associated with the player's account. (Default: false)
tsLastLogin	boolean	Timestamp when the event occurred. (Default: false)
pushNotifications	boolean	PushNotifications used in InfoRequestParam. (Default: false)
playerDataKeys	string[]	The key name in a key-value data pair.
playerCurrencyKeys	string[]	The key name in a key-value data pair.
playerStatisticsKeys	string[]	The key name in a key-value data pair.
customDataKeys	string[]	The key name in a key-value data pair.
tagKeys	string[]	The key name in a key-value data pair.

MasterPlayerLeaderboardResponseData

Structured data returned by the corresponding API operation.

Code	Type	Required	Description
position	number	true	Position used in MasterPlayerLeaderboardResponseData.
backupValue	number		The value assigned to a data key or statistic.
userId	string	true	Unique identifier of the player.
infoResponseParameters	InfoResponseParameters	true	InfoResponseParameters used in MasterPlayerLeaderboardResponseData. See InfoResponseParameters

InfoResponseParameters

Parameter object used to control behavior or filters in API calls.

Code	Type	Description
external	ExternalItem	Indicates whether the player is external to the current environment. See ExternalItem
segments	string[]	Timestamp when the event occurred.
customDatas	GenericModels.DataItem[]	Custom key-value data defined by the game or system. See GenericModels.DataItem
displayName	string	The public-facing name of the player.
avatar	GenericModels.AvatarItem	URL or identifier of the player's avatar image. See GenericModels.AvatarItem
tsCreate	number	Timestamp when the event occurred.
tags	GenericModels.TagItem[]	Tag label used to group or filter the player. See GenericModels.TagItem
playerBan	GenericModels.BanItem	Information about whether the player is currently banned. See GenericModels.BanItem
playerDatas	GenericModels.DataItem[]	Key-value metadata stored in the player's profile. See GenericModels.DataItem
playerCurrencies	GenericModels.CurrencyItem[]	List of all virtual currencies and their balances. See GenericModels.CurrencyItem
playerStatistics	GenericModels.StatisticsItem[]	Name or value of the player's statistic. See GenericModels.StatisticsItem
tsLastLogin	number	Timestamp when the event occurred.
ipAddressCreate	string	IP address from which the player first registered.
countryCode	string	Country associated with the player's IP or settings.
email	string	The email address associated with the player's account.
pushNotifications	PushNotificationItem[]	PushNotifications used in InfoResponseParameters. See PushNotificationItem

ExternalItem

Represents a single unit of data related to the player.

Code	Type	Description
device	Device	Device used in ExternalItem. See Device
account	Account	Account used in ExternalItem. See Account
custom	Custom	Custom used in ExternalItem. See Custom
apple	Apple	Apple used in ExternalItem. See Apple
google	Google	Google used in ExternalItem. See Google
facebook	Facebook	Facebook used in ExternalItem. See Facebook
genericService	GenericService[]	GenericService used in ExternalItem. See GenericService
googlePlayGameService	GooglePlayGameService	GooglePlayGameService used in ExternalItem. See GooglePlayGameService
gameCenter	GameCenter	GameCenter used in ExternalItem. See GameCenter

Device

Data structure: Device.

Code	Type	Description
customDeviceId	string	CustomDeviceId used in Device.
androidDeviceId	string	AndroidDeviceId used in Device.
iOSDeviceId	string	iOSDeviceId used in Device.
windowsPhoneDeviceId	string	WindowsPhoneDeviceId used in Device.
windowsDeviceId	string	WindowsDeviceId used in Device.
linuxDeviceId	string	LinuxDeviceId used in Device.
macOSDeviceId	string	MacOSDeviceId used in Device.
editorDeviceId	string	EditorDeviceId used in Device.

Account

Data structure: Account.

Code	Type	Required	Description
username	string		Username used in Account.

Custom

Data structure: Custom.

Code	Type	Required	Description
customId	string		CustomId used in Custom.

Apple

Data structure: Apple.

Code	Type	Required	Description
appleId	string	true	AppleId used in Apple.
email	string	true	The email address associated with the player's account.

Google

Data structure: Google.

Code	Type	Required	Description
googleId	string	true	GoogleId used in Google.
displayName	string	true	The public-facing name of the player.
email	string	true	The email address associated with the player's account.

Facebook

Data structure: Facebook.

Code	Type	Required	Description
facebookId	string	true	FacebookId used in Facebook.
displayName	string	true	The public-facing name of the player.
email	string	true	The email address associated with the player's account.

GenericService

Data structure: GenericService.

Code	Type	Required	Description
serviceName	string	true	ServiceName used in GenericService.
serviceId	string	true	ServiceId used in GenericService.

GooglePlayGameService

Data structure: GooglePlayGameService.

Code	Type	Required	Description
playerId	string	true	PlayerId used in GooglePlayGameService.
displayName	string	true	The public-facing name of the player.
email	string	true	The email address associated with the player's account.

GameCenter

Data structure: GameCenter.

Code	Type	Required	Description
playerId	string	true	PlayerId used in GameCenter.
displayName	string	true	The public-facing name of the player.
email	string	true	The email address associated with the player's account.

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.BanItem

Represents a ban state entry returned by player-auth or player-profile flows.

Code	Type	Required	Description
tsExpire	number	true	Expiration timestamp of the current ban state. -1 is never unban.
reason	string	true	Human-readable ban reason when provided by the backend.

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`.

PushNotificationItem

Represents a single unit of data related to the player.

Code	Type	Required	Description
token	string	true	Token used in PushNotificationItem.
pushId	string	true	Identifier for the registered push notification device.
platformType	number	true	PlatformType used in PushNotificationItem.

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.