The Leaderboards Metadata API

Some games may have multiple types of scores. You can use The Leaderboard Metadata API to distinguish them from one another.

Understanding Leaderboards

Let's say there's an endless runner game with 2 modes: "easy" and "hard". If you wanted to create leaderboards for the game for your users, it would only be fair that there are 2 separate leaderboards — one for the easy mode, and one for the hard mode.

To be able to do that, you need to distinguish which mode the user was playing in when we post a score to your webhook. This is where Leaderboards come in. Scores are not recorded against a game, they are recorded against a Leaderboard. A game may have more than one Leaderboard.

Note: This API does not return user scores sorted as in a leaderboard. Instead, it returns metadata on the different Leaderboards that exist for any game.

Most games have a single Leaderboard. This document is useful if you're taking a game from us which has multiple Leaderboards.

---

Get all Leaderboards for a game

The Leaderboards Metadata API can be used to fetch details of all the Leaderboards that can be made for a particular game.

API endpoint

GET https://api.gamezop.com/v3/leaderboards-metadata

Headers

Name	Description
Authorization: Bearer*	You must ask your Gamezop Account Manager to get your Bearer token created for you. You can then find the Bearer token for this API under Settings & Admin > API Tokens within the Gamezop Business Dashboard.

Query parameters

Name	Description
game-code	The of the Gamezop game for which you want to fetch Leaderboards' metadata.

---

Understanding the response

HTTP response codes

The API provides a JSON response with a data object. This, in turn, contains an array of JSON objects, each representing 1 Leaderboard.

200: OK

Expected response body:

This sample response contains 1 single Leaderboard object. Your API response may contain more, depending on the number of Leaderboards present for that game.

{
  "data": [
    {
      "leaderboard_id": "NkxfOJM-qg_default",
      "name": "Score leaderboard",
      "description": "Rankings of best scores made in Fidgety Frog",
      "score_type": "number",
      "sorting_order": "ascending"
    }
  ],
  "success": true
}

If the game you are requesting data for has no Leaderboards, then you will get a 200:OK response, but the data array will be empty.

401: Unauthorized

Occurs when the Bearer Token is incorrect / not provided / belongs to an archived Property.

400: Bad Request

Occurs when the game-code parameter is not provided.

404: Not Found

Occurs if the game code provided in the URL parameter is not a valid game code.

Response body

The table below explains each of the fields the API returns within a game object.

Key	Description
leaderboard_id	A unique identifier for the Leaderboard
name	English name of the Leaderboard (can be displayed to end-users)
description	A short english description of the Leaderboard (can be displayed to end-users)
score_type	Type of values that are captured as scores on the Leaderboard. Possible values are number and percent
sorting_order	Captures how scores for the Leaderboard progress: ascending means that higher score is better descending means that lower scores are better

---