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
}
}