Skip to main content

Leaderboard

Leaderboard​

The Leaderboard API allows clients to retrieve leaderboard positions for gamers and applications. It supports operations to get a gamer's position within a leaderboard and to fetch all leaderboards associated with an application.

info

Base Endpoint: /api/v1/

Available Endpoints​

1. Get Gamer Leaderboard Position​

  • Method & Path: GET /leaderboard
  • Description: Retrieves the leaderboard position of a gamer based on specified criteria.
  • Query Parameters:
    • statId: The ID of the statistic to filter the leaderboard by.
    • repeatInterval: The interval for repeating leaderboard calculations. (DAILY, WEEKLY, MONTHLY, NEVER)
    • aggregationType: The type of aggregation used for leaderboard calculations. (SUM, MAX)
  • Headers:
    • Authorization: Required. A valid authentication token.
  • Response:
    • A JSON object. containing the following fields:
      • gamerPosition: JSON object containing the position of requesting gamer for that leaderboard
        • position: Position of the gamer in the leaderboard
        • gamer: JSON object containing information about requesting gamer
          • id: Unique ID of the gamer
          • name: Display Name of the gamer
          • avatar: Avatar of the gamer
        • stat: JSON object containing detail about stat
          • id: Unique Id of the stat
          • name: Name of the stat
          • value: Requesting player's value for the stat
        • values: Array of JSON object containing object of
          • position: Position of a gamer in the leaderboard
          • gamer: JSON object containing information about gamer
            • id: Unique Id of the gamer
            • name: Display name of the gamer
            • avatar: Avatar of the gamer
          • stat: JSON object containing details about stat
            • id: Unique Id of the stat
            • name: Name of the stat
            • value: Player's value for the stat

cURL Command​

curl --request GET \
  --url 'https://api.yarsaplay.com/api/v1/leaderboard?statId=&repeatInterval=DAILY&aggregationType=SUM' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

Response Body​

{
  "gamerPosition": {
    "gamer": {
      "avatar": "<string>",
      "id": "<uuid>",
      "name": "<string>"
    },
    "position": "<number>",
    "stat": {
      "id": "<uuid>",
      "name": "<string>",
      "value": "<number>"
    }
  },
  "values": [
    {
      "gamer": {
        "avatar": "<string>",
        "id": "<uuid>",
        "name": "<string>"
      },
      "position": "<number>",
      "stat": {
        "id": "<uuid>",
        "name": "<string>",
        "value": "<number>"
      }
    },
    {
      "gamer": {
        "avatar": "<string>",
        "id": "<uuid>",
        "name": "<string>"
      },
      "position": "<number>",
      "stat": {
        "id": "<uuid>",
        "name": "<string>",
        "value": "<number>"
      }
    }
  ]
}

2. Get Application Leaderboards​

  • Method & Path: GET /:applicationId/leaderboards
  • Description: Fetches all leaderboards associated with a given application.
  • URL Parameters:
    • applicationId: The unique identifier of the application.
  • Headers:
    • Authorization: Required. A valid authentication token.
  • Response:
    • An array of JSON objects, each representing configured leaderboard for the application
      • id: ID of the configured leaderboard
      • name: Name of the configured leaderboard
      • resetIntervalType:Interval when the leaderboard resets (DAILY,WEEKLY, MONTHLY, NEVER )
      • aggregationType: The type of aggregation used for leaderboard calculations. (SUM, MAX)
      • applicationStat: JSON object containing detail about the stat for leaderboard
        • id: ID of the stat
        • name: Name of the stat

cURL Command​

curl --request GET \
  --url https://api.yarsaplay.com/api/v1/__APPLICATIONID__/leaderboards

Response Body​

[
  {
    "aggregationType": "<string>",
    "applicationStat": {
      "id": "<uuid>",
      "name": "<string>"
    },
    "id": "<uuid>",
    "name": "<string>",
    "resetIntervalType": "<string>"
  },
  {
    "aggregationType": "<string>",
    "applicationStat": {
      "id": "<uuid>",
      "name": "<string>"
    },
    "id": "<uuid>",
    "name": "<string>",
    "resetIntervalType": "<string>"
  }
]