Leaderboard

Prev Next

Leaderboard API

Register leaderboard user score API

Request

  • Method : POST
  • URI : https://gamepot.apigw.ntruss.com/gpapps/v2/leaderboardlogs
POST
url : https://gamepot.apigw.ntruss.com/gpapps/v2/leaderboardlogs
Header : 'content-type: application/json'
Header 'x-api-key: 86dcgffae0xxxxxxxxxxxxxx'
Header : 'x-project-id: ec8231b2-6b20-4ad1-xxxx-xxxxxxxxx'
data:
{
     "leaderboardId" : "leaderboardId",
    "userId" : "70045665-f64a-45c0-xxxx-xxxxxxxxx",
    "score": 10,
    "subscore": 0,
    "metadata": "{\"key\":\"value\"}"
}
Header Type Required Description
X-API-KEY String O Authentication key issued by GAMEPOT
X-PROJECT-ID String O Dashboard project ID
Attribute Type Required Description
leaderboardId String O Leaderboard unique ID generated in the dashboard
userId String O User ID
score Integer X Score
subscore Integer X Subscore (not required)
metadata String X Additional information

Response

Succeeded

{
   "leaderboardlog": {
        "project_id": "ec8231b2-6b20-4ad1-xxxx-xxxxxxxxx",
        "id": "TGVhZGVyYm9hcmRMb2c6NjNkMzRhYTgxxxxxxxxx",
        "user_id": "70045665-f64a-45c0-xxxx-xxxxxxxxx",
        "score": 10,
        "subscore": 0,
        "metadata": "{\"key\":\"value\"}",
        "expiredAt": "2023-01-30T20:00:00-08:00"
    }
}
Attribute Type Description
status Int Result value \ (-1 fail )
message String Error message
leaderboardlog.project_id String Project ID
leaderboardlog.id String Input ID
leaderboardlog.user_id String User ID
leaderboardlog.score Int Score
leaderboardlog.subscore Int Subscore
leaderboardlog.metadata Int User created data
leaderboardlog.expiredAt String Expiry date

Failure

{
    "status": -1,
    "message": "Registration failed"
}
Attribute Type Description
code Int Result \ (1: success, refer to the error code in case of failure )
error String Error message

Retrieve user score from leaderboard API

Request

  • Method : GET
  • URI : https://gamepot.apigw.ntruss.com/gpapps/v2/leaderboardlogs
GET
url : https://gamepot.apigw.ntruss.com/gpapps/v2/leaderboardlogs
Header : 'content-type: application/json'
Header 'x-api-key: 86dcgffae0xxxxxxxxxxxxxx'
Header : 'x-project-id: ec8231b2-6b20-4ad1-xxxx-xxxxxxxxx'
data:
{
     "leaderboardId" : "leaderboardId",
    "offset": 0,
    "per_page": 20
}
Header Type Required Description
X-API-KEY String O Authentication key issued by GAMEPOT
X-PROJECT-ID String O Dashboard project ID
Attribute Type Required Description
leaderboardId String O Leaderboard unique ID generated in the dashboard
offset Integer X OFFSET
per_page Integer X LIMIT

Response

Succeeded

[
    {
        "rank": 1,
        "leaderboard_id": "leaderboardId",
        "user_id": "9c510599-f77a-4e3e-xxxxxx-xxxxxxx",
         "project_id": "ec8231b2-6b20-4ad1-9c59-xxxxxxxxxxx",
        "score": 1100,
        "subscore": 0,
        "metadata": "{\"key\":\"value\"}",
        "expiredAt": "2023-01-30T20:00:00-08:00",
        "updatedAt": "2023-01-26T19:46:07-08:00"
    },
    {
        "rank": 2,
        "leaderboard_id": "leaderboardId",
        "user_id": "63ae4ac9-a0f4-4fba-xxxx-xxxxxxxx",
        "project_id": "ec8231b2-6b20-4ad1-9c59-xxxxxxxxxxx",
        "score": 1000,
        "subscore": 0,
        "metadata": "{\"key\":\"value\"}",
        "expiredAt": "2023-01-30T20:00:00-08:00",
        "updatedAt": "2023-01-26T19:45:58-08:00"
    },
]
Attribute Type Description
status Int Result value \ (-1 fail )
message String Error message
rank Int Ranking
project_id String Project ID
leaderboardId String Leaderboard unique ID generated in the dashboard
user_id String User ID
score Int Score
subscore Int Subscore
metadata Int User created data
updatedAt String Updated date
expiredAt String Expiration date

Failure

{
    "status": -1,
    "message": "Failure to search"
}
Attribute Type Description
status Int Result \ (refer to the error code in case of failure )
message String Error message

Retrieve score with specific keyword API

Request

  • Method : GET
  • URI : https://gamepot.apigw.ntruss.com/gpapps/v2/leaderboardlogs

Search with ID

GET
url : https://gamepot.apigw.ntruss.com/gpapps/v2/leaderboardlogs
Header : 'content-type: application/json'
Header 'x-api-key: 86dcgffae0xxxxxxxxxxxxxx'
Header : 'x-project-id: ec8231b2-6b20-4ad1-xxxx-xxxxxxxxx'
data:
{
     "leaderboardId" : "leaderboardId",
     "search" : "user_id",
     "query" : "f1deb103-cae1-47dd-b0aa-xxxxxxxxxx",
    "offset": 0,
    "per_page": 20
}

Search with SCORE range

GET
url : https://gamepot.apigw.ntruss.com/gpapps/v2/leaderboardlogs
Header : 'content-type: application/json'
Header 'x-api-key: 86dcgffae0xxxxxxxxxxxxxx'
Header : 'x-project-id: ec8231b2-6b20-4ad1-xxxx-xxxxxxxxx'
data:
{
     "leaderboardId" : "leaderboardId",
     "search" : "score",
     "query" : "99-120",
    "offset": 0,
    "per_page": 20
}
Header Type Required Description
X-API-KEY String O Authentication key issued by GAMEPOT
X-PROJECT-ID String O Dashboard project ID
Attribute Type Required Description
leaderboardId String O Leaderboard unique ID generated in the dashboard
offset Integer X OFFSET
per_page Integer X LIMIT

Response

Succeeded

[
    {
        "rank": 5,
        "leaderboard_id": "leaderboardId",
        "user_id": "f1deb103-cae1-47dd-b0aa-xxxxxx",
        "project_id": "ec8231b2-6b20-4ad1-9c59-xxxxxxxxx",
        "score": 99,
        "subscore": 100,
        "metadata": "{\"key\":\"value\"}",
        "expiredAt": "2023-01-30T20:00:00-08:00",
        "updatedAt": "2023-01-26T16:23:39-08:00"
    }
]

Failure

{
    "status": -1,
    "message": "Error message"
}
Attribute Type Description
status Int Result \ (refer to the error code in case of failure )
message String Error message

Retrieve leaderboard information and user count API

Request

  • Method : GET
  • URI : https://gamepot.apigw.ntruss.com/gpapps/v2/leaderboards?/{leaderboardId}?offset=0&per_page=10
GET
url : https://gamepot.apigw.ntruss.com/gpapps/v2/leaderboard
Header 'x-api-key: 86dcgffae0xxxxxxxxxxxxxx'
Header : 'x-project-id: ec8231b2-6b20-4ad1-xxxx-xxxxxxxxx'
Header Type Required Description
X-API-KEY String O Authentication key issued by GAMEPOT
X-PROJECT-ID String O Dashboard project ID
Attribute Type Required Description
leaderboardId String O Leaderboard unique ID generated in the dashboard
offset Integer X OFFSET
per_page Integer X LIMIT

Response

Succeeded

[
    {
        "status": true,
        "ranking": "best",
        "tie_breaking": "first",
        "id": "TGVhZGVyYm9hcmQ6YXNkYWRhZHNhZHNh",
        "name": "test",
        "description": "TEST",
        "descending": true,
        "resetDay": 0,
        "resetTime": "00:00",
        "resetDate": 1,
        "startedAt": "2023-01-25T12:09:47-08:00",
        "timezone": "America/Kralendijk",
        "project_id": "ec8231b2-6b20-4ad1-9c59-8e183087a742",
        "period_type": "monthly",
        "icon_url": "sdadasds",
        "user_count": 28,
    }
]
Attribute Type Required Description
id String O Leaderboard unique ID
projectId String O Project ID
status Boolean O Condition
is_check_user Boolean X Whether to check the user ID
name String X Leaderboard name
description String X Description
icon_url String X Icon URL
descending Boolean X Sort
startedAt String X Start date
expiredAt String X End date (if seasonal)
timezone String X Time zone
period_type String X Cycle (daily, weekly, monthly, season)
resetDay Integer X Reset day 1: Sun, 2: Mon, 3: Tue, 4: Wed, 5: Thu, 6: Fri, 7: Sat (where the periodType is weekly)
resetTime String X Reset time
resetDate Integer X Reset date 1-31 (where the periodType is monthly)
ranking String O Ranking update criteria (latest, accumulated, best)
tie_breaking String O Tie breaker (first, last)

Failure

{
    "status": -1,
    "message": "Error message"
}
Attribute Type Description
status Int Result \ (refer to the error code in case of failure )
message String Error message

Search user score in leaderboard API

Request

  • Method : GET
  • URI : https://gamepot.apigw.ntruss.com/gpapps/v2/leaderboard/{leaderboardID}/user{userid}
GET
url : https://gamepot.apigw.ntruss.com/gpapps/v2/leaderboard
Header 'x-api-key: 86dcgffae0xxxxxxxxxxxxxx'
Header : 'x-project-id: ec8231b2-6b20-4ad1-xxxx-xxxxxxxxx'
Header Type Required Description
X-API-KEY String O Authentication key issued by GAMEPOT
X-PROJECT-ID String O Dashboard project ID
Attribute Type Required Description
leaderboardID String O Leaderboard unique ID generated in the dashboard
userid String O User ID

Response

Succeeded

{
	"rank": 1,
	"leaderboard_id": "leaderboardID",
	"user_id": "8f372bf4-XXXX-XXXX-XXXX-XXXXXXXX",
	"project_id": "ec8231b2-6b20-4ad1-XXXX-XXXXXXXX",
	"score": 1,
	"prev_score": null,
	"subscore": 10,
	"metadata": "",
	"user_count": 2,
	"expiredAt": "2023-01-30T17:00:00+09:00",
	"updatedAt": "2023-01-30T11:55:37+09:00"
}
Attribute Type Description
status Int Result value \ (-1 fail )
message String Error message
rank Int Ranking
project_id String Project ID
leaderboardId String Leaderboard unique ID generated in the dashboard
user_id String User ID
score Int Score
subscore Int Subscore
metadata Int User created data
updatedAt String Updated date
expiredAt String Expiration date

Failure

{
    "status": -1,
    "message": "Error message"
}
Attribute Type Description
status Int Result \ (refer to the error code in case of failure )
message String Error message

Delete user registered in leaderboard API

Request

  • Method : DELETE
  • URI : https://gamepot.apigw.ntruss.com/gpapps/v2/leaderboardlogs
DELETE
url : https://gamepot.apigw.ntruss.com/gpapps/v2/leaderboardlogs
Header : 'content-type: application/json'
Header 'x-api-key: 86dcgffae0xxxxxxxxxxxxxx'
Header : 'x-project-id: ec8231b2-6b20-4ad1-xxxx-xxxxxxxxx'
data:
{
     "leaderboardId" : "leaderboardId",
     "userId" : "560963c3-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}
Header Type Required Description
X-API-KEY String O Authentication key issued by GAMEPOT
X-PROJECT-ID String O Dashboard project ID
Attribute Type Required Description
leaderboardId String X Leaderboard ID
userId String X Leaderboard user ID

Response

Succeeded

[
    {
        "leaderboard_id": "leaderboardId",
        "user_id": "f1deb103-cae1-47dd-b0aa-xxxxxx",
        "project_id": "ec8231b2-6b20-4ad1-9c59-xxxxxxxxx",
        "score": 99,
        "subscore": 100,
        "metadata": "{\"key\":\"value\"}",
        "expiredAt": "2023-01-30T20:00:00-08:00",
        "updatedAt": "2023-01-26T16:23:39-08:00"
    }
]
Attribute Type Description
status Int Result value \ (-1 fail )
message String Error message
project_id String Project ID
leaderboardId String Leaderboard unique ID generated in the dashboard
user_id String User ID
score Int Score
subscore Int Subscore
metadata Int User created data
updatedAt String Updated date
expiredAt String Expiration date

Failure

{
    "status": -1,
    "message": "Error message"
}
Attribute Type Description
status Int Result \ (refer to the error code in case of failure )
message String Error message

Register leaderboard API

Request

  • Method : POST
  • URI : https://gamepot.apigw.ntruss.com/gpapps/v2/leaderboards
POST
url : https://gamepot.apigw.ntruss.com/gpapps/v2/leaderboards
Header : 'content-type: application/json'
Header 'x-api-key: 86dcgffae0xxxxxxxxxxxxxx'
Header : 'x-project-id: ec8231b2-6b20-4ad1-xxxx-xxxxxxxxx'
data:
{
    "id" : "leaderboardId",
    "status": true,
    "name": "name",
    "description": "description",
    "iconUrl" : "icon_url",
    "descending": true,
    "startedAt" : "2023-01-22 13:00:00",
    "timezone" : "Asia/Seoul",
    "periodType" : "weekly",
    "resetDay": 1,
    "resetDate": 1,
    "resetTime" : "00:01:01",
    "ranking" : "latest", 
    "tie_breaking" : "first"
}
Header Type Required Description
X-API-KEY String O Authentication key issued by GAMEPOT
X-PROJECT-ID String O Dashboard project ID
Attribute Type Required Description
id String O Leaderboard unique ID
projectId String O Project ID
status Boolean O Condition
is_check_user Boolean X Whether to check the user ID
name String X Leaderboard name
description String X Description
iconUrl String X Icon URL
descending Boolean X Sort
startedAt String X Start date
expiredAt String X End date (if seasonal)
timezone String X Time zone
period_type String X Cycle (daily, weekly, monthly, season)
resetDay Integer X Reset day 1: Sun, 2: Mon, 3: Tue, 4: Wed, 5: Thu, 6: Fri, 7: Sat (where the periodType is weekly)
resetTime String X Reset time
resetDate Integer X Reset date 1-31 (where the periodType is monthly)
ranking String O Ranking update criteria (latest, accumulated, best)
tie_breaking String O Tie breaker (first, last)

Response

Succeeded

{
   "leaderboard": {
        "status": true,
        "is_check_user": true,
        "ranking": "latest",
        "tie_breaking": "first",
        "id": "TGVhZGVyYm9hcmQ6ZHNzZGFkMTIyMjIyMTJhZA==",
        "name": "name",
        "description": "description",
        "descending": true,
        "resetDay": 1,
        "resetTime": "00:01:01",
        "resetDate": 1,
        "startedAt": "2023-01-22T13:00:00-08:00",
        "expiredAt": "2023-11-22T13:00:00-08:00",
        "timezone": "Asia/Seoul",
        "project_id": "ec8231b2-6b20-4ad1-9c59-8e183087a742",
        "period_type": "weekly",
        "icon_url": "icon_url",
        "user_count": null,
        "updatedAt": "2023-02-01T15:52:24-08:00",
        "createdAt": "2023-02-01T15:52:24-08:00"
    }
}
Attribute Type Required Description
id String O Leaderboard unique ID
projectId String O Project ID
status Boolean O Condition
is_check_user Boolean X Whether to check the user ID
name String X Leaderboard name
description String X Description
icon_url String X Icon URL
descending Boolean X Sort
startedAt String X Start date
expiredAt String X End date (if seasonal)
timezone String X Time zone
period_type String X Cycle (daily, weekly, monthly, season)
resetDay Integer X Reset day 1: Sun, 2: Mon, 3: Tue, 4: Wed, 5: Thu, 6: Fri, 7: Sat (where the periodType is weekly)
resetTime String X Reset time
resetDate Integer X Reset date 1-31 (where the periodType is monthly)
ranking String O Ranking update criteria (latest, accumulated, best)
tie_breaking String O Tie breaker (first, last)

Failure

 "status": -1,
"message": "Error message"
Attribute Type Description
code Int Result \ (1: success, refer to the error code in case of failure )
error String Error message

Edit leaderboard API

Request

  • Method : PUT
  • URI : https://gamepot.apigw.ntruss.com/gpapps/v2/leaderboards/{leaderboardId}
PUT
url : https://gamepot.apigw.ntruss.com/gpapps/v2/leaderboards/{leaderboardId}
Header : 'content-type: application/json'
Header 'x-api-key: 86dcgffae0xxxxxxxxxxxxxx'
Header : 'x-project-id: ec8231b2-6b20-4ad1-xxxx-xxxxxxxxx'
data:
{
    "status": true,
    "name": "name",
    "description": "description",
    "iconUrl" : "icon_url",
    "descending": true,
    "startedAt" : "2023-01-22 13:00:00",
    "timezone" : "Asia/Seoul",
    "periodType" : "weekly",
    "resetDay": 1,
    "resetDate": 1,
    "resetTime" : "00:01:01",
    "ranking" : "latest", 
    "tie_breaking" : "first"
}
Header Type Required Description
X-API-KEY String O Authentication key issued by GAMEPOT
X-PROJECT-ID String O Dashboard project ID
Attribute Type Required Description
leaderboardId String O Leaderboard unique ID
status Boolean O Condition
is_check_user Boolean X Whether to check the user ID
name String X Leaderboard name
description String X Description
icon_url String X Icon URL
descending Boolean X Sort
startedAt String X Start date
expiredAt String X End date (if seasonal)
timezone String X Time zone
period_type String X Cycle (daily, weekly, monthly, season)
resetDay Integer X Reset day 1: Sun, 2: Mon, 3: Tue, 4: Wed, 5: Thu, 6: Fri, 7: Sat (where the periodType is weekly)
resetTime String X Reset time
resetDate Integer X Reset date 1-31 (where the periodType is monthly)
ranking String O Ranking update criteria (latest, accumulated, best)
tie_breaking String O Tie breaker (first, last)

Response

Succeeded

{
   "leaderboard": {
        "status": true,
        "is_check_user": true,
        "ranking": "latest",
        "tie_breaking": "first",
        "id": "TGVhZGVyYm9hcmQ6ZHNzZGFkMTIyMjIyMTJhZA==",
        "name": "name",
        "description": "description",
        "descending": true,
        "resetDay": 1,
        "resetTime": "00:01:01",
        "resetDate": 1,
        "startedAt": "2023-01-22T13:00:00-08:00",
        "expiredAt": "2023-11-22T13:00:00-08:00",
        "timezone": "Asia/Seoul",
        "project_id": "ec8231b2-6b20-4ad1-9c59-8e183087a742",
        "period_type": "weekly",
        "icon_url": "icon_url",
        "user_count": null,
        "updatedAt": "2023-02-01T15:52:24-08:00",
        "createdAt": "2023-02-01T15:52:24-08:00"
    }
}
Attribute Type Required Description
id String O Leaderboard unique ID
projectId String O Project ID
status Boolean O Condition
is_check_user Boolean X Whether to check the user ID
name String X Leaderboard name
description String X Description
icon_url String X Icon URL
descending Boolean X Sort
startedAt String X Start date
expiredAt String X End date (if seasonal)
timezone String X Time zone
period_type String X Cycle (daily, weekly, monthly, season)
resetDay Integer X Reset day 1: Sun, 2: Mon, 3: Tue, 4: Wed, 5: Thu, 6: Fri, 7: Sat (where the periodType is weekly)
resetTime String X Reset time
resetDate Integer X Reset date 1-31 (where the periodType is monthly)
ranking String O Ranking update criteria (latest, accumulated, best)
tie_breaking String O Tie breaker (first, last)

Failure

 "status": -1,
"message": "Error message"
Attribute Type Description
code Int Result \ (1: success, refer to the error code in case of failure )
error String Error message

Delete leaderboard API

Request

  • Method : DELETE
  • URI : https://gamepot.apigw.ntruss.com/gpapps/v2/leaderboards/{leaderboardId}
DELETE
url : https://gamepot.apigw.ntruss.com/gpapps/v2/leaderboards/leaderboardId
Header 'x-api-key: 86dcgffae0xxxxxxxxxxxxxx'
Header : 'x-project-id: ec8231b2-6b20-4ad1-xxxx-xxxxxxxxx'
Header Type Required Description
X-API-KEY String O Authentication key issued by GAMEPOT
X-PROJECT-ID String O Dashboard project ID
Attribute Type Required Description
leaderboardId String O Leaderboard unique ID

Response

Succeeded

{
   "leaderboard": {
        "status": true,
        "is_check_user": true,
        "ranking": "latest",
        "tie_breaking": "first",
        "id": "TGVhZGVyYm9hcmQ6ZHNzZGFkMTIyMjIyMTJhZA==",
        "name": "name",
        "description": "description",
        "descending": true,
        "resetDay": 1,
        "resetTime": "00:01:01",
        "resetDate": 1,
        "startedAt": "2023-01-22T13:00:00-08:00",
        "expiredAt": "2023-11-22T13:00:00-08:00",
        "timezone": "Asia/Seoul",
        "project_id": "ec8231b2-6b20-4ad1-9c59-8e183087a742",
        "period_type": "weekly",
        "icon_url": "icon_url",
        "user_count": null,
        "updatedAt": "2023-02-01T15:52:24-08:00",
        "createdAt": "2023-02-01T15:52:24-08:00"
    }
}

Succeeded

Attribute Type Required Description
id String O Leaderboard unique ID
projectId String O Project ID
status Boolean O Condition
is_check_user Boolean X Whether to check the user ID
name String X Leaderboard name
description String X Description
icon_url String X Icon URL
descending Boolean X Sort
startedAt String X Start date
expiredAt String X End date (if seasonal)
timezone String X Time zone
period_type String X Cycle (daily, weekly, monthly, season)
resetDay Integer X Reset day 1: Sun, 2: Mon, 3: Tue, 4: Wed, 5: Thu, 6: Fri, 7: Sat (where the periodType is weekly)
resetTime String X Reset time
resetDate Integer X Reset date 1-31 (where the periodType is monthly)
ranking String O Ranking update criteria (latest, accumulated, best)
tie_breaking String O Tie breaker (first, last)

Failure

 "status": -1,
"message": "Error message"
Attribute Type Description
code Int Result \ (1: success, refer to the error code in case of failure )
error String Error message