zkldi_Tachi/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/: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/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
		}
	}
}

---

Retrieve a user's goals for this game + playtype.

GET /api/v1/users/:userID/games/:game/:playtype/goals

Parameters

| Property | Type | Description | | :: | :: | :: | | unachieved (Optional) | Presence | If present, only unachieved goals are returned. |

Response

| Property | Type | Description | | :: | :: | :: | | userGoals | Array<UserGoalDocument> | The array of user-subscriptions to goals this user has. | | goals | Array<GoalDocument> | The array of goal documents this user has a subscription to. |

Example

Request

GET /api/v1/users/zkldi/games/iidx/SP/goals

Response

{
	userGoals: [
		{
			userID: 1,
			goalID: "foobar",
			progress: 4,
			progressHuman: "CLEAR",
			outOf: 5,
			outOfHuman: "HARD CLEAR",
			// ... so on
		}
	],
	goals: [
		{
			goalID: "foobar",
			title: "Hard Clear 5.1.1. SP ANOTHER",
			// ... so on
		}
	]
}

---

Retrieve a user's milestones for this game + playtype.

GET /api/v1/users/:userID/games/:game/:playtype/milestones

Parameters

| Property | Type | Description | | :: | :: | :: | | unachieved (Optional) | Presence | If present, only unachieved milestones are returned. |

Response

| Property | Type | Description | | :: | :: | :: | | userMilestones | Array<UserMilestoneDocument> | The array of user-subscriptions to milestones this user has. | | milestones | Array<MilestoneDocument> | The array of milestone documents this user has a subscription to. |

Example

Request

GET /api/v1/users/zkldi/games/iidx/SP/milestones

Response

{
	userMilestones: [
		{
			userID: 1,
			milestoneID: "foobar",
			// ... so on
		}
	],
	milestones: [
		{
			milestoneID: "foobar",
			title: "IIDX SP 9th Dan Milestone",
			// ... so on
		}
	]
}

---

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/zkldi/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/zkldi/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",
	}]
}

---

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](../../tachi-server/implementation-details/search.md)

Example

Request

GET /api/v1/users/zkldi/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/zkldi/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/zkldi/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/zkldi/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 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/zkldi/games/iidx/SP/sessions/highlighted

Response

[
	{
		userID: 1,
		game: "iidx",
		playtype: "SP",
		calculatedData: {
			ktRating: 14,
			bpi: 3
		}
		highlight: true
	},
]

---

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/zkldi/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/zkldi/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

!!! warn 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: []
}