엔터티 주변 순위표 가져오기

Get the leaderboard around a specific entity.

Allowed entity token types: title, title_player_account, game_server

Error codes

This operation may return the following PlayFab errors:

Error	Code
LeaderboardNotFound	1567
NoLeaderboardForStatistic	1421
SpecifiedVersionLeaderboardNotFound	1583
StatisticNotFound	1195

POST

Leaderboard

GetLeaderboardAroundEntity

Get Leaderboard Around Entity

curl --request POST \
  --url https://{titleId}.playfabapi.com/Leaderboard/GetLeaderboardAroundEntity \
  --header 'Content-Type: application/json' \
  --header 'X-EntityToken: <api-key>' \
  --data '
{
  "LeaderboardName": "Points",
  "Version": 2,
  "Entity": {
    "Id": "819478109412",
    "Type": "title_player_account",
    "TypeString": "title_player_account"
  }
}
'

import requests

url = "https://{titleId}.playfabapi.com/Leaderboard/GetLeaderboardAroundEntity"

payload = {
    "LeaderboardName": "Points",
    "Version": 2,
    "Entity": {
        "Id": "819478109412",
        "Type": "title_player_account",
        "TypeString": "title_player_account"
    }
}
headers = {
    "X-EntityToken": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'X-EntityToken': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    LeaderboardName: 'Points',
    Version: 2,
    Entity: {
      Id: '819478109412',
      Type: 'title_player_account',
      TypeString: 'title_player_account'
    }
  })
};

fetch('https://{titleId}.playfabapi.com/Leaderboard/GetLeaderboardAroundEntity', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://{titleId}.playfabapi.com/Leaderboard/GetLeaderboardAroundEntity",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'LeaderboardName' => 'Points',
    'Version' => 2,
    'Entity' => [
        'Id' => '819478109412',
        'Type' => 'title_player_account',
        'TypeString' => 'title_player_account'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "X-EntityToken: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://{titleId}.playfabapi.com/Leaderboard/GetLeaderboardAroundEntity"

	payload := strings.NewReader("{\n  \"LeaderboardName\": \"Points\",\n  \"Version\": 2,\n  \"Entity\": {\n    \"Id\": \"819478109412\",\n    \"Type\": \"title_player_account\",\n    \"TypeString\": \"title_player_account\"\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-EntityToken", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://{titleId}.playfabapi.com/Leaderboard/GetLeaderboardAroundEntity")
  .header("X-EntityToken", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"LeaderboardName\": \"Points\",\n  \"Version\": 2,\n  \"Entity\": {\n    \"Id\": \"819478109412\",\n    \"Type\": \"title_player_account\",\n    \"TypeString\": \"title_player_account\"\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://{titleId}.playfabapi.com/Leaderboard/GetLeaderboardAroundEntity")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["X-EntityToken"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"LeaderboardName\": \"Points\",\n  \"Version\": 2,\n  \"Entity\": {\n    \"Id\": \"819478109412\",\n    \"Type\": \"title_player_account\",\n    \"TypeString\": \"title_player_account\"\n  }\n}"

response = http.request(request)
puts response.read_body

{
  "code": 200,
  "status": "OK",
  "data": {
    "Version": 5,
    "Rankings": [
      {
        "Entity": {
          "Id": "1784371290HJA9",
          "Type": "title_player_account",
          "TypeString": "title_player_account"
        },
        "DisplayName": "FastHand",
        "Scores": [
          "4503"
        ],
        "Rank": 1
      },
      {
        "Entity": {
          "Id": "1947109JA18412",
          "Type": "title_player_account",
          "TypeString": "title_player_account"
        },
        "DisplayName": "Mouse",
        "Scores": [
          "4502"
        ],
        "Rank": 2
      }
    ]
  }
}

{
  "code": 123,
  "errorCode": 123,
  "status": "<string>",
  "error": "<string>",
  "errorMessage": "<string>",
  "errorDetails": {}
}

인증

X-EntityToken

string

header

필수

This API requires an Entity Session Token, available from the Entity GetEntityToken method.

본문

application/json

Request to load a section of a leaderboard centered on a specific 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.

CustomTags

object

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

Entity

object

The optional entity to perform this action on. Defaults to the currently logged in entity.

Show child attributes

Version

number

Optional version of the leaderboard, defaults to current.

응답

Leaderboard response

code

integer

The Http status code. If X-ReportErrorAsSuccess header is set to true, this will report the actual http error code.

status

string

The Http status code as a string.

data

object

Leaderboard response

Show child attributes

예시:

{
  "Version": 5,
  "Rankings": [
    {
      "Entity": {
        "Id": "1784371290HJA9",
        "Type": "title_player_account",
        "TypeString": "title_player_account"
      },
      "DisplayName": "FastHand",
      "Scores": ["4503"],
      "Rank": 1
    },
    {
      "Entity": {
        "Id": "1947109JA18412",
        "Type": "title_player_account",
        "TypeString": "title_player_account"
      },
      "DisplayName": "Mouse",
      "Scores": ["4502"],
      "Rank": 2
    }
  ]
}

마지막 수정일 2026년 10월 6일

⌘I

Get Leaderboard Around Entity

curl --request POST \
  --url https://{titleId}.playfabapi.com/Leaderboard/GetLeaderboardAroundEntity \
  --header 'Content-Type: application/json' \
  --header 'X-EntityToken: <api-key>' \
  --data '
{
  "LeaderboardName": "Points",
  "Version": 2,
  "Entity": {
    "Id": "819478109412",
    "Type": "title_player_account",
    "TypeString": "title_player_account"
  }
}
'

import requests

url = "https://{titleId}.playfabapi.com/Leaderboard/GetLeaderboardAroundEntity"

payload = {
    "LeaderboardName": "Points",
    "Version": 2,
    "Entity": {
        "Id": "819478109412",
        "Type": "title_player_account",
        "TypeString": "title_player_account"
    }
}
headers = {
    "X-EntityToken": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'X-EntityToken': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    LeaderboardName: 'Points',
    Version: 2,
    Entity: {
      Id: '819478109412',
      Type: 'title_player_account',
      TypeString: 'title_player_account'
    }
  })
};

fetch('https://{titleId}.playfabapi.com/Leaderboard/GetLeaderboardAroundEntity', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://{titleId}.playfabapi.com/Leaderboard/GetLeaderboardAroundEntity",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'LeaderboardName' => 'Points',
    'Version' => 2,
    'Entity' => [
        'Id' => '819478109412',
        'Type' => 'title_player_account',
        'TypeString' => 'title_player_account'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "X-EntityToken: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://{titleId}.playfabapi.com/Leaderboard/GetLeaderboardAroundEntity"

	payload := strings.NewReader("{\n  \"LeaderboardName\": \"Points\",\n  \"Version\": 2,\n  \"Entity\": {\n    \"Id\": \"819478109412\",\n    \"Type\": \"title_player_account\",\n    \"TypeString\": \"title_player_account\"\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-EntityToken", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://{titleId}.playfabapi.com/Leaderboard/GetLeaderboardAroundEntity")
  .header("X-EntityToken", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"LeaderboardName\": \"Points\",\n  \"Version\": 2,\n  \"Entity\": {\n    \"Id\": \"819478109412\",\n    \"Type\": \"title_player_account\",\n    \"TypeString\": \"title_player_account\"\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://{titleId}.playfabapi.com/Leaderboard/GetLeaderboardAroundEntity")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["X-EntityToken"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"LeaderboardName\": \"Points\",\n  \"Version\": 2,\n  \"Entity\": {\n    \"Id\": \"819478109412\",\n    \"Type\": \"title_player_account\",\n    \"TypeString\": \"title_player_account\"\n  }\n}"

response = http.request(request)
puts response.read_body

{
  "code": 200,
  "status": "OK",
  "data": {
    "Version": 5,
    "Rankings": [
      {
        "Entity": {
          "Id": "1784371290HJA9",
          "Type": "title_player_account",
          "TypeString": "title_player_account"
        },
        "DisplayName": "FastHand",
        "Scores": [
          "4503"
        ],
        "Rank": 1
      },
      {
        "Entity": {
          "Id": "1947109JA18412",
          "Type": "title_player_account",
          "TypeString": "title_player_account"
        },
        "DisplayName": "Mouse",
        "Scores": [
          "4502"
        ],
        "Rank": 2
      }
    ]
  }
}

{
  "code": 123,
  "errorCode": 123,
  "status": "<string>",
  "error": "<string>",
  "errorMessage": "<string>",
  "errorDetails": {}
}

PlayFab API

PlayFab REST API References

엔터티 주변 순위표 가져오기

Error codes

인증

본문

응답