zkldi_Tachi/old-docs/docs/api/routes/user-gamept.md

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/:gameGroup/: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/zkldi/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/:gameGroup/: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/zkldimes/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/:gameGroup/: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/zkldimes/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/:gameGroup/: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/zkldimes/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/:gameGroup/: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/:gameGroup/: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](../../codebase/implementation-details/search.md)

Example

Request

GET /api/v1/users/zkldimes/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/:gameGroup/: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/zkldimes/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/:gameGroup/: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/zkldimes/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/:gameGroup/: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/zkldimes/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/:gameGroup/: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/:gameGroup/: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/zkldimes/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/:gameGroup/: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/zkldimes/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/:gameGroup/: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/zkldimes/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/:gameGroup/: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/zkldimes/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/:gameGroup/: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/:gameGroup/: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/:gameGroup/: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: []
}