通过

Player Data Management - Get Leaderboard

  • Reference
Service:
Client
API Version:
241025

Retrieves a list of ranked users for the given statistic, starting from the indicated point in the leaderboard

POST https://titleId.playfabapi.com/Client/GetLeaderboard

Request Header

Name Required Type Description
X-Authorization True

string

This API requires a client session ticket, available from any Client Login function.

Request Body

Name Required Type Description
StartPosition True

number

Position in the leaderboard to start this listing (defaults to the first entry).
StatisticName True

string

Statistic used to rank players for this leaderboard.
CustomTags

object

The optional custom tags associated with the request (e.g. build number, external trace identifiers, etc.).
MaxResultsCount

number

Maximum number of entries to retrieve. Default 10, maximum 100.
ProfileConstraints

PlayerProfileViewConstraints

If non-null, this determines which properties of the resulting player profiles to return. For API calls from the client, only the allowed client profile properties for the title may be requested. These allowed properties are configured in the Game Manager "Client Profile Options" tab in the "Settings" section.
UseSpecificVersion

boolean

If set to false, Version is considered null. If true, uses the specified Version
Version

number

The version of the leaderboard to get.

Responses

Name Type Description
200 OK

GetLeaderboardResult

Note: the user's Position is relative to the overall leaderboard.
400 Bad Request

ApiErrorWrapper

This is the outer wrapper for all responses with errors

Security

X-Authorization

This API requires a client session ticket, available from any Client Login function.

Type: apiKey
In: header

Definitions

Name Description
AdCampaignAttributionModel
ApiErrorWrapper

The basic wrapper around every failed API response
ContactEmailInfoModel
ContinentCode
CountryCode
EmailVerificationStatus
GetLeaderboardRequest
GetLeaderboardResult

Note: the user's Position is relative to the overall leaderboard.
LinkedPlatformAccountModel
LocationModel
LoginIdentityProvider
MembershipModel
PlayerLeaderboardEntry
PlayerProfileModel
PlayerProfileViewConstraints
PushNotificationPlatform
PushNotificationRegistrationModel
StatisticModel
SubscriptionModel
SubscriptionProviderStatus
TagModel
ValueToDateModel

AdCampaignAttributionModel

Name Type Description
AttributedAt

string

UTC time stamp of attribution
CampaignId

string

Attribution campaign identifier
Platform

string

Attribution network name

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

ContactEmailInfoModel

Name Type Description
EmailAddress

string

The email address
Name

string

The name of the email info data
VerificationStatus

EmailVerificationStatus

The verification status of the email

ContinentCode

Name Type Description
AF

string

AN

string

AS

string

EU

string

NA

string

OC

string

SA

string

Unknown

string

CountryCode

Name Type Description
AD

string

AE

string

AF

string

AG

string

AI

string

AL

string

AM

string

AO

string

AQ

string

AR

string

AS

string

AT

string

AU

string

AW

string

AX

string

AZ

string

BA

string

BB

string

BD

string

BE

string

BF

string

BG

string

BH

string

BI

string

BJ

string

BL

string

BM

string

BN

string

BO

string

BQ

string

BR

string

BS

string

BT

string

BV

string

BW

string

BY

string

BZ

string

CA

string

CC

string

CD

string

CF

string

CG

string

CH

string

CI

string

CK

string

CL

string

CM

string

CN

string

CO

string

CR

string

CU

string

CV

string

CW

string

CX

string

CY

string

CZ

string

DE

string

DJ

string

DK

string

DM

string

DO

string

DZ

string

EC

string

EE

string

EG

string

EH

string

ER

string

ES

string

ET

string

FI

string

FJ

string

FK

string

FM

string

FO

string

FR

string

GA

string

GB

string

GD

string

GE

string

GF

string

GG

string

GH

string

GI

string

GL

string

GM

string

GN

string

GP

string

GQ

string

GR

string

GS

string

GT

string

GU

string

GW

string

GY

string

HK

string

HM

string

HN

string

HR

string

HT

string

HU

string

ID

string

IE

string

IL

string

IM

string

IN

string

IO

string

IQ

string

IR

string

IS

string

IT

string

JE

string

JM

string

JO

string

JP

string

KE

string

KG

string

KH

string

KI

string

KM

string

KN

string

KP

string

KR

string

KW

string

KY

string

KZ

string

LA

string

LB

string

LC

string

LI

string

LK

string

LR

string

LS

string

LT

string

LU

string

LV

string

LY

string

MA

string

MC

string

MD

string

ME

string

MF

string

MG

string

MH

string

MK

string

ML

string

MM

string

MN

string

MO

string

MP

string

MQ

string

MR

string

MS

string

MT

string

MU

string

MV

string

MW

string

MX

string

MY

string

MZ

string

NA

string

NC

string

NE

string

NF

string

NG

string

NI

string

NL

string

NO

string

NP

string

NR

string

NU

string

NZ

string

OM

string

PA

string

PE

string

PF

string

PG

string

PH

string

PK

string

PL

string

PM

string

PN

string

PR

string

PS

string

PT

string

PW

string

PY

string

QA

string

RE

string

RO

string

RS

string

RU

string

RW

string

SA

string

SB

string

SC

string

SD

string

SE

string

SG

string

SH

string

SI

string

SJ

string

SK

string

SL

string

SM

string

SN

string

SO

string

SR

string

SS

string

ST

string

SV

string

SX

string

SY

string

SZ

string

TC

string

TD

string

TF

string

TG

string

TH

string

TJ

string

TK

string

TL

string

TM

string

TN

string

TO

string

TR

string

TT

string

TV

string

TW

string

TZ

string

UA

string

UG

string

UM

string

US

string

UY

string

UZ

string

Unknown

string

VA

string

VC

string

VE

string

VG

string

VI

string

VN

string

VU

string

WF

string

WS

string

YE

string

YT

string

ZA

string

ZM

string

ZW

string

EmailVerificationStatus

Name Type Description
Confirmed

string

Pending

string

Unverified

string

GetLeaderboardRequest

Name Type Description
CustomTags

object

The optional custom tags associated with the request (e.g. build number, external trace identifiers, etc.).
MaxResultsCount

number

Maximum number of entries to retrieve. Default 10, maximum 100.
ProfileConstraints

PlayerProfileViewConstraints

If non-null, this determines which properties of the resulting player profiles to return. For API calls from the client, only the allowed client profile properties for the title may be requested. These allowed properties are configured in the Game Manager "Client Profile Options" tab in the "Settings" section.
StartPosition

number

Position in the leaderboard to start this listing (defaults to the first entry).
StatisticName

string

Statistic used to rank players for this leaderboard.
UseSpecificVersion

boolean

If set to false, Version is considered null. If true, uses the specified Version
Version

number

The version of the leaderboard to get.

GetLeaderboardResult

Note: the user's Position is relative to the overall leaderboard.

Name Type Description
Leaderboard

PlayerLeaderboardEntry[]

Ordered listing of users and their positions in the requested leaderboard.
NextReset

string

The time the next scheduled reset will occur. Null if the leaderboard does not reset on a schedule.
Version

number

The version of the leaderboard returned.

LinkedPlatformAccountModel

Name Type Description
Email

string

Linked account email of the user on the platform, if available
Platform

LoginIdentityProvider

Authentication platform
PlatformUserId

string

Unique account identifier of the user on the platform
Username

string

Linked account username of the user on the platform, if available

LocationModel

Name Type Description
City

string

City name.
ContinentCode

ContinentCode

The two-character continent code for this location
CountryCode

CountryCode

The two-character ISO 3166-1 country code for the country associated with the location
Latitude

number

Latitude coordinate of the geographic location.
Longitude

number

Longitude coordinate of the geographic location.

LoginIdentityProvider

Name Type Description
AndroidDevice

string

Apple

string

Custom

string

CustomServer

string

Facebook

string

FacebookInstantGames

string

GameCenter

string

GameServer

string

GooglePlay

string

GooglePlayGames

string

IOSDevice

string

King

string

Kongregate

string

NintendoSwitch

string

NintendoSwitchAccount

string

OpenIdConnect

string

PSN

string

PlayFab

string

Steam

string

Twitch

string

Unknown

string

WindowsHello

string

XBoxLive

string

XboxMobileStore

string

MembershipModel

Name Type Description
IsActive

boolean

Whether this membership is active. That is, whether the MembershipExpiration time has been reached.
MembershipExpiration

string

The time this membership expires
MembershipId

string

The id of the membership
OverrideExpiration

string

Membership expirations can be explicitly overridden (via game manager or the admin api). If this membership has been overridden, this will be the new expiration time.
OverrideIsSet

boolean

Whether the override expiration is set.
Subscriptions

SubscriptionModel[]

The list of subscriptions that this player has for this membership

PlayerLeaderboardEntry

Name Type Description
DisplayName

string

Title-specific display name of the user for this leaderboard entry.
PlayFabId

string

PlayFab unique identifier of the user for this leaderboard entry.
Position

number

User's overall position in the leaderboard.
Profile

PlayerProfileModel

The profile of the user, if requested.
StatValue

number

Specific value of the user's statistic.

PlayerProfileModel

Name Type Description
AdCampaignAttributions

AdCampaignAttributionModel[]

List of advertising campaigns the player has been attributed to
AvatarUrl

string

URL of the player's avatar image
BannedUntil

string

If the player is currently banned, the UTC Date when the ban expires
ContactEmailAddresses

ContactEmailInfoModel[]

List of all contact email info associated with the player account
Created

string

Player record created
DisplayName

string

Player display name
ExperimentVariants

string[]

List of experiment variants for the player. Note that these variants are not guaranteed to be up-to-date when returned during login because the player profile is updated only after login. Instead, use the LoginResult.TreatmentAssignment property during login to get the correct variants and variables.
LastLogin

string

UTC time when the player most recently logged in to the title
LinkedAccounts

LinkedPlatformAccountModel[]

List of all authentication systems linked to this player account
Locations

LocationModel[]

List of geographic locations from which the player has logged in to the title
Memberships

MembershipModel[]

List of memberships for the player, along with whether are expired.
Origination

LoginIdentityProvider

Player account origination
PlayerId

string

PlayFab player account unique identifier
PublisherId

string

Publisher this player belongs to
PushNotificationRegistrations

PushNotificationRegistrationModel[]

List of configured end points registered for sending the player push notifications
Statistics

StatisticModel[]

List of leaderboard statistic values for the player
Tags

TagModel[]

List of player's tags for segmentation
TitleId

string

Title ID this player profile applies to
TotalValueToDateInUSD

number

Sum of the player's purchases made with real-money currencies, converted to US dollars equivalent and represented as a whole number of cents (1/100 USD). For example, 999 indicates nine dollars and ninety-nine cents.
ValuesToDate

ValueToDateModel[]

List of the player's lifetime purchase totals, summed by real-money currency

PlayerProfileViewConstraints

Name Type Description
ShowAvatarUrl

boolean

Whether to show player's avatar URL. Defaults to false
ShowBannedUntil

boolean

Whether to show the banned until time. Defaults to false
ShowCampaignAttributions

boolean

Whether to show campaign attributions. Defaults to false
ShowContactEmailAddresses

boolean

Whether to show contact email addresses. Defaults to false
ShowCreated

boolean

Whether to show the created date. Defaults to false
ShowDisplayName

boolean

Whether to show the display name. Defaults to false
ShowExperimentVariants

boolean

Whether to show player's experiment variants. Defaults to false
ShowLastLogin

boolean

Whether to show the last login time. Defaults to false
ShowLinkedAccounts

boolean

Whether to show the linked accounts. Defaults to false
ShowLocations

boolean

Whether to show player's locations. Defaults to false
ShowMemberships

boolean

Whether to show player's membership information. Defaults to false
ShowOrigination

boolean

Whether to show origination. Defaults to false
ShowPushNotificationRegistrations

boolean

Whether to show push notification registrations. Defaults to false
ShowStatistics

boolean

Reserved for future development
ShowTags

boolean

Whether to show tags. Defaults to false
ShowTotalValueToDateInUsd

boolean

Whether to show the total value to date in usd. Defaults to false
ShowValuesToDate

boolean

Whether to show the values to date. Defaults to false

PushNotificationPlatform

Name Type Description
ApplePushNotificationService

string

GoogleCloudMessaging

string

PushNotificationRegistrationModel

Name Type Description
NotificationEndpointARN

string

Notification configured endpoint
Platform

PushNotificationPlatform

Push notification platform

StatisticModel

Name Type Description
Name

string

Statistic name
Value

number

Statistic value
Version

number

Statistic version (0 if not a versioned statistic)

SubscriptionModel

Name Type Description
Expiration

string

When this subscription expires.
InitialSubscriptionTime

string

The time the subscription was orignially purchased
IsActive

boolean

Whether this subscription is currently active. That is, if Expiration > now.
Status

SubscriptionProviderStatus

The status of this subscription, according to the subscription provider.
SubscriptionId

string

The id for this subscription
SubscriptionItemId

string

The item id for this subscription from the primary catalog
SubscriptionProvider

string

The provider for this subscription. Apple or Google Play are supported today.

SubscriptionProviderStatus

Name Type Description
BillingError

string

Cancelled

string

CustomerDidNotAcceptPriceChange

string

FreeTrial

string

NoError

string

PaymentPending

string

ProductUnavailable

string

UnknownError

string

TagModel

Name Type Description
TagValue

string

Full value of the tag, including namespace

ValueToDateModel

Name Type Description
Currency

string

ISO 4217 code of the currency used in the purchases
TotalValue

number

Total value of the purchases in a whole number of 1/100 monetary units. For example, 999 indicates nine dollars and ninety-nine cents when Currency is 'USD')
TotalValueAsDecimal

string

Total value of the purchases in a string representation of decimal monetary units. For example, '9.99' indicates nine dollars and ninety-nine cents when Currency is 'USD'.

Error Codes

Name Code
LeaderboardVersionNotAvailable 1277