Leaderboards - Get Leaderboard Around Entity
Get the leaderboard around a specific entity.
POST https://titleId.playfabapi.com/Leaderboard/GetLeaderboardAroundEntityRequest Header
| Name | Required | Type | Description |
|---|---|---|---|
| X-EntityToken | True |
string |
This API requires an Entity Session Token, available from the Entity GetEntityToken method. |
Request Body
| Name | Required | Type | Description |
|---|---|---|---|
| LeaderboardName | True |
string |
Name of the leaderboard. |
| MaxSurroundingEntries | True |
number |
Number of surrounding entries to return (in addition to specified entity). In general, the number of ranks above and below will be split into half. For example, if the specified value is 10, 5 ranks above and 5 ranks below will be retrieved. However, the numbers will get skewed in either direction when the specified entity is towards the top or bottom of the leaderboard. Also, the number of entries returned can be lower than the value specified for entries at the bottom of the leaderboard. |
| CustomTags |
object |
The optional custom tags associated with the request (e.g. build number, external trace identifiers, etc.). |
|
| Entity |
The optional entity to perform this action on. Defaults to the currently logged in entity. |
||
| Version |
number |
Optional version of the leaderboard, defaults to current. |
Responses
| Name | Type | Description |
|---|---|---|
| 200 OK |
Leaderboard response |
|
| 400 Bad Request |
This is the outer wrapper for all responses with errors |
Security
X-EntityToken
This API requires an Entity Session Token, available from the Entity GetEntityToken method.
Type:
apiKey
In:
header
Definitions
| Name | Description |
|---|---|
|
Api |
The basic wrapper around every failed API response |
|
Entity |
Combined entity type and ID structure which uniquely identifies a single entity. |
|
Entity |
Individual rank of an entity in a leaderboard |
|
Get |
Leaderboard response |
|
Get |
Request to load a section of a leaderboard centered on a specific entity. |
|
Leaderboard |
|
|
Leaderboard |
|
|
Linked |
ApiErrorWrapper
The basic wrapper around every failed API response
| Name | Type | Description |
|---|---|---|
| code |
integer |
Numerical HTTP code |
| error |
string |
Playfab error code |
| errorCode |
integer |
Numerical PlayFab error code |
| errorDetails |
object |
Detailed description of individual issues with the request object |
| errorMessage |
string |
Description for the PlayFab errorCode |
| status |
string |
String HTTP code |
EntityKey
Combined entity type and ID structure which uniquely identifies a single entity.
| Name | Type | Description |
|---|---|---|
| Id |
string |
Unique ID of the entity. |
| Type |
string |
Entity type. See https://docs.microsoft.com/gaming/playfab/features/data/entities/available-built-in-entity-types |
EntityLeaderboardEntry
Individual rank of an entity in a leaderboard
| Name | Type | Description |
|---|---|---|
| DisplayName |
string |
Entity's display name. |
| Entity |
Entity identifier. |
|
| LastUpdated |
string |
The time at which the last update to the entry was recorded on the server. |
| Metadata |
string |
An opaque blob of data stored on the leaderboard entry. Note that the metadata is not used for ranking purposes. |
| Rank |
number |
Position on the leaderboard. |
| Scores |
string[] |
Scores for the entry. |
GetEntityLeaderboardResponse
Leaderboard response
| Name | Type | Description |
|---|---|---|
| Columns |
Leaderboard columns describing the sort directions. |
|
| EntryCount |
number |
The number of entries on the leaderboard. |
| Rankings |
Individual entity rankings in the leaderboard, in sorted order by rank. |
|
| Version |
number |
Version of the leaderboard being returned. |
GetLeaderboardAroundEntityRequest
Request to load a section of a leaderboard centered on a specific entity.
| Name | Type | Description |
|---|---|---|
| CustomTags |
object |
The optional custom tags associated with the request (e.g. build number, external trace identifiers, etc.). |
| Entity |
The optional entity to perform this action on. Defaults to the currently logged in entity. |
|
| LeaderboardName |
string |
Name of the leaderboard. |
| MaxSurroundingEntries |
number |
Number of surrounding entries to return (in addition to specified entity). In general, the number of ranks above and below will be split into half. For example, if the specified value is 10, 5 ranks above and 5 ranks below will be retrieved. However, the numbers will get skewed in either direction when the specified entity is towards the top or bottom of the leaderboard. Also, the number of entries returned can be lower than the value specified for entries at the bottom of the leaderboard. |
| Version |
number |
Optional version of the leaderboard, defaults to current. |
LeaderboardColumn
| Name | Type | Description |
|---|---|---|
| LinkedStatisticColumn |
If the value for this column is sourced from a statistic, details of the linked column. Null if the leaderboard is not linked. |
|
| Name |
string |
A name for the leaderboard column, unique per leaderboard definition. |
| SortDirection |
The sort direction for this column. |
LeaderboardSortDirection
| Name | Type | Description |
|---|---|---|
| Ascending |
string |
|
| Descending |
string |
LinkedStatisticColumn
| Name | Type | Description |
|---|---|---|
| LinkedStatisticColumnName |
string |
The name of the statistic column that this leaderboard column is sourced from. |
| LinkedStatisticName |
string |
The name of the statistic. |
Error Codes
| Name | Code |
|---|---|
| LeaderboardNotFound | 1567 |
| NoLeaderboardForStatistic | 1421 |
| StatisticNotFound | 1195 |