using System; using System.Collections.Generic; using System.Linq; using System.Text; using SpotifyAPI.Web.Enums; using SpotifyAPI.Web.Models; namespace SpotifyAPI.Web { /// /// SpotifyAPI URL-Generator /// public class SpotifyWebBuilder { public const string APIBase = "https://api.spotify.com/v1"; #region Search /// /// Get Spotify catalog information about artists, albums, tracks or playlists that match a keyword string. /// /// The search query's keywords (and optional field filters and operators), for example q=roadhouse+blues. /// A list of item types to search across. /// The maximum number of items to return. Default: 20. Minimum: 1. Maximum: 50. /// The index of the first result to return. Default: 0 /// An ISO 3166-1 alpha-2 country code or the string from_token. /// 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 /// /// Get Spotify catalog information about an album’s tracks. Optional parameters can be used to limit the number of /// tracks returned. /// /// The Spotify ID for the album. /// The maximum number of items to return. Default: 20. Minimum: 1. Maximum: 50. /// The index of the first track to return. Default: 0 (the first object). /// An ISO 3166-1 alpha-2 country code. Provide this parameter if you want to apply Track Relinking. /// 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(); } /// /// Get Spotify catalog information for a single album. /// /// The Spotify ID for the album. /// An ISO 3166-1 alpha-2 country code. Provide this parameter if you want to apply Track Relinking. /// public string GetAlbum(String id, String market = "") { if (String.IsNullOrEmpty(market)) return $"{APIBase}/albums/{id}"; return $"{APIBase}/albums/{id}?market={market}"; } /// /// Get Spotify catalog information for multiple albums identified by their Spotify IDs. /// /// A list of the Spotify IDs for the albums. Maximum: 20 IDs. /// An ISO 3166-1 alpha-2 country code. Provide this parameter if you want to apply Track Relinking. /// public string GetSeveralAlbums(List 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 /// /// Get Spotify catalog information for a single artist identified by their unique Spotify ID. /// /// The Spotify ID for the artist. /// public string GetArtist(String id) { return $"{APIBase}/artists/{id}"; } /// /// Get Spotify catalog information about artists similar to a given artist. Similarity is based on analysis of the /// Spotify community’s listening history. /// /// The Spotify ID for the artist. /// public string GetRelatedArtists(String id) { return $"{APIBase}/artists/{id}/related-artists"; } /// /// Get Spotify catalog information about an artist’s top tracks by country. /// /// The Spotify ID for the artist. /// The country: an ISO 3166-1 alpha-2 country code. /// public string GetArtistsTopTracks(String id, String country) { return $"{APIBase}/artists/{id}/top-tracks?country={country}"; } /// /// Get Spotify catalog information about an artist’s albums. Optional parameters can be specified in the query string /// to filter and sort the response. /// /// The Spotify ID for the artist. /// /// A list of keywords that will be used to filter the response. If not supplied, all album types will /// be returned /// /// The maximum number of items to return. Default: 20. Minimum: 1. Maximum: 50. /// The index of the first album to return. Default: 0 /// /// An ISO 3166-1 alpha-2 country code. Supply this parameter to limit the response to one particular /// geographical market /// /// 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("?type=" + type.GetStringAttribute(",")); builder.Append("&limit=" + limit); builder.Append("&offset=" + offset); if (!String.IsNullOrEmpty(market)) builder.Append("&market=" + market); return builder.ToString(); } /// /// Get Spotify catalog information for several artists based on their Spotify IDs. /// /// A list of the Spotify IDs for the artists. Maximum: 50 IDs. /// public string GetSeveralArtists(List ids) { return $"{APIBase}/artists?ids={string.Join(",", ids.Take(50))}"; } #endregion Artists #region Browse /// /// Get a list of Spotify featured playlists (shown, for example, on a Spotify player’s “Browse” tab). /// /// /// 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. /// /// A country: an ISO 3166-1 alpha-2 country code. /// A timestamp in ISO 8601 format /// The maximum number of items to return. Default: 20. Minimum: 1. Maximum: 50. /// The index of the first item to return. Default: 0 /// AUTH NEEDED public string GetFeaturedPlaylists(String locale = "", String country = "", DateTime timestamp = default(DateTime), int limit = 20, int offset = 0) { limit = Math.Max(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("×tamp=" + timestamp.ToString("yyyy-MM-ddTHH:mm:ss")); return builder.ToString(); } /// /// Get a list of new album releases featured in Spotify (shown, for example, on a Spotify player’s “Browse” tab). /// /// A country: an ISO 3166-1 alpha-2 country code. /// The maximum number of items to return. Default: 20. Minimum: 1. Maximum: 50. /// The index of the first item to return. Default: 0 /// /// AUTH NEEDED public string GetNewAlbumReleases(String country = "", int limit = 20, int offset = 0) { limit = Math.Max(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(); } /// /// Get a list of categories used to tag items in Spotify (on, for example, the Spotify player’s “Browse” tab). /// /// /// 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 /// /// /// The desired language, consisting of an ISO 639 language code and an ISO 3166-1 alpha-2 country /// code, joined by an underscore /// /// The maximum number of categories to return. Default: 20. Minimum: 1. Maximum: 50. /// The index of the first item to return. Default: 0 (the first object). /// /// AUTH NEEDED 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(); } /// /// Get a single category used to tag items in Spotify (on, for example, the Spotify player’s “Browse” tab). /// /// The Spotify category ID for the category. /// /// A country: an ISO 3166-1 alpha-2 country code. Provide this parameter to ensure that the category /// exists for a particular country. /// /// /// The desired language, consisting of an ISO 639 language code and an ISO 3166-1 alpha-2 country /// code, joined by an underscore /// /// /// AUTH NEEDED 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(); } /// /// Get a list of Spotify playlists tagged with a particular category. /// /// The Spotify category ID for the category. /// A country: an ISO 3166-1 alpha-2 country code. /// The maximum number of items to return. Default: 20. Minimum: 1. Maximum: 50. /// The index of the first item to return. Default: 0 /// /// AUTH NEEDED 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(); } #endregion Browse #region Follow /// /// Get the current user’s followed artists. /// /// The maximum number of items to return. Default: 20. Minimum: 1. Maximum: 50. /// The last artist ID retrieved from the previous request. /// /// AUTH NEEDED public string GetFollowedArtists(int limit = 20, String after = "") { limit = Math.Max(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(); } /// /// Add the current user as a follower of one or more artists or other Spotify users. /// /// The ID type: either artist or user. /// /// AUTH NEEDED public string Follow(FollowType followType) { return $"{APIBase}/me/following?type={followType.GetStringAttribute("")}"; } /// /// Remove the current user as a follower of one or more artists or other Spotify users. /// /// The ID type: either artist or user. /// /// AUTH NEEDED public string Unfollow(FollowType followType) { return $"{APIBase}/me/following?type={followType.GetStringAttribute("")}"; } /// /// Check to see if the current user is following one or more artists or other Spotify users. /// /// The ID type: either artist or user. /// A list of the artist or the user Spotify IDs to check /// /// AUTH NEEDED public string IsFollowing(FollowType followType, List ids) { return $"{APIBase}/me/following/contains?type={followType.GetStringAttribute("")}&ids={string.Join(",", ids)}"; } /// /// Add the current user as a follower of a playlist. /// /// The Spotify user ID of the person who owns the playlist. /// /// 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. /// /// /// If true the playlist will be included in user's public playlists, if false it will remain /// private. /// /// /// AUTH NEEDED public string FollowPlaylist(String ownerId, String playlistId, bool showPublic = true) { return $"{APIBase}/users/{ownerId}/playlists/{playlistId}/followers"; } /// /// Remove the current user as a follower of a playlist. /// /// The Spotify user ID of the person who owns the playlist. /// The Spotify ID of the playlist that is to be no longer followed. /// /// AUTH NEEDED public string UnfollowPlaylist(String ownerId, String playlistId) { return $"{APIBase}/users/{ownerId}/playlists/{playlistId}/followers"; } /// /// Check to see if one or more Spotify users are following a specified playlist. /// /// The Spotify user ID of the person who owns the playlist. /// The Spotify ID of the playlist. /// A list of Spotify User IDs /// /// AUTH NEEDED public string IsFollowingPlaylist(String ownerId, String playlistId, List ids) { return $"{APIBase}/users/{ownerId}/playlists/{playlistId}/followers/contains?ids={string.Join(",", ids)}"; } #endregion Follow #region Library /// /// Save one or more tracks to the current user’s “Your Music” library. /// /// A list of the Spotify IDs /// /// AUTH NEEDED public string SaveTracks(List ids) { return APIBase + "/me/tracks/"; } /// /// Get a list of the songs saved in the current Spotify user’s “Your Music” library. /// /// The maximum number of objects to return. Default: 20. Minimum: 1. Maximum: 50. /// The index of the first object to return. Default: 0 (i.e., the first object) /// An ISO 3166-1 alpha-2 country code. Provide this parameter if you want to apply Track Relinking. /// /// AUTH NEEDED 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(); } /// /// Remove one or more tracks from the current user’s “Your Music” library. /// /// A list of the Spotify IDs. /// /// AUTH NEEDED public string RemoveSavedTracks(List ids) { return APIBase + "/me/tracks/"; } /// /// Check if one or more tracks is already saved in the current Spotify user’s “Your Music” library. /// /// A list of the Spotify IDs. /// /// AUTH NEEDED public string CheckSavedTracks(List ids) { return APIBase + "/me/tracks/contains?ids=" + string.Join(",", ids); } #endregion Library #region Playlists /// /// Get a list of the playlists owned or followed by a Spotify user. /// /// The user's Spotify user ID. /// The maximum number of playlists to return. Default: 20. Minimum: 1. Maximum: 50. /// The index of the first playlist to return. Default: 0 (the first object) /// /// AUTH NEEDED 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(); } /// /// Get a playlist owned by a Spotify user. /// /// The user's Spotify user ID. /// The Spotify ID for the playlist. /// /// Filters for the query: a comma-separated list of the fields to return. If omitted, all fields are /// returned. /// /// An ISO 3166-1 alpha-2 country code. Provide this parameter if you want to apply Track Relinking. /// /// AUTH NEEDED 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(); } /// /// Get full details of the tracks of a playlist owned by a Spotify user. /// /// The user's Spotify user ID. /// The Spotify ID for the playlist. /// /// Filters for the query: a comma-separated list of the fields to return. If omitted, all fields are /// returned. /// /// The maximum number of tracks to return. Default: 100. Minimum: 1. Maximum: 100. /// The index of the first object to return. Default: 0 (i.e., the first object) /// An ISO 3166-1 alpha-2 country code. Provide this parameter if you want to apply Track Relinking. /// /// AUTH NEEDED public string GetPlaylistTracks(String userId, String playlistId, String fields = "", int limit = 100, int offset = 0, String market = "") { limit = Math.Max(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(); } /// /// Create a playlist for a Spotify user. (The playlist will be empty until you add tracks.) /// /// The user's Spotify user ID. /// /// The name for the new playlist, for example "Your Coolest Playlist". This name does not need /// to be unique. /// /// /// 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. /// /// /// AUTH NEEDED public string CreatePlaylist(String userId, String playlistName, Boolean isPublic = true) { return $"{APIBase}/users/{userId}/playlists"; } /// /// Change a playlist’s name and public/private state. (The user must, of course, own the playlist.) /// /// The user's Spotify user ID. /// The Spotify ID for the playlist. /// The new name for the playlist, for example "My New Playlist Title". /// If true the playlist will be public, if false it will be private. /// /// AUTH NEEDED public string UpdatePlaylist(String userId, String playlistId, String newName = null, Boolean? newPublic = null) { return $"{APIBase}/users/{userId}/playlists/{playlistId}"; } /// /// 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. /// /// The user's Spotify user ID. /// The Spotify ID for the playlist. /// A list of Spotify track URIs to set. A maximum of 100 tracks can be set in one request. /// /// AUTH NEEDED public string ReplacePlaylistTracks(String userId, String playlistId, List uris) { return $"{APIBase}/users/{userId}/playlists/{playlistId}/tracks"; } /// /// Remove one or more tracks from a user’s playlist. /// /// The user's Spotify user ID. /// The Spotify ID for the playlist. /// /// array of objects containing Spotify URI strings (and their position in the playlist). A maximum of /// 100 objects can be sent at once. /// /// /// AUTH NEEDED public string RemovePlaylistTracks(String userId, String playlistId, List uris) { return $"{APIBase}/users/{userId}/playlists/{playlistId}/tracks"; } /// /// Add one or more tracks to a user’s playlist. /// /// The user's Spotify user ID. /// The Spotify ID for the playlist. /// A list of Spotify track URIs to add /// The position to insert the tracks, a zero-based index /// /// AUTH NEEDED public string AddPlaylistTracks(String userId, String playlistId, List uris, int? position = null) { if (position == null) return $"{APIBase}/users/{userId}/playlists/{playlistId}/tracks"; return $"{APIBase}/users/{userId}/playlists/{playlistId}/tracks?position={position}"; } /// /// Reorder a track or a group of tracks in a playlist. /// /// The user's Spotify user ID. /// The Spotify ID for the playlist. /// The position of the first track to be reordered. /// The position where the tracks should be inserted. /// The amount of tracks to be reordered. Defaults to 1 if not set. /// The playlist's snapshot ID against which you want to make the changes. /// /// AUTH NEEDED public string ReorderPlaylist(String userId, String playlistId, int rangeStart, int insertBefore, int rangeLength = 1, String snapshotId = "") { return APIBase + "/users/" + userId + "/playlists/" + playlistId + "/tracks"; } #endregion Playlists #region Profiles /// /// Get detailed profile information about the current user (including the current user’s username). /// /// /// AUTH NEEDED public string GetPrivateProfile() { return $"{APIBase}/me"; } /// /// Get public profile information about a Spotify user. /// /// The user's Spotify user ID. /// public string GetPublicProfile(String userId) { return $"{APIBase}/users/{userId}"; } #endregion Profiles #region Tracks /// /// Get Spotify catalog information for multiple tracks based on their Spotify IDs. /// /// A list of the Spotify IDs for the tracks. Maximum: 50 IDs. /// An ISO 3166-1 alpha-2 country code. Provide this parameter if you want to apply Track Relinking. /// public string GetSeveralTracks(List 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))}"; } /// /// Get Spotify catalog information for a single track identified by its unique Spotify ID. /// /// The Spotify ID for the track. /// An ISO 3166-1 alpha-2 country code. Provide this parameter if you want to apply Track Relinking. /// public string GetTrack(String id, String market = "") { if (String.IsNullOrEmpty(market)) return $"{APIBase}/tracks/{id}"; return $"{APIBase}/tracks/{id}?market={market}"; } #endregion Tracks } }