Stats APIs Documentation

The StatsController handles logging and retrieving play statistics, including track plays, skips, ratings, listening times, and more.

Controller Route: `/api/stats`

All routes within the StatsController are prefixed by /api/stats.

Summary of Endpoints

Endpoint	Method	Description	Authorization
`/api/stats/log-play`	POST	Logs a track play for the current user.	Admin, User
`/api/stats/log-skip`	POST	Logs a track skip for the current user.	Admin, User
`/api/stats/listening-time`	GET	Retrieves total listening time for a user.	Admin, User, Pass
`/api/stats/top-tracks`	GET	Retrieves the top tracks for a user.	Admin, User, Pass
`/api/stats/top-albums`	GET	Retrieves the top albums for a user.	Admin, User, Pass
`/api/stats/top-artists`	GET	Retrieves the top artists for a user.	Admin, User, Pass
`/api/stats/top-genres`	GET	Retrieves the top genres for a user.	Admin, User, Pass
`/api/stats/recent-tracks`	GET	Retrieves recent tracks played by the user.	Admin, User, Pass
`/api/stats/recent-albums`	GET	Retrieves recent albums played by the user.	Admin, User, Pass
`/api/stats/recent-artists`	GET	Retrieves recent artists played by the user.	Admin, User, Pass
`/api/stats/rate-track`	POST	Allows users to rate a track.	Admin, User
`/api/stats/rate-album`	POST	Allows users to rate an album.	Admin, User
`/api/stats/rate-artist`	POST	Allows users to rate an artist.	Admin, User

Log Play

Logs a track play event and updates the play statistics for the track, album, and associated artists.

Details:

Endpoint: /api/stats/log-play
Method: POST
Authorization: JWT (Roles: Admin, User)

Parameters:

id (string, required): The ID of the track being played.
device (string, optional): The device used to play the track.
dateTime (string, optional): The date and time the track was played (ISO format).

Responses:

200 OK: Returns success if the play event is logged.
404 Not Found: If the track is not found.
400 Bad Request: If the date format is invalid.

Example Request:

curl -X POST "https://your-api-url.com/api/stats/log-play?id=66bc99b8ab7ba419497e21af&device=mobile" \
             -H "Authorization: Bearer <JWT-token>" \
             -H "Content-Type: application/json"

Log Skip

Logs a track skip event for a user.

Details:

Endpoint: /api/stats/log-skip
Method: POST
Authorization: JWT (Roles: Admin, User)

Parameters:

id (string, required): The ID of the track being skipped.
device (string, optional): The device used to skip the track.
dateTime (string, optional): The date and time of the skip (ISO format).

Responses:

200 OK: Returns success if the skip event is logged.
404 Not Found: If the track is not found.
400 Bad Request: If the date format is invalid.

Example Request:

curl -X POST "https://your-api-url.com/api/stats/log-skip?id=66bc99b8ab7ba419497e21af&device=mobile" \
             -H "Authorization: Bearer <JWT-token>" \
             -H "Content-Type: application/json"

Get Listening Time

Retrieves the total listening time for a user.

Details:

Endpoint: /api/stats/listening-time
Method: GET
Authorization: JWT (Roles: Admin, User, Pass)

Parameters:

userId (string, optional): The ID of the user (defaults to the current user).
ltDateTime (string, optional): Filters logs before this date.
gtDateTime (string, optional): Filters logs after this date.
page (int, optional): The page of results (default is 0).
count (int, optional): The number of results per page (default is 100).

Responses:

200 OK: Returns the total listening time for the user.
404 Not Found: If the user is not found.

Example Request:

curl -X GET "https://your-api-url.com/api/stats/listening-time?userId=66bc99b8ab7ba419497e21af&ltDateTime=2023-01-01&gtDateTime=2022-01-01" \
             -H "Authorization: Bearer <JWT-token>"

Get Top Tracks

Retrieves the top played tracks for a user within a given timeframe.

Details:

Endpoint: /api/stats/top-tracks
Method: GET
Authorization: JWT (Roles: Admin, User, Pass)

Parameters:

userId (string, optional): The ID of the user (defaults to the current user).
ltDateTime (string, optional): Filters logs before this date.
gtDateTime (string, optional): Filters logs after this date.
device (string, optional): Filters logs by device.
page (int, optional): The page of results (default is 0).
count (int, optional): The number of results per page (default is 100).

Responses:

200 OK: Returns the list of top tracks.
404 Not Found: If the user is not found.

Example Request:

curl -X GET "https://your-api-url.com/api/stats/top-tracks?userId=66bc99b8ab7ba419497e21af&page=0&count=10" \
             -H "Authorization: Bearer <JWT-token>"

Get Top Albums

Retrieves the top played albums for a user within a given timeframe.

Details:

Endpoint: /api/stats/top-albums
Method: GET
Authorization: JWT (Roles: Admin, User, Pass)

Parameters:

userId (string, optional): The ID of the user (defaults to the current user).
ltDateTime (string, optional): Filters logs before this date.
gtDateTime (string, optional): Filters logs after this date.
device (string, optional): Filters logs by device.
page (int, optional): The page of results (default is 0).
count (int, optional): The number of results per page (default is 100).

Responses:

200 OK: Returns the list of top albums.
404 Not Found: If the user is not found.

Example Request:

curl -X GET "https://your-api-url.com/api/stats/top-albums?userId=66bc99b8ab7ba419497e21af&page=0&count=10" \
             -H "Authorization: Bearer <JWT-token>"

Get Top Artists

Retrieves the top played artists for a user within a given timeframe.

Details:

Endpoint: /api/stats/top-artists
Method: GET
Authorization: JWT (Roles: Admin, User, Pass)

Parameters:

userId (string, optional): The ID of the user (defaults to the current user).
ltDateTime (string, optional): Filters logs before this date.
gtDateTime (string, optional): Filters logs after this date.
device (string, optional): Filters logs by device.
page (int, optional): The page of results (default is 0).
count (int, optional): The number of results per page (default is 100).

Responses:

200 OK: Returns the list of top artists.
404 Not Found: If the user is not found.

Example Request:

curl -X GET "https://your-api-url.com/api/stats/top-artists?userId=66bc99b8ab7ba419497e21af&page=0&count=10" \
             -H "Authorization: Bearer <JWT-token>"

Get Top Genres

Retrieves the top played genres for a user within a given timeframe.

Details:

Endpoint: /api/stats/top-genres
Method: GET
Authorization: JWT (Roles: Admin, User, Pass)

Parameters:

userId (string, optional): The ID of the

user (defaults to the current user).
ltDateTime (string, optional): Filters logs before this date.
gtDateTime (string, optional): Filters logs after this date.
device (string, optional): Filters logs by device.
page (int, optional): The page of results (default is 0).
count (int, optional): The number of results per page (default is 100).

Responses:

200 OK: Returns the list of top genres.
404 Not Found: If the user is not found.

Example Request:

curl -X GET "https://your-api-url.com/api/stats/top-genres?userId=66bc99b8ab7ba419497e21af&page=0&count=10" \
             -H "Authorization: Bearer <JWT-token>"

Get Recent Tracks

Retrieves a list of recently played tracks for a user.

Details:

Endpoint: /api/stats/recent-tracks
Method: GET
Authorization: JWT (Roles: Admin, User, Pass)

Parameters:

userId (string, optional): The ID of the user (defaults to the current user).
device (string, optional): Filters logs by device.
page (int, optional): The page of results (default is 0).
count (int, optional): The number of results per page (default is 100).

Responses:

200 OK: Returns a list of recent tracks played by the user.
404 Not Found: If the user is not found.

Example Request:

curl -X GET "https://your-api-url.com/api/stats/recent-tracks?userId=66bc99b8ab7ba419497e21af&device=mobile&page=0&count=10" \
             -H "Authorization: Bearer <JWT-token>"

Get Recent Albums

Retrieves a list of recently played albums for a user.

Details:

Endpoint: /api/stats/recent-albums
Method: GET
Authorization: JWT (Roles: Admin, User, Pass)

Parameters:

userId (string, optional): The ID of the user (defaults to the current user).
device (string, optional): Filters logs by device.
page (int, optional): The page of results (default is 0).
count (int, optional): The number of results per page (default is 100).

Responses:

200 OK: Returns a list of recent albums played by the user.
404 Not Found: If the user is not found.

Example Request:

curl -X GET "https://your-api-url.com/api/stats/recent-albums?userId=66bc99b8ab7ba419497e21af&device=mobile&page=0&count=10" \
             -H "Authorization: Bearer <JWT-token>"

Get Recent Artists

Retrieves a list of recently played artists for a user.

Details:

Endpoint: /api/stats/recent-artists
Method: GET
Authorization: JWT (Roles: Admin, User, Pass)

Parameters:

userId (string, optional): The ID of the user (defaults to the current user).
device (string, optional): Filters logs by device.
page (int, optional): The page of results (default is 0).
count (int, optional): The number of results per page (default is 100).

Responses:

200 OK: Returns a list of recent artists played by the user.
404 Not Found: If the user is not found.

Example Request:

curl -X GET "https://your-api-url.com/api/stats/recent-artists?userId=66bc99b8ab7ba419497e21af&device=mobile&page=0&count=10" \
             -H "Authorization: Bearer <JWT-token>"

Rate Track

Allows a user to rate a track.

Details:

Endpoint: /api/stats/rate-track
Method: POST
Authorization: JWT (Roles: Admin, User)

Parameters:

id (string, required): The ID of the track.
rating (long, required): The rating value for the track.

Responses:

200 OK: Returns success if the rating is saved.
404 Not Found: If the track is not found.

Example Request:

curl -X POST "https://your-api-url.com/api/stats/rate-track?id=66bc99b8ab7ba419497e21af&rating=5" \
             -H "Authorization: Bearer <JWT-token>" \
             -H "Content-Type: application/json"

Rate Album

Allows a user to rate an album.

Details:

Endpoint: /api/stats/rate-album
Method: POST
Authorization: JWT (Roles: Admin, User)

Parameters:

id (string, required): The ID of the album.
rating (long, required): The rating value for the album.

Responses:

200 OK: Returns success if the rating is saved.
404 Not Found: If the album is not found.

Example Request:

curl -X POST "https://your-api-url.com/api/stats/rate-album?id=66bc99b8ab7ba419497e21af&rating=5" \
             -H "Authorization: Bearer <JWT-token>" \
             -H "Content-Type: application/json"

Rate Artist

Allows a user to rate an artist.

Details:

Endpoint: /api/stats/rate-artist
Method: POST
Authorization: JWT (Roles: Admin, User)

Parameters:

id (string, required): The ID of the artist.
rating (long, required): The rating value for the artist.

Responses:

200 OK: Returns success if the rating is saved.
404 Not Found: If the artist is not found.

Example Request:

curl -X POST "https://your-api-url.com/api/stats/rate-artist?id=66bc99b8ab7ba419497e21af&rating=5" \
             -H "Authorization: Bearer <JWT-token>" \
             -H "Content-Type: application/json"

Stats APIs Documentation

Controller Route: /api/stats

Summary of Endpoints

Log Play

Log Skip

Get Listening Time

Get Top Tracks

Get Top Albums

Get Top Artists

Get Top Genres

Get Recent Tracks

Get Recent Albums

Get Recent Artists

Rate Track

Rate Album

Rate Artist

Controller Route: `/api/stats`