zkldi_Tachi/docs/docs/api/routes/gpt.md

Game:Playtype Endpoints

These endpoints are for games + their playtypes. To find out what games are supported by a service programmatically, you should see Game Endpoints.

---

Retrieve Game:Playtype Configuration.

GET /api/v1/games/:game/:playtype

Parameters

None.

Response

| Property | Type | Description | | :: | :: | :: | | config | GamePTConfig | The configuration file for this game + playtype. |

!!! warning A GamePTConfig is different to a GameConfig! Read more here.

Example

Request

GET /api/v1/games/iidx/SP

Response

{
	"config": {
		"idString": "iidx:SP",

		"percentMax": 100,

		"defaultScoreRatingAlg": "ktRating",
		"defaultSessionRatingAlg": "ktRating",
		"defaultProfileRatingAlg": "ktRating",

		// ... more props - a lot more props
	}
}

---

Retrieve the player leaderboard.

GET /api/v1/games/:game/:playtype/leaderboard

Parameters

| Property | Type | Description | | :: | :: | :: | | alg (Optional) | String | If present, specifies an alternative algorithm to sort players on, instead of the default. |

Response

| Property | Type | Description | | :: | :: | :: | | gameStats | Array<GameStats> | The sorted statistics for the leaderboards. | | users | Array<UserDocument> | All of the related users for the above statistics. |

Example

Request

GET /api/v1/games/iidx/SP/leaderboard

Response

{
	"gameStats": [{
		"userID": 1,
		"ratings": {
			"ktRating": 4,
			// ...
		}
		// ...
	}],
	"users": [{
		"id": 1,
		"username": "zkldi"
	}]
}

---

Retrieve a song and its charts.

GET /api/v1/games/:game/:playtype/songs/:songID

Parameters

None.

Response

| Property | Type | Description | | :: | :: | :: | | song | SongDocument |The requested song document. | | charts | ChartDocument[] | All of the charts that belong to this song for this playtype. |

Example

Request

GET /api/v1/games/iidx/SP/songs/1

Response

{
	"song": {
		"id": 1,
		"title": "5.1.1."
	},
	"charts": [{
		"songID": 1,
		"playtype": "SP",
		"difficulty": "HYPER",
		// ...
	}, {
		"songID": 1,
		"playtype": "SP",
		"difficulty": "ANOTHER",
		// ...
	}]
}

---

Get popular charts for this game + playtype.

GET /api/v1/games/:game/:playtype/charts

Parameters

| Property | Type | Description | | :: | :: | :: | | search (Optional) | String | A song title to search for. |

!!! note If no search parameter is set, then the most popular 100 charts for this game are returned.

If a search parameter is set, then the most popular
charts that match the search criteria will be returned,
in that order.

Response

| Property | Type | Description | | :: | :: | :: | | charts | Array<ChartDocument with __playcount> | The chart documents that matched this search, or the most popular 100 charts for this game. | | songs | Array<SongDocument> | The associated song documents for the charts. |

!!! info The __playcount property is patched onto the chart documents returned. This indicates the amount of unique players that have played this chart.

Example

Request

GET /api/v1/games/iidx/SP/charts?search=AA

Response

{
	"songs": [{
		"title": "AA",
		"id": 3,
		// ...
	}, {
		"title": "AA -rebuild-",
		"id": 133,
		// ...
	}],
	"charts": [{
		"songID": 3,
		"difficulty": "ANOTHER",
		"__playcount": 1049,
		// ...
	}, {
		"songID": 133,
		"difficulty": "ANOTHER",
		"__playcount": 120
	},
		//...
	]
}

---

Retrieve a chart at a specific ID.

GET /api/v1/games/:game/:playtype/charts/:chartID

Parameters

None.

Response

| Property | Type | Description | | :: | :: | :: | | song | SongDocument | The parent song for this chart. | | chart | ChartDocument | The requested chart document. |

Example

Request

GET /api/v1/games/iidx/SP/charts/some_chart_id

Response

{
	"song": {
		"id": 123,
		"title": "BLOCKS",
		// ...
	},
	"chart": {
		"chartID": "some_chart_id",
		"songID": 123,
		"playtype": "SP",
		// ...
	}
}

---

Retrieve playcount for this chart.

GET /api/v1/games/:game/:playtype/charts/:chartID/playcount

Parameters

None.

Response

| Property | Type | Description | | :: | :: | :: | | count | Integer | The amount of plays on this chart. |

Example

Self-explanatory.

---

Retrieve leaderboards for this chart.

GET /api/v1/games/:game/:playtype/charts/:chartID/pbs

Parameters

| Property | Type | Description | | :: | :: | :: | | startRanking (Optional) | Specify a start point to return 100 pbs from. Defaults to 1. Inclusive. |

Response

| Property | Type | Description | | :: | :: | :: | | pbs | Array<PBDocument> | The array of pbs sorted by ranking. | | users | The users these PBs belong to. |

Example

Request

GET /api/v1/games/iidx/SP/charts/some_chart/pbs

Response

{
	"pbs": [{
		"chartID": "some_chart",
		"userID": 1,
		"rankingData": {
			"rank": 1,
			"outOf": 100,
		},
		// ...
	}, 
		//...
	],
	"users": [{
		"id": 1,
		"username": "zkldi",
		// ...
	},
		// ...
	]
}

---

Search for a user's PB on this chart.

GET /api/v1/games/:game/:playtype/charts/:chartID/pbs/search

Parameters

| Property | Type | Description | | :: | :: | :: | | search | String | The user whose PB you're searching for. |

Response

Same as /api/v1/games/:game/:playtype/charts/:chartID/pbs.

Example

See Above.

---

Search a GPT's folders.

GET /api/v1/games/:game/:playtype/folders

Parameters

| Property | Type | Description | | :: | :: | :: | | search | String | A string to search for a given folder. |

Response

| Property | Type | Description | | :: | :: | :: | | <body> | Array<FolderDocument> | The folders that matched this search. |

Example

Request

GET /api/v1/games/iidx/SP/folders?search=12

Response

[{
	name: "beatmania IIDX Level 12",
	// ...
}]

---

Retrieve information on a specific folderID

GET /api/v1/games/:game/:playtype/folders/:folderID

Parameters

None.

Response

| Property | Type | Description | | :: | :: | :: | | songs | Array<SongDocument> | The related song documents for this folder. | | charts | Array<ChartDocument> | The related chart documents for this folder. | | folder | FolderDocument | The folder document at this ID. |

Example

Request

GET /api/v1/games/iidx/SP/folders/some_folder_id

Response

{
	songs: [{
		id: 123,
		title: "Epic Song",
		artist: "foo bar",
		// ...
	}],
	charts: [{
		chartID: "foo_bar",
		songID: 123,
		difficulty: "ANOTHER",
		// ...
	}],
	folder: {
		name: "beatmania IIDX Level 12",
		folderID: "some_folder_id",
		// ...
	}
}

---

Return all the tables for this game

GET /api/v1/games/:game/:playtype/tables

!!! note Unlike the folders endpoint, this one doesn't have a search parameter. This is because we expect the total table count to stay rather small.

If this changes in the future, this might become a paginated search like endpoint.

Parameters

None.

Response

| Property | Type | Description | | :: | :: | :: | | tables | Array<TableDocument> | Every table for this GPT. |

Example

Request

GET /api/v1/games/bms/7K/tables

Response

{
	tables: [
		{
			name: "Insane",
			// ...
		}, {
			name: "Overjoy",
			// ...
		}
	]
}

---

Retrieve folder documents for a specific table.

GET /api/v1/games/:game/:playtype/tables/:tableID

Parameters

None.

Response

| Property | Type | Description | | :: | :: | :: | | folders | Array<FolderDocument> | All of the folders for this table. | | table | TableDocument | The table document at this ID. |

Example

Request

GET /api/v1/games/bms/7K/tableID/insane

Response

{
	folders: [
		// insane lv1, insane lv2 -- insane lv 25, so on.
	],
	table: {
		tableID: "insane",
		name: "Insane",
		// ...
	}
}

---

Retrieve the PB leaderboard for this Game.

GET /api/v1/games/:game/:playtype/pb-leaderboard

Parameters

| Property | Type | Description | | :: | :: | :: | | alg | String | An alternative algorithm to use instead of the GPTs default. | | limit | Optional Integer | Optionally, provide a number between 1 and 50 to change the amount of scores returned. |

Response

| Property | Type | Description | | :: | :: | :: | | pbs | Array<PBDocument> | The array of pbs part of the PB leaderboard. | | songs | Array<SongDocument> | The array of songs part of the PBs. | | charts | Array<ChartDocument> | The array of charts part of the PBs. | | users | Array<UserDocument> | The array of users part of the PBs. |

---

Get the distribution of players for a provided class.

GET /api/v1/games/:game/:playtype/player-distribution

Parameters

| Property | Type | Description | | :: | :: | :: | | class | String | Must be one of the GPTs supported classes, This specifies what distribution to return. |

Response

| Property | Type | Description | | :: | :: | :: | | <body> | Record<ClassValue, integer> | Returns a record of the class value against the amount of people who have it. |

Example

Request

GET /api/v1/games/bms/7K/player-distribution?class=stslDan

Response

{
	"12": 1,
	"11": 5,
	"10": 7,
	"9": 6,
	"8": 4,
	// Note that keys will be empty if nobody has them.
	"5": 30,
	// ... so on
}

!!! info You can find the humanised conversions for these classes in the gptConfig for this GPT.

See [tachi/common](https://github.com/TNG-dev/Tachi/tree/staging/common) for more information.

---

Retrieve recent class updates from all users on this game.

GET /api/v1/games/:game/:playtype/player-distribution

Parameters

| Property | Type | Description | | :: | :: | :: | | limit | Optional Integer | Optionally, An integer between 1 and 50 can be provided to limit the amount of returns. Defaults to 10. |

Response

| Property | Type | Description | | :: | :: | :: | | users | Array<UserDocument> | Array of the users who achieved the courses. | | classes | Array<ClassAchievementDocument> | Data about the recently achieved classes. |

---

Retrieve the most recent highlighted scores for this GPT.

GET /api/v1/games/:game/:playtype/scores/highlighted

Parameters

| Property | Type | Description | | :: | :: | :: | | limit | Optional Integer | Optionally, provide an integer between 1 and 100 to return this amount of scores. Defaults to 100. |

Response

| Property | Type | Description | | :: | :: | :: | | scores | Array<ScoreDocument> | The highlighted scores. | | users | Array<UserDocument> | The users who own the scores. | | songs | Array<SongDocument> | The songs the scores are on. | | charts | Array<ChartDocument> | The charts the scores are on. |