Spotify.NET/SpotifyAPI/Web/SpotifyWebBuilder.cs
2017-05-31 17:31:41 +02:00

993 lines
48 KiB
C#
Raw Permalink Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using SpotifyAPI.Web.Enums;
using SpotifyAPI.Web.Models;
namespace SpotifyAPI.Web
{
/// <summary>
/// SpotifyAPI URL-Generator
/// </summary>
public class SpotifyWebBuilder
{
public const string APIBase = "https://api.spotify.com/v1";
#region Search
/// <summary>
/// Get Spotify catalog information about artists, albums, tracks or playlists that match a keyword string.
/// </summary>
/// <param name="q">The search query's keywords (and optional field filters and operators), for example q=roadhouse+blues.</param>
/// <param name="type">A list of item types to search across.</param>
/// <param name="limit">The maximum number of items to return. Default: 20. Minimum: 1. Maximum: 50.</param>
/// <param name="offset">The index of the first result to return. Default: 0</param>
/// <param name="market">An ISO 3166-1 alpha-2 country code or the string from_token.</param>
/// <returns></returns>
public string SearchItems(string q, SearchType type, int limit = 20, int offset = 0, string market = "")
{
limit = Math.Min(50, limit);
StringBuilder builder = new StringBuilder(APIBase + "/search");
builder.Append("?q=" + q);
builder.Append("&type=" + type.GetStringAttribute(","));
builder.Append("&limit=" + limit);
builder.Append("&offset=" + offset);
if (!string.IsNullOrEmpty(market))
builder.Append("&market=" + market);
return builder.ToString();
}
#endregion Search
#region Albums
/// <summary>
/// Get Spotify catalog information about an albums tracks. Optional parameters can be used to limit the number of
/// tracks returned.
/// </summary>
/// <param name="id">The Spotify ID for the album.</param>
/// <param name="limit">The maximum number of items to return. Default: 20. Minimum: 1. Maximum: 50.</param>
/// <param name="offset">The index of the first track to return. Default: 0 (the first object).</param>
/// <param name="market">An ISO 3166-1 alpha-2 country code. Provide this parameter if you want to apply Track Relinking.</param>
/// <returns></returns>
public string GetAlbumTracks(string id, int limit = 20, int offset = 0, string market = "")
{
limit = Math.Min(limit, 50);
StringBuilder builder = new StringBuilder(APIBase + "/albums/" + id + "/tracks");
builder.Append("?limit=" + limit);
builder.Append("&offset=" + offset);
if (!string.IsNullOrEmpty(market))
builder.Append("&market=" + market);
return builder.ToString();
}
/// <summary>
/// Get Spotify catalog information for a single album.
/// </summary>
/// <param name="id">The Spotify ID for the album.</param>
/// <param name="market">An ISO 3166-1 alpha-2 country code. Provide this parameter if you want to apply Track Relinking.</param>
/// <returns></returns>
public string GetAlbum(string id, string market = "")
{
if (string.IsNullOrEmpty(market))
return $"{APIBase}/albums/{id}";
return $"{APIBase}/albums/{id}?market={market}";
}
/// <summary>
/// Get Spotify catalog information for multiple albums identified by their Spotify IDs.
/// </summary>
/// <param name="ids">A list of the Spotify IDs for the albums. Maximum: 20 IDs.</param>
/// <param name="market">An ISO 3166-1 alpha-2 country code. Provide this parameter if you want to apply Track Relinking.</param>
/// <returns></returns>
public string GetSeveralAlbums(List<string> ids, string market = "")
{
if (string.IsNullOrEmpty(market))
return $"{APIBase}/albums?ids={string.Join(",", ids.Take(20))}";
return $"{APIBase}/albums?market={market}&ids={string.Join(",", ids.Take(20))}";
}
#endregion Albums
#region Artists
/// <summary>
/// Get Spotify catalog information for a single artist identified by their unique Spotify ID.
/// </summary>
/// <param name="id">The Spotify ID for the artist.</param>
/// <returns></returns>
public string GetArtist(string id)
{
return $"{APIBase}/artists/{id}";
}
/// <summary>
/// Get Spotify catalog information about artists similar to a given artist. Similarity is based on analysis of the
/// Spotify communitys listening history.
/// </summary>
/// <param name="id">The Spotify ID for the artist.</param>
/// <returns></returns>
public string GetRelatedArtists(string id)
{
return $"{APIBase}/artists/{id}/related-artists";
}
/// <summary>
/// Get Spotify catalog information about an artists top tracks by country.
/// </summary>
/// <param name="id">The Spotify ID for the artist.</param>
/// <param name="country">The country: an ISO 3166-1 alpha-2 country code.</param>
/// <returns></returns>
public string GetArtistsTopTracks(string id, string country)
{
return $"{APIBase}/artists/{id}/top-tracks?country={country}";
}
/// <summary>
/// Get Spotify catalog information about an artists albums. Optional parameters can be specified in the query string
/// to filter and sort the response.
/// </summary>
/// <param name="id">The Spotify ID for the artist.</param>
/// <param name="type">
/// A list of keywords that will be used to filter the response. If not supplied, all album types will
/// be returned
/// </param>
/// <param name="limit">The maximum number of items to return. Default: 20. Minimum: 1. Maximum: 50.</param>
/// <param name="offset">The index of the first album to return. Default: 0</param>
/// <param name="market">
/// An ISO 3166-1 alpha-2 country code. Supply this parameter to limit the response to one particular
/// geographical market
/// </param>
/// <returns></returns>
public string GetArtistsAlbums(string id, AlbumType type = AlbumType.All, int limit = 20, int offset = 0, string market = "")
{
limit = Math.Min(limit, 50);
StringBuilder builder = new StringBuilder(APIBase + "/artists/" + id + "/albums");
builder.Append("?album_type=" + type.GetStringAttribute(","));
builder.Append("&limit=" + limit);
builder.Append("&offset=" + offset);
if (!string.IsNullOrEmpty(market))
builder.Append("&market=" + market);
return builder.ToString();
}
/// <summary>
/// Get Spotify catalog information for several artists based on their Spotify IDs.
/// </summary>
/// <param name="ids">A list of the Spotify IDs for the artists. Maximum: 50 IDs.</param>
/// <returns></returns>
public string GetSeveralArtists(List<string> ids)
{
return $"{APIBase}/artists?ids={string.Join(",", ids.Take(50))}";
}
#endregion Artists
#region Browse
/// <summary>
/// Get a list of Spotify featured playlists (shown, for example, on a Spotify players “Browse” tab).
/// </summary>
/// <param name="locale">
/// The desired language, consisting of a lowercase ISO 639 language code and an uppercase ISO 3166-1
/// alpha-2 country code, joined by an underscore.
/// </param>
/// <param name="country">A country: an ISO 3166-1 alpha-2 country code.</param>
/// <param name="timestamp">A timestamp in ISO 8601 format</param>
/// <param name="limit">The maximum number of items to return. Default: 20. Minimum: 1. Maximum: 50.</param>
/// <param name="offset">The index of the first item to return. Default: 0</param>
/// <remarks>AUTH NEEDED</remarks>
public string GetFeaturedPlaylists(string locale = "", string country = "", DateTime timestamp = default(DateTime), int limit = 20, int offset = 0)
{
limit = Math.Min(limit, 50);
StringBuilder builder = new StringBuilder(APIBase + "/browse/featured-playlists");
builder.Append("?limit=" + limit);
builder.Append("&offset=" + offset);
if (!string.IsNullOrEmpty(locale))
builder.Append("&locale=" + locale);
if (!string.IsNullOrEmpty(country))
builder.Append("&country=" + country);
if (timestamp != default(DateTime))
builder.Append("&timestamp=" + timestamp.ToString("yyyy-MM-ddTHH:mm:ss"));
return builder.ToString();
}
/// <summary>
/// Get a list of new album releases featured in Spotify (shown, for example, on a Spotify players “Browse” tab).
/// </summary>
/// <param name="country">A country: an ISO 3166-1 alpha-2 country code.</param>
/// <param name="limit">The maximum number of items to return. Default: 20. Minimum: 1. Maximum: 50.</param>
/// <param name="offset">The index of the first item to return. Default: 0</param>
/// <returns></returns>
/// <remarks>AUTH NEEDED</remarks>
public string GetNewAlbumReleases(string country = "", int limit = 20, int offset = 0)
{
limit = Math.Min(limit, 50);
StringBuilder builder = new StringBuilder(APIBase + "/browse/new-releases");
builder.Append("?limit=" + limit);
builder.Append("&offset=" + offset);
if (!string.IsNullOrEmpty(country))
builder.Append("&country=" + country);
return builder.ToString();
}
/// <summary>
/// Get a list of categories used to tag items in Spotify (on, for example, the Spotify players “Browse” tab).
/// </summary>
/// <param name="country">
/// A country: an ISO 3166-1 alpha-2 country code. Provide this parameter if you want to narrow the
/// list of returned categories to those relevant to a particular country
/// </param>
/// <param name="locale">
/// The desired language, consisting of an ISO 639 language code and an ISO 3166-1 alpha-2 country
/// code, joined by an underscore
/// </param>
/// <param name="limit">The maximum number of categories to return. Default: 20. Minimum: 1. Maximum: 50. </param>
/// <param name="offset">The index of the first item to return. Default: 0 (the first object).</param>
/// <returns></returns>
/// <remarks>AUTH NEEDED</remarks>
public string GetCategories(string country = "", string locale = "", int limit = 20, int offset = 0)
{
limit = Math.Min(50, limit);
StringBuilder builder = new StringBuilder(APIBase + "/browse/categories");
builder.Append("?limit=" + limit);
builder.Append("&offset=" + offset);
if (!string.IsNullOrEmpty(country))
builder.Append("&country=" + country);
if (!string.IsNullOrEmpty(locale))
builder.Append("&locale=" + locale);
return builder.ToString();
}
/// <summary>
/// Get a single category used to tag items in Spotify (on, for example, the Spotify players “Browse” tab).
/// </summary>
/// <param name="categoryId">The Spotify category ID for the category.</param>
/// <param name="country">
/// A country: an ISO 3166-1 alpha-2 country code. Provide this parameter to ensure that the category
/// exists for a particular country.
/// </param>
/// <param name="locale">
/// The desired language, consisting of an ISO 639 language code and an ISO 3166-1 alpha-2 country
/// code, joined by an underscore
/// </param>
/// <returns></returns>
/// <remarks>AUTH NEEDED</remarks>
public string GetCategory(string categoryId, string country = "", string locale = "")
{
StringBuilder builder = new StringBuilder(APIBase + "/browse/categories/" + categoryId);
if (!string.IsNullOrEmpty(country))
builder.Append("?country=" + country);
if (!string.IsNullOrEmpty(locale))
builder.Append((country == "" ? "?locale=" : "&locale=") + locale);
return builder.ToString();
}
/// <summary>
/// Get a list of Spotify playlists tagged with a particular category.
/// </summary>
/// <param name="categoryId">The Spotify category ID for the category.</param>
/// <param name="country">A country: an ISO 3166-1 alpha-2 country code.</param>
/// <param name="limit">The maximum number of items to return. Default: 20. Minimum: 1. Maximum: 50.</param>
/// <param name="offset">The index of the first item to return. Default: 0</param>
/// <returns></returns>
/// <remarks>AUTH NEEDED</remarks>
public string GetCategoryPlaylists(string categoryId, string country = "", int limit = 20, int offset = 0)
{
limit = Math.Min(50, limit);
StringBuilder builder = new StringBuilder(APIBase + "/browse/categories/" + categoryId + "/playlists");
builder.Append("?limit=" + limit);
builder.Append("&offset=" + offset);
if (!string.IsNullOrEmpty(country))
builder.Append("&country=" + country);
return builder.ToString();
}
/// <summary>
/// Create a playlist-style listening experience based on seed artists, tracks and genres.
/// </summary>
/// <param name="artistSeed">A comma separated list of Spotify IDs for seed artists.
/// Up to 5 seed values may be provided in any combination of seed_artists, seed_tracks and seed_genres.
/// </param>
/// <param name="genreSeed">A comma separated list of any genres in the set of available genre seeds.
/// Up to 5 seed values may be provided in any combination of seed_artists, seed_tracks and seed_genres.
/// </param>
/// <param name="trackSeed">A comma separated list of Spotify IDs for a seed track.
/// Up to 5 seed values may be provided in any combination of seed_artists, seed_tracks and seed_genres.
/// </param>
/// <param name="target">Tracks with the attribute values nearest to the target values will be preferred.</param>
/// <param name="min">For each tunable track attribute, a hard floor on the selected track attributes value can be provided</param>
/// <param name="max">For each tunable track attribute, a hard ceiling on the selected track attributes value can be provided</param>
/// <param name="limit">The target size of the list of recommended tracks. Default: 20. Minimum: 1. Maximum: 100.
/// For seeds with unusually small pools or when highly restrictive filtering is applied, it may be impossible to generate the requested number of recommended tracks.
/// </param>
/// <param name="market">An ISO 3166-1 alpha-2 country code. Provide this parameter if you want to apply Track Relinking.
/// Because min_*, max_* and target_* are applied to pools before relinking, the generated results may not precisely match the filters applied.</param>
/// <returns></returns>
/// <remarks>AUTH NEEDED</remarks>
public string GetRecommendations(List<string> artistSeed = null, List<string> genreSeed = null, List<string> trackSeed = null,
TuneableTrack target = null, TuneableTrack min = null, TuneableTrack max = null, int limit = 20, string market = "")
{
limit = Math.Min(100, limit);
StringBuilder builder = new StringBuilder($"{APIBase}/recommendations");
builder.Append("?limit=" + limit);
if (artistSeed?.Count > 0)
builder.Append("&seed_artists=" + string.Join(",", artistSeed));
if (genreSeed?.Count > 0)
builder.Append("&seed_genres=" + string.Join(",", genreSeed));
if (trackSeed?.Count > 0)
builder.Append("&seed_tracks=" + string.Join(",", trackSeed));
if (target != null)
builder.Append(target.BuildUrlParams("target"));
if (min != null)
builder.Append(min.BuildUrlParams("min"));
if (max != null)
builder.Append(max.BuildUrlParams("max"));
if (!string.IsNullOrEmpty(market))
builder.Append("&market=" + market);
return builder.ToString();
}
/// <summary>
/// Retrieve a list of available genres seed parameter values for recommendations.
/// </summary>
/// <returns></returns>
/// <remarks>AUTH NEEDED</remarks>
public string GetRecommendationSeedsGenres()
{
return $"{APIBase}/recommendations/available-genre-seeds";
}
#endregion Browse
#region Follow
/// <summary>
/// Get the current users followed artists.
/// </summary>
/// <param name="limit">The maximum number of items to return. Default: 20. Minimum: 1. Maximum: 50. </param>
/// <param name="after">The last artist ID retrieved from the previous request.</param>
/// <returns></returns>
/// <remarks>AUTH NEEDED</remarks>
public string GetFollowedArtists(int limit = 20, string after = "")
{
limit = Math.Min(limit, 50);
const FollowType followType = FollowType.Artist; //currently only artist is supported.
StringBuilder builder = new StringBuilder(APIBase + "/me/following?type=" + followType.GetStringAttribute());
builder.Append("&limit=" + limit);
if (!string.IsNullOrEmpty(after))
builder.Append("&after=" + after);
return builder.ToString();
}
/// <summary>
/// Add the current user as a follower of one or more artists or other Spotify users.
/// </summary>
/// <param name="followType">The ID type: either artist or user.</param>
/// <returns></returns>
/// <remarks>AUTH NEEDED</remarks>
public string Follow(FollowType followType)
{
return $"{APIBase}/me/following?type={followType.GetStringAttribute()}";
}
/// <summary>
/// Remove the current user as a follower of one or more artists or other Spotify users.
/// </summary>
/// <param name="followType">The ID type: either artist or user.</param>
/// <returns></returns>
/// <remarks>AUTH NEEDED</remarks>
public string Unfollow(FollowType followType)
{
return $"{APIBase}/me/following?type={followType.GetStringAttribute()}";
}
/// <summary>
/// Check to see if the current user is following one or more artists or other Spotify users.
/// </summary>
/// <param name="followType">The ID type: either artist or user.</param>
/// <param name="ids">A list of the artist or the user Spotify IDs to check</param>
/// <returns></returns>
/// <remarks>AUTH NEEDED</remarks>
public string IsFollowing(FollowType followType, List<string> ids)
{
return $"{APIBase}/me/following/contains?type={followType.GetStringAttribute()}&ids={string.Join(",", ids)}";
}
/// <summary>
/// Add the current user as a follower of a playlist.
/// </summary>
/// <param name="ownerId">The Spotify user ID of the person who owns the playlist.</param>
/// <param name="playlistId">
/// The Spotify ID of the playlist. Any playlist can be followed, regardless of its public/private
/// status, as long as you know its playlist ID.
/// </param>
/// <param name="showPublic">
/// If true the playlist will be included in user's public playlists, if false it will remain
/// private.
/// </param>
/// <returns></returns>
/// <remarks>AUTH NEEDED</remarks>
public string FollowPlaylist(string ownerId, string playlistId, bool showPublic = true)
{
return $"{APIBase}/users/{ownerId}/playlists/{playlistId}/followers";
}
/// <summary>
/// Remove the current user as a follower of a playlist.
/// </summary>
/// <param name="ownerId">The Spotify user ID of the person who owns the playlist.</param>
/// <param name="playlistId">The Spotify ID of the playlist that is to be no longer followed.</param>
/// <returns></returns>
/// <remarks>AUTH NEEDED</remarks>
public string UnfollowPlaylist(string ownerId, string playlistId)
{
return $"{APIBase}/users/{ownerId}/playlists/{playlistId}/followers";
}
/// <summary>
/// Check to see if one or more Spotify users are following a specified playlist.
/// </summary>
/// <param name="ownerId">The Spotify user ID of the person who owns the playlist.</param>
/// <param name="playlistId">The Spotify ID of the playlist.</param>
/// <param name="ids">A list of Spotify User IDs</param>
/// <returns></returns>
/// <remarks>AUTH NEEDED</remarks>
public string IsFollowingPlaylist(string ownerId, string playlistId, List<string> ids)
{
return $"{APIBase}/users/{ownerId}/playlists/{playlistId}/followers/contains?ids={string.Join(",", ids)}";
}
#endregion Follow
#region Library
/// <summary>
/// Save one or more tracks to the current users “Your Music” library.
/// </summary>
/// <returns></returns>
/// <remarks>AUTH NEEDED</remarks>
public string SaveTracks()
{
return APIBase + "/me/tracks/";
}
/// <summary>
/// Get a list of the songs saved in the current Spotify users “Your Music” library.
/// </summary>
/// <param name="limit">The maximum number of objects to return. Default: 20. Minimum: 1. Maximum: 50.</param>
/// <param name="offset">The index of the first object to return. Default: 0 (i.e., the first object)</param>
/// <param name="market">An ISO 3166-1 alpha-2 country code. Provide this parameter if you want to apply Track Relinking.</param>
/// <returns></returns>
/// <remarks>AUTH NEEDED</remarks>
public string GetSavedTracks(int limit = 20, int offset = 0, string market = "")
{
limit = Math.Min(limit, 50);
StringBuilder builder = new StringBuilder(APIBase + "/me/tracks");
builder.Append("?limit=" + limit);
builder.Append("&offset=" + offset);
if (!string.IsNullOrEmpty(market))
builder.Append("&market=" + market);
return builder.ToString();
}
/// <summary>
/// Remove one or more tracks from the current users “Your Music” library.
/// </summary>
/// <returns></returns>
/// <remarks>AUTH NEEDED</remarks>
public string RemoveSavedTracks()
{
return APIBase + "/me/tracks/";
}
/// <summary>
/// Check if one or more tracks is already saved in the current Spotify users “Your Music” library.
/// </summary>
/// <param name="ids">A list of the Spotify IDs.</param>
/// <returns></returns>
/// <remarks>AUTH NEEDED</remarks>
public string CheckSavedTracks(List<string> ids)
{
return APIBase + "/me/tracks/contains?ids=" + string.Join(",", ids);
}
/// <summary>
/// Save one or more albums to the current users "Your Music" library.
/// </summary>
/// <returns></returns>
/// <remarks>AUTH NEEDED</remarks>
public string SaveAlbums()
{
return $"{APIBase}/me/albums";
}
/// <summary>
/// Get a list of the albums saved in the current Spotify users "Your Music" library.
/// </summary>
/// <param name="limit">The maximum number of objects to return. Default: 20. Minimum: 1. Maximum: 50.</param>
/// <param name="offset">The index of the first object to return. Default: 0 (i.e., the first object)</param>
/// <param name="market">An ISO 3166-1 alpha-2 country code. Provide this parameter if you want to apply Track Relinking.</param>
/// <returns></returns>
/// <remarks>AUTH NEEDED</remarks>
public string GetSavedAlbums(int limit = 20, int offset = 0, string market = "")
{
limit = Math.Min(limit, 50);
StringBuilder builder = new StringBuilder(APIBase + "/me/albums");
builder.Append("?limit=" + limit);
builder.Append("&offset=" + offset);
if (!string.IsNullOrEmpty(market))
builder.Append("&market=" + market);
return builder.ToString();
}
/// <summary>
/// Remove one or more albums from the current users "Your Music" library.
/// </summary>
/// <returns></returns>
/// <remarks>AUTH NEEDED</remarks>
public string RemoveSavedAlbums()
{
return APIBase + "/me/albums/";
}
/// <summary>
/// Check if one or more albums is already saved in the current Spotify users "Your Music" library.
/// </summary>
/// <param name="ids">A list of the Spotify IDs.</param>
/// <returns></returns>
/// <remarks>AUTH NEEDED</remarks>
public string CheckSavedAlbums(List<string> ids)
{
return APIBase + "/me/albums/contains?ids=" + string.Join(",", ids);
}
#endregion Library
#region Personalization
/// <summary>
/// Get the current users top tracks based on calculated affinity.
/// </summary>
/// <param name="timeRange">Over what time frame the affinities are computed.
/// Valid values: long_term (calculated from several years of data and including all new data as it becomes available),
/// medium_term (approximately last 6 months), short_term (approximately last 4 weeks). </param>
/// <param name="limit">The number of entities to return. Default: 20. Minimum: 1. Maximum: 50</param>
/// <param name="offest">The index of the first entity to return. Default: 0 (i.e., the first track). Use with limit to get the next set of entities.</param>
/// <returns></returns>
/// <remarks>AUTH NEEDED</remarks>
public string GetUsersTopTracks(TimeRangeType timeRange = TimeRangeType.MediumTerm, int limit = 20, int offest = 0)
{
limit = Math.Min(50, limit);
StringBuilder builder = new StringBuilder($"{APIBase}/me/top/tracks");
builder.Append("?limit=" + limit);
builder.Append("&offset=" + offest);
builder.Append("&time_range=" + timeRange.GetStringAttribute());
return builder.ToString();
}
/// <summary>
/// Get the current users top artists based on calculated affinity.
/// </summary>
/// <param name="timeRange">Over what time frame the affinities are computed.
/// Valid values: long_term (calculated from several years of data and including all new data as it becomes available),
/// medium_term (approximately last 6 months), short_term (approximately last 4 weeks). </param>
/// <param name="limit">The number of entities to return. Default: 20. Minimum: 1. Maximum: 50</param>
/// <param name="offest">The index of the first entity to return. Default: 0 (i.e., the first track). Use with limit to get the next set of entities.</param>
/// <returns></returns>
/// <remarks>AUTH NEEDED</remarks>
public string GetUsersTopArtists(TimeRangeType timeRange = TimeRangeType.MediumTerm, int limit = 20, int offest = 0)
{
limit = Math.Min(50, limit);
StringBuilder builder = new StringBuilder($"{APIBase}/me/top/artists");
builder.Append("?limit=" + limit);
builder.Append("&offset=" + offest);
builder.Append("&time_range=" + timeRange.GetStringAttribute());
return builder.ToString();
}
/// <summary>
/// Get tracks from the current users recent play history.
/// </summary>
/// <param name="limit">The maximum number of items to return. Default: 20. Minimum: 1. Maximum: 50. </param>
/// <param name="after">A Unix timestamp in milliseconds. Returns all items after (but not including) this cursor position. If after is specified, before must not be specified.</param>
/// <param name="before">A Unix timestamp in milliseconds. Returns all items before (but not including) this cursor position. If before is specified, after must not be specified.</param>
/// <returns></returns>
/// <remarks>AUTH NEEDED</remarks>
public string GetUsersRecentlyPlayedTracks(int limit = 20, DateTime? after = null, DateTime? before = null)
{
limit = Math.Min(50, limit);
StringBuilder builder = new StringBuilder($"{APIBase}/me/player/recently-played");
builder.Append("?limit=" + limit);
if (after.HasValue)
builder.Append("&after=" + after.Value.ToUnixTimeMillisecondsPoly());
if (before.HasValue)
builder.Append("&before=" + before.Value.ToUnixTimeMillisecondsPoly());
return builder.ToString();
}
#endregion
#region Playlists
/// <summary>
/// Get a list of the playlists owned or followed by a Spotify user.
/// </summary>
/// <param name="userId">The user's Spotify user ID.</param>
/// <param name="limit">The maximum number of playlists to return. Default: 20. Minimum: 1. Maximum: 50. </param>
/// <param name="offset">The index of the first playlist to return. Default: 0 (the first object)</param>
/// <returns></returns>
/// <remarks>AUTH NEEDED</remarks>
public string GetUserPlaylists(string userId, int limit = 20, int offset = 0)
{
limit = Math.Min(limit, 50);
StringBuilder builder = new StringBuilder(APIBase + "/users/" + userId + "/playlists");
builder.Append("?limit=" + limit);
builder.Append("&offset=" + offset);
return builder.ToString();
}
/// <summary>
/// Get a playlist owned by a Spotify user.
/// </summary>
/// <param name="userId">The user's Spotify user ID.</param>
/// <param name="playlistId">The Spotify ID for the playlist.</param>
/// <param name="fields">
/// Filters for the query: a comma-separated list of the fields to return. If omitted, all fields are
/// returned.
/// </param>
/// <param name="market">An ISO 3166-1 alpha-2 country code. Provide this parameter if you want to apply Track Relinking.</param>
/// <returns></returns>
/// <remarks>AUTH NEEDED</remarks>
public string GetPlaylist(string userId, string playlistId, string fields = "", string market = "")
{
StringBuilder builder = new StringBuilder(APIBase + "/users/" + userId + "/playlists/" + playlistId);
builder.Append("?fields=" + fields);
if (!string.IsNullOrEmpty(market))
builder.Append("&market=" + market);
return builder.ToString();
}
/// <summary>
/// Get full details of the tracks of a playlist owned by a Spotify user.
/// </summary>
/// <param name="userId">The user's Spotify user ID.</param>
/// <param name="playlistId">The Spotify ID for the playlist.</param>
/// <param name="fields">
/// Filters for the query: a comma-separated list of the fields to return. If omitted, all fields are
/// returned.
/// </param>
/// <param name="limit">The maximum number of tracks to return. Default: 100. Minimum: 1. Maximum: 100.</param>
/// <param name="offset">The index of the first object to return. Default: 0 (i.e., the first object)</param>
/// <param name="market">An ISO 3166-1 alpha-2 country code. Provide this parameter if you want to apply Track Relinking.</param>
/// <returns></returns>
/// <remarks>AUTH NEEDED</remarks>
public string GetPlaylistTracks(string userId, string playlistId, string fields = "", int limit = 100, int offset = 0, string market = "")
{
limit = Math.Min(limit, 100);
StringBuilder builder = new StringBuilder(APIBase + "/users/" + userId + "/playlists/" + playlistId + "/tracks");
builder.Append("?fields=" + fields);
builder.Append("&limit=" + limit);
builder.Append("&offset=" + offset);
if (!string.IsNullOrEmpty(market))
builder.Append("&market=" + market);
return builder.ToString();
}
/// <summary>
/// Create a playlist for a Spotify user. (The playlist will be empty until you add tracks.)
/// </summary>
/// <param name="userId">The user's Spotify user ID.</param>
/// <param name="playlistName">
/// The name for the new playlist, for example "Your Coolest Playlist". This name does not need
/// to be unique.
/// </param>
/// <param name="isPublic">
/// default true. If true the playlist will be public, if false it will be private. To be able to
/// create private playlists, the user must have granted the playlist-modify-private scope.
/// </param>
/// <returns></returns>
/// <remarks>AUTH NEEDED</remarks>
public string CreatePlaylist(string userId, string playlistName, Boolean isPublic = true)
{
return $"{APIBase}/users/{userId}/playlists";
}
/// <summary>
/// Change a playlists name and public/private state. (The user must, of course, own the playlist.)
/// </summary>
/// <param name="userId">The user's Spotify user ID.</param>
/// <param name="playlistId">The Spotify ID for the playlist.</param>
/// <returns></returns>
/// <remarks>AUTH NEEDED</remarks>
public string UpdatePlaylist(string userId, string playlistId)
{
return $"{APIBase}/users/{userId}/playlists/{playlistId}";
}
/// <summary>
/// Replace all the tracks in a playlist, overwriting its existing tracks. This powerful request can be useful for
/// replacing tracks, re-ordering existing tracks, or clearing the playlist.
/// </summary>
/// <param name="userId">The user's Spotify user ID.</param>
/// <param name="playlistId">The Spotify ID for the playlist.</param>
/// <returns></returns>
/// <remarks>AUTH NEEDED</remarks>
public string ReplacePlaylistTracks(string userId, string playlistId)
{
return $"{APIBase}/users/{userId}/playlists/{playlistId}/tracks";
}
/// <summary>
/// Remove one or more tracks from a users playlist.
/// </summary>
/// <param name="userId">The user's Spotify user ID.</param>
/// <param name="playlistId">The Spotify ID for the playlist.</param>
/// <param name="uris">
/// array of objects containing Spotify URI strings (and their position in the playlist). A maximum of
/// 100 objects can be sent at once.
/// </param>
/// <returns></returns>
/// <remarks>AUTH NEEDED</remarks>
public string RemovePlaylistTracks(string userId, string playlistId, List<DeleteTrackUri> uris)
{
return $"{APIBase}/users/{userId}/playlists/{playlistId}/tracks";
}
/// <summary>
/// Add one or more tracks to a users playlist.
/// </summary>
/// <param name="userId">The user's Spotify user ID.</param>
/// <param name="playlistId">The Spotify ID for the playlist.</param>
/// <param name="uris">A list of Spotify track URIs to add</param>
/// <param name="position">The position to insert the tracks, a zero-based index</param>
/// <returns></returns>
/// <remarks>AUTH NEEDED</remarks>
public string AddPlaylistTracks(string userId, string playlistId, List<string> uris, int? position = null)
{
if (position == null)
return $"{APIBase}/users/{userId}/playlists/{playlistId}/tracks";
return $"{APIBase}/users/{userId}/playlists/{playlistId}/tracks?position={position}";
}
/// <summary>
/// Reorder a track or a group of tracks in a playlist.
/// </summary>
/// <param name="userId">The user's Spotify user ID.</param>
/// <param name="playlistId">The Spotify ID for the playlist.</param>
/// <returns></returns>
/// <remarks>AUTH NEEDED</remarks>
public string ReorderPlaylist(string userId, string playlistId)
{
return $"{APIBase}/users/{userId}/playlists/{playlistId}/tracks";
}
#endregion Playlists
#region Profiles
/// <summary>
/// Get detailed profile information about the current user (including the current users username).
/// </summary>
/// <returns></returns>
/// <remarks>AUTH NEEDED</remarks>
public string GetPrivateProfile()
{
return $"{APIBase}/me";
}
/// <summary>
/// Get public profile information about a Spotify user.
/// </summary>
/// <param name="userId">The user's Spotify user ID.</param>
/// <returns></returns>
public string GetPublicProfile(string userId)
{
return $"{APIBase}/users/{userId}";
}
#endregion Profiles
#region Tracks
/// <summary>
/// Get Spotify catalog information for multiple tracks based on their Spotify IDs.
/// </summary>
/// <param name="ids">A list of the Spotify IDs for the tracks. Maximum: 50 IDs.</param>
/// <param name="market">An ISO 3166-1 alpha-2 country code. Provide this parameter if you want to apply Track Relinking.</param>
/// <returns></returns>
public string GetSeveralTracks(List<string> ids, string market = "")
{
if (string.IsNullOrEmpty(market))
return $"{APIBase}/tracks?ids={string.Join(",", ids.Take(50))}";
return $"{APIBase}/tracks?market={market}&ids={string.Join(",", ids.Take(50))}";
}
/// <summary>
/// Get Spotify catalog information for a single track identified by its unique Spotify ID.
/// </summary>
/// <param name="id">The Spotify ID for the track.</param>
/// <param name="market">An ISO 3166-1 alpha-2 country code. Provide this parameter if you want to apply Track Relinking.</param>
/// <returns></returns>
public string GetTrack(string id, string market = "")
{
if (string.IsNullOrEmpty(market))
return $"{APIBase}/tracks/{id}";
return $"{APIBase}/tracks/{id}?market={market}";
}
/// <summary>
/// Get audio feature information for a single track identified by its unique Spotify ID.
/// </summary>
/// <param name="id">The Spotify ID for the track.</param>
/// <returns></returns>
/// <remarks>AUTH NEEDED</remarks>
public string GetAudioFeatures(string id)
{
return $"{APIBase}/audio-features/{id}";
}
/// <summary>
/// Get audio features for multiple tracks based on their Spotify IDs.
/// </summary>
/// <param name="ids">A list of Spotify Track-IDs. Maximum: 100 IDs.</param>
/// <returns></returns>
/// <remarks>AUTH NEEDED</remarks>
public string GetSeveralAudioFeatures(List<string> ids)
{
return $"{APIBase}/audio-features?ids={string.Join(",", ids.Take(100))}";
}
#endregion Tracks
#region Player
/// <summary>
/// Get information about a users available devices.
/// </summary>
/// <returns></returns>
public string GetDevices()
{
return $"{APIBase}/me/player/devices";
}
/// <summary>
/// Get information about the users current playback state, including track, track progress, and active device.
/// </summary>
/// <param name="market">An ISO 3166-1 alpha-2 country code. Provide this parameter if you want to apply Track Relinking.</param>
/// <returns></returns>
public string GetPlayback(string market = "")
{
if (string.IsNullOrEmpty(market))
return $"{APIBase}/me/player";
return $"{APIBase}/me/player?market={market}";
}
/// <summary>
/// Get the object currently being played on the users Spotify account.
/// </summary>
/// <param name="market">An ISO 3166-1 alpha-2 country code. Provide this parameter if you want to apply Track Relinking.</param>
/// <returns></returns>
public string GetPlayingTrack(string market = "")
{
if (string.IsNullOrEmpty(market))
return $"{APIBase}/me/player/currently-playing";
return $"{APIBase}/me/player/currently-playing?market={market}";
}
/// <summary>
/// Transfer playback to a new device and determine if it should start playing.
/// </summary>
/// <returns></returns>
public string TransferPlayback()
{
return $"{APIBase}/me/player";
}
/// <summary>
/// Start a new context or resume current playback on the users active device.
/// </summary>
/// <param name="deviceId">The id of the device this command is targeting. If not supplied, the user's currently active device is the target.</param>
/// <returns></returns>
public string ResumePlayback(string deviceId = "")
{
if(string.IsNullOrEmpty(deviceId))
return $"{APIBase}/me/player/play";
return $"{APIBase}/me/player/play?device_id={deviceId}";
}
/// <summary>
/// Pause playback on the users account.
/// </summary>
/// <param name="deviceId">The id of the device this command is targeting. If not supplied, the user's currently active device is the target.</param>
/// <returns></returns>
public string PausePlayback(string deviceId = "")
{
if (string.IsNullOrEmpty(deviceId))
return $"{APIBase}/me/player/pause";
return $"{APIBase}/me/player/pause?device_id={deviceId}";
}
/// <summary>
/// Skips to next track in the users queue.
/// </summary>
/// <param name="deviceId">The id of the device this command is targeting. If not supplied, the user's currently active device is the target.</param>
/// <returns></returns>
public string SkipPlaybackToNext(string deviceId = "")
{
if (string.IsNullOrEmpty(deviceId))
return $"{APIBase}/me/player/next";
return $"{APIBase}/me/player/next?device_id={deviceId}";
}
/// <summary>
/// Skips to previous track in the users queue.
/// Note that this will ALWAYS skip to the previous track, regardless of the current tracks progress.
/// Returning to the start of the current track should be performed using the https://api.spotify.com/v1/me/player/seek endpoint.
/// </summary>
/// <param name="deviceId">The id of the device this command is targeting. If not supplied, the user's currently active device is the target.</param>
/// <returns></returns>
public string SkipPlaybackToPrevious(string deviceId = "")
{
if (string.IsNullOrEmpty(deviceId))
return $"{APIBase}/me/player/previous";
return $"{APIBase}/me/player/previous?device_id={deviceId}";
}
/// <summary>
/// Seeks to the given position in the users currently playing track.
/// </summary>
/// <param name="positionMs">The position in milliseconds to seek to. Must be a positive number.
/// Passing in a position that is greater than the length of the track will cause the player to start playing the next song.</param>
/// <param name="deviceId">The id of the device this command is targeting. If not supplied, the user's currently active device is the target.</param>
/// <returns></returns>
public string SeekPlayback(int positionMs, string deviceId = "")
{
if (string.IsNullOrEmpty(deviceId))
return $"{APIBase}/me/player/seek?position_ms={positionMs}";
return $"{APIBase}/me/player/seek?position_ms={positionMs}&device_id={deviceId}";
}
/// <summary>
/// Set the repeat mode for the users playback. Options are repeat-track, repeat-context, and off.
/// </summary>
/// <param name="repeatState">track, context or off.</param>
/// <param name="deviceId">The id of the device this command is targeting. If not supplied, the user's currently active device is the target.</param>
/// <returns></returns>
public string SetRepeatMode(RepeatState repeatState, string deviceId = "")
{
if (string.IsNullOrEmpty(deviceId))
return $"{APIBase}/me/player/repeat?state={repeatState.GetStringAttribute()}";
return $"{APIBase}/me/player/repeat?state={repeatState.GetStringAttribute()}&device_id={deviceId}";
}
/// <summary>
/// Set the volume for the users current playback device.
/// </summary>
/// <param name="volumePercent">Integer. The volume to set. Must be a value from 0 to 100 inclusive.</param>
/// <param name="deviceId">The id of the device this command is targeting. If not supplied, the user's currently active device is the target.</param>
/// <returns></returns>
public string SetVolume(int volumePercent, string deviceId = "")
{
if (string.IsNullOrEmpty(deviceId))
return $"{APIBase}/me/player/volume?volume_percent={volumePercent}";
return $"{APIBase}/me/player/volume?volume_percent={volumePercent}&device_id={deviceId}";
}
/// <summary>
/// Toggle shuffle on or off for users playback.
/// </summary>
/// <param name="shuffle">True of False.</param>
/// <param name="deviceId">The id of the device this command is targeting. If not supplied, the user's currently active device is the target.</param>
/// <returns></returns>
public string SetShuffle(bool shuffle, string deviceId = "")
{
if (string.IsNullOrEmpty(deviceId))
return $"{APIBase}/me/player/shuffle?state={shuffle}";
return $"{APIBase}/me/player/shuffle?state={shuffle}&device_id={deviceId}";
}
#endregion
}
}