Individual User on Specific Game¶
This endpoints are for specific users information on specific game + playtype combinations.
This scenario appears frequently, and is typically shortened to UGPT.
Get information about a user's plays on a game + playtype.¶
GET /api/v1/users/:userID/games/:game/:playtype
Parameters¶
None.
Response¶
Property | Type | Description |
---|---|---|
gameStats |
UserGameStatsDocument | The User's GameStats for this game + playtype. |
firstScore |
ScoreDocument or Null | The user's first score for this game + playtype. This is null if the user has no scores with timestamps. |
mostRecentScore |
ScoreDocument or Null | The user's most recent score. This is null if the user has no scores with timestamps. |
totalScores |
Integer | The total amount of scores this user has. |
rankingData |
Record<Rating Algorithm, { ranking: integer, outOf: integer }> | The position of this player on the default leaderboards for this game, and how many players it is out of. |
Example¶
Request¶
GET /api/v1/users/zkrising/games/iidx/SP
Response¶
{
gameStats: {
userID: 1,
game: "iidx",
playtype: "SP",
ratings: {
ktRating: 15
},
classes: {
dan: 14
}
},
firstScore: null,
mostRecentScore: null,
totalScores: 5,
rankingData: {
ktRating: {
ranking: 3,
outOf: 18
}
ktLampRating: {
ranking: 2,
outOf: 18
},
BPI: {
ranking: 5,
outOf: 18
}
}
}
Search a user's personal bests.¶
GET /api/v1/users/:userID/games/:game/:playtype/pbs
Parameters¶
Property | Type | Description |
---|---|---|
search |
String | Limits the returned scores to those where the corresponding song is most similar to this query. |
Response¶
Property | Type | Description |
---|---|---|
songs |
Array<SongDocument> | The array of songs this search returned. |
charts |
Array<ChartDocument> | The array of charts this search returned. |
pbs |
Array<PBDocument> | The array of personal bests this search returned. This is limited to 30 returns. |
Example¶
Request¶
GET /api/v1/users/zkrising/games/iidx/SP/pbs?search=Verfl
Response¶
{
pbs: [{
userID: 1,
scoreData: {
score: 123,
// ...
}
}],
songs: [{
title: "Verflucht",
// ...
}],
charts: [{
songID: 123,
playtype: "SP",
difficulty: "ANOTHER",
// ...
}, {
songID: 123,
playtype: "SP",
difficulty: "HYPER",
}]
}
Get a user's best 100 personal bests.¶
GET /api/v1/users/:userID/games/:game/:playtype/pbs/best
This returns the users' best 100 personal bests according to the Default Rating Algorithm for this game.
This is returned in descending sorted order.
The query parameter alg
can be used to specify a
different rating algorithm to sort under.
Parameters¶
Property | Type | Description |
---|---|---|
alg |
String | An overriding rating algorithm to use instead of the default. |
Response¶
Property | Type | Description |
---|---|---|
songs |
Array<SongDocument> | The array of songs this search returned. |
charts |
Array<ChartDocument> | The array of charts this search returned. |
pbs |
Array<PBDocument> | The array of personal bests this search returned. |
Example¶
Request¶
GET /api/v1/users/zkrising/games/iidx/SP/pbs/best?alg=BPI
Response¶
{
pbs: [{
userID: 1,
scoreData: {
// ...
},
calculatedData: {
ktRating: 15,
BPI: 4.4
}
}, {
userID: 1,
scoreData: {
// ...
},
calculatedData: {
ktRating: 19,
BPI: 4.2
}
}],
songs: [{
title: "Verflucht",
// ...
}, {
title: "AA",
// ...
}],
charts: [{
songID: 123,
playtype: "SP",
difficulty: "ANOTHER",
// ...
}, {
songID: 14,
playtype: "SP",
difficulty: "ANOTHER",
}]
}
Returns all of a users personal bests.¶
GET /api/v1/users/:userID/games/:game/:playtype/pbs/all
Parameters¶
None.
Response¶
Property | Type | Description |
---|---|---|
pbs |
Array<PBDocument> | All of the users PB Documents |
songs |
Array<SongDocument> | All of the relevant songs. |
charts |
Array<ChartDocument> | All of the relevant charts. |
Example¶
Request¶
GET /api/v1/users/zkrising/games/iidx/SP/pbs/all
Response¶
{
pbs: [{
userID: 1,
scoreData: {
score: 123,
// ...
}
}],
songs: [{
title: "Verflucht",
// ...
}],
charts: [{
songID: 123,
playtype: "SP",
difficulty: "ANOTHER",
// ...
}, {
songID: 123,
playtype: "SP",
difficulty: "HYPER",
}]
}
Get A User's PB for a given chart.¶
GET /api/v1/users/:userID/games/:game/:playtype/pbs/:chartID
Parameters¶
Property | Type | Description |
---|---|---|
getComposition |
Presence | If present, the individual ScoreDocuments that composed this PB will also be returned. |
Response¶
Property | Type | Description |
---|---|---|
pb |
PBDocument | The user's PB for this chart. |
chart |
ChartDocument | The chart this PB is on. |
scores (Conditional) |
Array<ScoreDocument> | If getComposition is present, then this field contains the array of score documents that composed this PB. |
Example¶
Request¶
GET /api/v1/users/1/games/iidx/SP/pbs/some_chart_id
Response¶
{
pb: {
chartID: "some_chart_id",
userID: 1,
game: "iidx",
playtype: "SP",
},
chart: {
chartID: "some_chart_id"
}
}
Search a user's individual scores.¶
GET /api/v1/users/:userID/games/:game/:playtype/scores
Parameters¶
Property | Type | Description |
---|---|---|
search |
String | Limits the returned scores to those where the corresponding song is most similar to this query. |
Response¶
Property | Type | Description |
---|---|---|
songs |
Array<SongDocument with __textScore> | The array of songs this search returned. |
charts |
Array<ChartDocument> | The array of charts this search returned. |
scores |
Array<ScoreDocument> | The array of scores this search returned. This is limited to 30 returns. |
Info
All songs
returned also have the __textScore
property. This property describes how close the query
was to the actual text, and is mostly internal.
You can read more into the details of this at Search Implementation
Example¶
Request¶
GET /api/v1/users/zkrising/games/iidx/SP/scores?search=Verfl
Response¶
{
scores: [{
userID: 1,
scoreData: {
score: 123,
// ...
}
}],
songs: [{
title: "Verflucht",
// ...
}],
charts: [{
songID: 123,
playtype: "SP",
difficulty: "ANOTHER",
// ...
}, {
songID: 123,
playtype: "SP",
difficulty: "HYPER",
}]
}
Get a user's most recent 100 scores.¶
GET /api/v1/users/:userID/games/:game/:playtype/scores/recent
Parameters¶
None.
Response¶
Property | Type | Description |
---|---|---|
songs |
Array<SongDocument> | The array of songs this search returned. |
charts |
Array<ChartDocument> | The array of charts this search returned. |
scores |
Array<ScoreDocument> | The array of scores this search returned. This is limited to 30 returns. |
Example¶
Request¶
GET /api/v1/users/zkrising/games/iidx/SP/scores/recent
Response¶
{
scores: [{
userID: 1,
scoreData: {
score: 123,
// ...
}
}],
songs: [{
title: "Verflucht",
// ...
}],
charts: [{
songID: 123,
playtype: "SP",
difficulty: "ANOTHER",
// ...
}, {
songID: 123,
playtype: "SP",
difficulty: "HYPER",
}]
}
Search a user's sessions.¶
GET /api/v1/users/:userID/games/:game/:playtype/sessions
Searches the names of sessions from a given user. This does not search session descriptions, nor does it search song titles of played songs inside sessions.
Parameters¶
Property | Type | Description |
---|---|---|
search |
String | The session name to search for. |
Response¶
Property | Type | Description |
---|---|---|
<body> |
Array<SessionDocument> | The array of sessions that matched this query. |
Example¶
Request¶
GET /api/v1/users/zkrising/games/iidx/SP/sessions?search=epic%20session
Response¶
[
{
name: "My Epic Session!!!",
userID: 1,
game: "iidx",
playtype: "SP",
// ...
}
]
Get a user's best 100 sessions.¶
GET /api/v1/users/:userID/games/:game/:playtype/sessions/best
Retrieves a user's best 100 sessions according to the
game + playtypes default algorithm. The algorithm can
be overrode with the alg
query string parameter.
These are returned in descending order.
Parameters¶
Property | Type | Description |
---|---|---|
alg (Optional) |
String | The name of the algorithm to use instead of the default. |
Response¶
Property | Type | Description |
---|---|---|
<body> |
Array<SessionDocument> | The array of the users best sessions. |
Example¶
Request¶
GET /api/v1/users/zkrising/games/iidx/SP/sessions/best
Response¶
Info
The default rating algorithm for IIDX:SP is ktRating
.
[
{
userID: 1,
game: "iidx",
playtype: "SP",
calculatedData: {
ktRating: 14,
bpi: 3
}
// ... more properties
},
{
userID: 1,
game: "iidx",
playtype: "SP",
calculatedData: {
ktRating: 13.2,
bpi: 4
}
}
]
Get a user's most recent 100 sessions.¶
GET /api/v1/users/:userID/games/:game/:playtype/sessions/recent
Retrieves a user's most recent 100 sessions for this game.
These are returned in descending order according to timeEnded
.
Parameters¶
None.
Response¶
Property | Type | Description |
---|---|---|
<body> |
Array<SessionDocument> | The array of the users sessions. |
Get a user's most recent session.¶
GET /api/v1/users/:userID/games/:game/:playtype/sessions/last
Info
This endpoint will return 404 if the user has never had a session for this game.
Parameters¶
None.
Response¶
Property | Type | Description |
---|---|---|
<body> |
SessionDocument | The user's most recent session. |
Example¶
Request¶
GET /api/v1/users/zkrising/games/iidx/SP/sessions/last
Response¶
{
"name": "foo",
"desc": "My most recent session",
// ...
}
Get a user's most recent 100 highlighted sessions.¶
GET /api/v1/users/:userID/games/:game/:playtype/sessions/highlighted
Retrieves a user's most recent 100 highlighted sessions for this game.
These are returned in descending order according to timeEnded
.
Parameters¶
None.
Response¶
Property | Type | Description |
---|---|---|
<body> |
Array<SessionDocument> | The array of the users highlighted sessions. |
Example¶
Request¶
GET /api/v1/users/zkrising/games/iidx/SP/sessions/highlighted
Response¶
[
{
userID: 1,
game: "iidx",
playtype: "SP",
calculatedData: {
ktRating: 14,
bpi: 3
}
highlight: true,
// ... more props
},
]
Get a user's most played charts.¶
GET /api/v1/users/:userID/games/:game/:playtype/most-played
Parameters¶
None.
Response¶
Property | Type | Description |
---|---|---|
songs |
Array<SongDocument> | The array of songs related to the pbs. |
charts |
Array<ChartDocument> | The array of charts related to the pbs. |
pbs |
Array<(PBDocument & {__playcount: integer})> | An array of PB documents with the __playcount property attached. This property dictates how many times the user has played this chart. |
Example¶
Request¶
GET /api/v1/users/zkrising/games/iidx/SP/most-played
Response¶
{
songs: [{
id: 1,
title: "5.1.1.",
// ...
}, {
id: 2,
title: "GAMBOL",
// ...
}],
charts: [{
songID: 1,
difficulty: "ANOTHER",
// ...
}, {
songID: 2,
difficulty: "LEGGENDARIA",
// ...
}, {
songID: 1,
difficulty: "HYPER",
}],
pbs: [{
chartID: "something",
__playcount: 5,
// ...
}, {
chartID: "something_else",
__playcount: 2,
// ...
}, {
chartID: "something_more",
__playcount: 1,
// ...
}]
}
Retrieve a leaderboard around a user.¶
GET /api/v1/users/:userID/games/:game/:playtype/leaderboard-adjacent
Parameters¶
Property | Type | Description |
---|---|---|
alg |
String (Optional) | Optionally, you can provide an override algorithm to use for the leaderboards instead of the game+playtype default. |
Response¶
Property | Type | Description |
---|---|---|
above |
Array<UserGameStats> | Up to 5 users' game stats better than this user. |
below |
Array<UserGameStats> | Same as above, but below the user. |
users |
Array<UserDocument> | The user documents related to the above statistics. |
thisUsersStats |
UserGameStats | The requested user's stats for this GPT. |
thisUsersRanking |
{outOf: integer, ranking: integer} | The requested user's ranking for this GPT. |
Example¶
Request¶
GET /api/v1/users/zkrising/games/iidx/SP/leaderboard-adjacent
Response¶
{
above: [{
userID: 2,
ratings: {
ktRating: 9
},
classes: {
dan: 10
},
// ...
}],
below: [{
userID: 3,
ratings: {
ktRating: 1
},
classes: {
dan: 5
},
// ...
}],
users: [{
userID: 2,
username: "sptmgtm",
// ...
}, {
userID: 3,
username: "neil.c",
// ...
}],
thisUsersStats: {
userID: 1,
ratings: {
ktRating: 5
},
classes: {
dan: 5
}
},
thisUsersRanking: {
ranking: 2,
outOf: 3
}
}
Retrieve this user's GPT stat history.¶
GET /api/v1/users/:userID/games/:game/:playtype/history
Every day, a user's game stats are snapshotted and saved. This returns the recent ones.
Parameters¶
None.
Response¶
Property | Type | Description |
---|---|---|
<body> |
Array<UserGameStatsSnapshot> | The most recent (up to) 90 UGS Snapshots, where the first element is the most recent one, and the last is the oldest. |
Example¶
Request¶
GET /api/v1/users/1/games/iidx/SP/history
Response¶
[
{
classes: {
dan: 13,
},
ratings: {
BPI: 5,
ktRating: 3,
ktLampRating: 1,
},
timestamp: 12312323123123, // most recent
playcount: 500,
ranking: 14
},
// and so on..
]
Retrieve this user's GPT settings.¶
GET /api/v1/users/:userID/games/:game/:playtype/settings
Warning
Unlike most other applications, your settings are completely public. GPT Settings only concern cosmetic things, like what rating algorithms to prefer.
Parameters¶
None.
Response¶
Property | Type | Description |
---|---|---|
<body> |
UGPTSettingsDocument | The settings document for this user. |
Example¶
Request¶
GET /api/v1/users/1/games/iidx/SP/settings
Response¶
{
preferredScoreAlg: null,
preferredSessionAlg: "BPI",
preferredProfileAlg: null,
stats: []
}
Modify your UGPT settings.¶
PATCH /api/v1/users/:userID/games/:game/:playtype/settings
Note
Although stats
are part of your settings, they are not modifiable under these endpoints,
instead you should use UGPT Showcase Endpoints.
Permissions¶
customise_profile
Parameters¶
Property | Type | Description |
---|---|---|
<body> |
Partial UGPTSettingsDocument | A UGPTSettingsDocument where all properties are optional. Properties not present will not be modified. Note that stats are not modifiable here. |
Response¶
Property | Type | Description |
---|---|---|
<body> |
UGPTSettingsDocument | The new UGPTSettingsDocument. |
Example¶
Request¶
PATCH /api/v1/users/1/games/iidx/SP/settings
{
preferredScoreAlg: "BPI"
}
Response¶
{
preferredScoreAlg: "BPI",
preferredSessionAlg: "ktRating",
preferredProfileAlg: null,
stats: []
}