using Newtonsoft.Json;

using Newtonsoft.Json.Linq;

using SpotifyAPI.Web.Enums;

using SpotifyAPI.Web.Models;

using System;

using System.Collections.Generic;

using System.Linq;

using System.Net;

using System.Threading;

using System.Threading.Tasks;

namespace SpotifyAPI.Web

{

// ReSharper disable once InconsistentNaming

public sealed class SpotifyWebAPI : IDisposable

{

private readonly SpotifyWebBuilder _builder;

public SpotifyWebAPI() : this(null)

{

}

public SpotifyWebAPI(ProxyConfig proxyConfig)

{

_builder = new SpotifyWebBuilder();

UseAuth = true;

WebClient = new SpotifyWebClient(proxyConfig)

{

JsonSettings =

new JsonSerializerSettings

{

NullValueHandling = NullValueHandling.Ignore

}

};

}

public void Dispose()

{

WebClient.Dispose();

GC.SuppressFinalize(this);

}

#region Configuration

/// <summary>

/// The type of the <see cref="AccessToken"/>

/// </summary>

public string TokenType { get; set; }

/// <summary>

/// A valid token issued by spotify. Used only when <see cref="UseAuth"/> is true

/// </summary>

public string AccessToken { get; set; }

/// <summary>

/// If true, an authorization header based on <see cref="TokenType"/> and <see cref="AccessToken"/> will be used

/// </summary>

public bool UseAuth { get; set; }

/// <summary>

/// A custom WebClient, used for Unit-Testing

/// </summary>

public IClient WebClient { get; set; }

/// <summary>

/// Specifies after how many miliseconds should a failed request be retried.

/// </summary>

public int RetryAfter { get; set; } = 50;

/// <summary>

/// Should a failed request (specified by <see cref="RetryErrorCodes"/> be automatically retried or not.

/// </summary>

public bool UseAutoRetry { get; set; } = false;

/// <summary>

/// Maximum number of tries for one failed request.

/// </summary>

public int RetryTimes { get; set; } = 10;

/// <summary>

/// Whether a failure of type "Too Many Requests" should use up one of the allocated retry attempts.

/// </summary>

public bool TooManyRequestsConsumesARetry { get; set; } = false;

/// <summary>

/// Error codes that will trigger auto-retry if <see cref="UseAutoRetry"/> is enabled.

/// </summary>

public IEnumerable<int> RetryErrorCodes { get; set; } = new[] { 500, 502, 503 };

#endregion Configuration

#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 SearchItem SearchItems(string q, SearchType type, int limit = 20, int offset = 0, string market = "")

{

return DownloadData<SearchItem>(_builder.SearchItems(q, type, limit, offset, market));

}

/// <summary>

/// Get Spotify catalog information about artists, albums, tracks or playlists that match a keyword string asynchronously.

/// </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 Task<SearchItem> SearchItemsAsync(string q, SearchType type, int limit = 20, int offset = 0, string market = "")

{

return DownloadDataAsync<SearchItem>(_builder.SearchItems(q, type, limit, offset, market));

}

/// <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. (properly escaped)</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 SearchItem SearchItemsEscaped(string q, SearchType type, int limit = 20, int offset = 0, string market = "")

{

string escapedQuery = WebUtility.UrlEncode(q);

return DownloadData<SearchItem>(_builder.SearchItems(escapedQuery, type, limit, offset, market));

}

/// <summary>

/// Get Spotify catalog information about artists, albums, tracks or playlists that match a keyword string asynchronously.

/// </summary>

/// <param name="q">The search query's keywords (and optional field filters and operators), for example q=roadhouse+blues. (properly escaped)</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 Task<SearchItem> SearchItemsEscapedAsync(string q, SearchType type, int limit = 20, int offset = 0, string market = "")

{

string escapedQuery = WebUtility.UrlEncode(q);

return DownloadDataAsync<SearchItem>(_builder.SearchItems(escapedQuery, type, limit, offset, market));

}

#endregion Search

#region Albums

/// <summary>

/// Get Spotify catalog information about an album’s 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 Paging<SimpleTrack> GetAlbumTracks(string id, int limit = 20, int offset = 0, string market = "")

{

return DownloadData<Paging<SimpleTrack>>(_builder.GetAlbumTracks(id, limit, offset, market));

}

/// <summary>

/// Get Spotify catalog information about an album’s tracks asynchronously. 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 Task<Paging<SimpleTrack>> GetAlbumTracksAsync(string id, int limit = 20, int offset = 0, string market = "")

{

return DownloadDataAsync<Paging<SimpleTrack>>(_builder.GetAlbumTracks(id, limit, offset, market));

}

/// <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 FullAlbum GetAlbum(string id, string market = "")

{

return DownloadData<FullAlbum>(_builder.GetAlbum(id, market));

}

/// <summary>

/// Get Spotify catalog information for a single album asynchronously.

/// </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 Task<FullAlbum> GetAlbumAsync(string id, string market = "")

{

return DownloadDataAsync<FullAlbum>(_builder.GetAlbum(id, 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 SeveralAlbums GetSeveralAlbums(List<string> ids, string market = "")

{

return DownloadData<SeveralAlbums>(_builder.GetSeveralAlbums(ids, market));

}

/// <summary>

/// Get Spotify catalog information for multiple albums identified by their Spotify IDs asynchrously.

/// </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 Task<SeveralAlbums> GetSeveralAlbumsAsync(List<string> ids, string market = "")

{

return DownloadDataAsync<SeveralAlbums>(_builder.GetSeveralAlbums(ids, market));

}

#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 FullArtist GetArtist(string id)

{

return DownloadData<FullArtist>(_builder.GetArtist(id));

}

/// <summary>

/// Get Spotify catalog information for a single artist identified by their unique Spotify ID asynchronously.

/// </summary>

/// <param name="id">The Spotify ID for the artist.</param>

/// <returns></returns>

public Task<FullArtist> GetArtistAsync(string id)

{

return DownloadDataAsync<FullArtist>(_builder.GetArtist(id));

}

/// <summary>

/// Get Spotify catalog information about artists similar to a given artist. Similarity is based on analysis of the

/// Spotify community’s listening history.

/// </summary>

/// <param name="id">The Spotify ID for the artist.</param>

/// <returns></returns>

public SeveralArtists GetRelatedArtists(string id)

{

return DownloadData<SeveralArtists>(_builder.GetRelatedArtists(id));

}

/// <summary>

/// Get Spotify catalog information about artists similar to a given artist asynchronously. Similarity is based on analysis of the

/// Spotify community’s listening history.

/// </summary>

/// <param name="id">The Spotify ID for the artist.</param>

/// <returns></returns>

public Task<SeveralArtists> GetRelatedArtistsAsync(string id)

{

return DownloadDataAsync<SeveralArtists>(_builder.GetRelatedArtists(id));

}

/// <summary>

/// Get Spotify catalog information about an artist’s 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 SeveralTracks GetArtistsTopTracks(string id, string country)

{

return DownloadData<SeveralTracks>(_builder.GetArtistsTopTracks(id, country));

}

/// <summary>

/// Get Spotify catalog information about an artist’s top tracks by country asynchronously.

/// </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 Task<SeveralTracks> GetArtistsTopTracksAsync(string id, string country)

{

return DownloadDataAsync<SeveralTracks>(_builder.GetArtistsTopTracks(id, country));

}

/// <summary>

/// Get Spotify catalog information about an artist’s 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 Paging<SimpleAlbum> GetArtistsAlbums(string id, AlbumType type = AlbumType.All, int limit = 20, int offset = 0, string market = "")

{

return DownloadData<Paging<SimpleAlbum>>(_builder.GetArtistsAlbums(id, type, limit, offset, market));

}

/// <summary>

/// Get Spotify catalog information about an artist’s albums asynchronously. 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 Task<Paging<SimpleAlbum>> GetArtistsAlbumsAsync(string id, AlbumType type = AlbumType.All, int limit = 20, int offset = 0, string market = "")

{

return DownloadDataAsync<Paging<SimpleAlbum>>(_builder.GetArtistsAlbums(id, type, limit, offset, market));

}

/// <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 SeveralArtists GetSeveralArtists(List<string> ids)

{

return DownloadData<SeveralArtists>(_builder.GetSeveralArtists(ids));

}

/// <summary>

/// Get Spotify catalog information for several artists based on their Spotify IDs asynchronously.

/// </summary>

/// <param name="ids">A list of the Spotify IDs for the artists. Maximum: 50 IDs.</param>

/// <returns></returns>

public Task<SeveralArtists> GetSeveralArtistsAsync(List<string> ids)

{

return DownloadDataAsync<SeveralArtists>(_builder.GetSeveralArtists(ids));

}

#endregion Artists

#region Browse

/// <summary>

/// Get a list of Spotify featured playlists (shown, for example, on a Spotify player’s “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 FeaturedPlaylists GetFeaturedPlaylists(string locale = "", string country = "", DateTime timestamp = default(DateTime), int limit = 20, int offset = 0)

{

if (!UseAuth)

throw new InvalidOperationException("Auth is required for GetFeaturedPlaylists");

return DownloadData<FeaturedPlaylists>(_builder.GetFeaturedPlaylists(locale, country, timestamp, limit, offset));

}

/// <summary>

/// Get a list of Spotify featured playlists asynchronously (shown, for example, on a Spotify player’s “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 Task<FeaturedPlaylists> GetFeaturedPlaylistsAsync(string locale = "", string country = "", DateTime timestamp = default(DateTime), int limit = 20, int offset = 0)

{

if (!UseAuth)

throw new InvalidOperationException("Auth is required for GetFeaturedPlaylists");

return DownloadDataAsync<FeaturedPlaylists>(_builder.GetFeaturedPlaylists(locale, country, timestamp, limit, offset));

}

/// <summary>

/// Get a list of new album releases featured in Spotify (shown, for example, on a Spotify player’s “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 NewAlbumReleases GetNewAlbumReleases(string country = "", int limit = 20, int offset = 0)

{

if (!UseAuth)

throw new InvalidOperationException("Auth is required for GetNewAlbumReleases");

return DownloadData<NewAlbumReleases>(_builder.GetNewAlbumReleases(country, limit, offset));

}

/// <summary>

/// Get a list of new album releases featured in Spotify asynchronously (shown, for example, on a Spotify player’s “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 Task<NewAlbumReleases> GetNewAlbumReleasesAsync(string country = "", int limit = 20, int offset = 0)

{

if (!UseAuth)

throw new InvalidOperationException("Auth is required for GetNewAlbumReleases");

return DownloadDataAsync<NewAlbumReleases>(_builder.GetNewAlbumReleases(country, limit, offset));

}

/// <summary>

/// Get a list of categories used to tag items in Spotify (on, for example, the Spotify player’s “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 CategoryList GetCategories(string country = "", string locale = "", int limit = 20, int offset = 0)

{

if (!UseAuth)

throw new InvalidOperationException("Auth is required for GetCategories");

return DownloadData<CategoryList>(_builder.GetCategories(country, locale, limit, offset));

}

/// <summary>

/// Get a list of categories used to tag items in Spotify asynchronously (on, for example, the Spotify player’s “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 Task<CategoryList> GetCategoriesAsync(string country = "", string locale = "", int limit = 20, int offset = 0)

{

if (!UseAuth)

throw new InvalidOperationException("Auth is required for GetCategories");

return DownloadDataAsync<CategoryList>(_builder.GetCategories(country, locale, limit, offset));

}

/// <summary>

/// Get a single category used to tag items in Spotify (on, for example, the Spotify player’s “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 Category GetCategory(string categoryId, string country = "", string locale = "")

{

return DownloadData<Category>(_builder.GetCategory(categoryId, country, locale));

}

/// <summary>

/// Get a single category used to tag items in Spotify asynchronously (on, for example, the Spotify player’s “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 Task<Category> GetCategoryAsync(string categoryId, string country = "", string locale = "")

{

return DownloadDataAsync<Category>(_builder.GetCategory(categoryId, country, locale));

}

/// <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 CategoryPlaylist GetCategoryPlaylists(string categoryId, string country = "", int limit = 20, int offset = 0)

{

return DownloadData<CategoryPlaylist>(_builder.GetCategoryPlaylists(categoryId, country, limit, offset));

}

/// <summary>

/// Get a list of Spotify playlists tagged with a particular category asynchronously.

/// </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 Task<CategoryPlaylist> GetCategoryPlaylistsAsync(string categoryId, string country = "", int limit = 20, int offset = 0)

{

return DownloadDataAsync<CategoryPlaylist>(_builder.GetCategoryPlaylists(categoryId, country, limit, offset));

}

/// <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 attribute’s value can be provided</param>

/// <param name="max">For each tunable track attribute, a hard ceiling on the selected track attribute’s 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 Recommendations 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 = "")

{

return DownloadData<Recommendations>(_builder.GetRecommendations(artistSeed, genreSeed, trackSeed, target, min, max, limit, market));

}

/// <summary>

/// Create a playlist-style listening experience based on seed artists, tracks and genres asynchronously.

/// </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 attribute’s value can be provided</param>

/// <param name="max">For each tunable track attribute, a hard ceiling on the selected track attribute’s 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 Task<Recommendations> GetRecommendationsAsync(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 = "")

{

return DownloadDataAsync<Recommendations>(_builder.GetRecommendations(artistSeed, genreSeed, trackSeed, target, min, max, limit, market));

}

/// <summary>

/// Retrieve a list of available genres seed parameter values for recommendations.

/// </summary>

/// <returns></returns>

/// <remarks>AUTH NEEDED</remarks>

public RecommendationSeedGenres GetRecommendationSeedsGenres()

{

return DownloadData<RecommendationSeedGenres>(_builder.GetRecommendationSeedsGenres());

}

/// <summary>

/// Retrieve a list of available genres seed parameter values for recommendations asynchronously.

/// </summary>

/// <returns></returns>

/// <remarks>AUTH NEEDED</remarks>

public Task<RecommendationSeedGenres> GetRecommendationSeedsGenresAsync()

{

return DownloadDataAsync<RecommendationSeedGenres>(_builder.GetRecommendationSeedsGenres());

}

#endregion Browse

#region Follow

/// <summary>

/// Get the current user’s followed artists.

/// </summary>

/// <param name="followType">The ID type: currently only artist is supported. </param>

/// <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 FollowedArtists GetFollowedArtists(FollowType followType, int limit = 20, string after = "")

{

if (!UseAuth)

throw new InvalidOperationException("Auth is required for GetFollowedArtists");

return DownloadData<FollowedArtists>(_builder.GetFollowedArtists(limit, after));

}

/// <summary>

/// Get the current user’s followed artists asynchronously.

/// </summary>

/// <param name="followType">The ID type: currently only artist is supported. </param>

/// <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 Task<FollowedArtists> GetFollowedArtistsAsync(FollowType followType, int limit = 20, string after = "")

{

if (!UseAuth)

throw new InvalidOperationException("Auth is required for GetFollowedArtists");

return DownloadDataAsync<FollowedArtists>(_builder.GetFollowedArtists(limit, after));

}

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

/// <param name="ids">A list of the artist or the user Spotify IDs</param>

/// <returns></returns>

/// <remarks>AUTH NEEDED</remarks>

public ErrorResponse Follow(FollowType followType, List<string> ids)

{

JObject ob = new JObject

{

{"ids", new JArray(ids)}

};

return UploadData<ErrorResponse>(_builder.Follow(followType), ob.ToString(Formatting.None), "PUT") ?? new ErrorResponse();

}

/// <summary>

/// Add the current user as a follower of one or more artists or other Spotify users asynchronously.

/// </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</param>

/// <returns></returns>

/// <remarks>AUTH NEEDED</remarks>

public async Task<ErrorResponse> FollowAsync(FollowType followType, List<string> ids)

{

JObject ob = new JObject

{

{"ids", new JArray(ids)}

};

return await UploadDataAsync<ErrorResponse>(_builder.Follow(followType),

ob.ToString(Formatting.None), "PUT").ConfigureAwait(false) ?? new ErrorResponse();

}

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

/// <param name="id">Artists or the Users Spotify ID</param>

/// <returns></returns>

/// <remarks>AUTH NEEDED</remarks>

public ErrorResponse Follow(FollowType followType, string id)

{

return Follow(followType, new List<string> { id });

}

/// <summary>

/// Add the current user as a follower of one or more artists or other Spotify users asynchronously.

/// </summary>

/// <param name="followType">The ID type: either artist or user.</param>

/// <param name="id">Artists or the Users Spotify ID</param>

/// <returns></returns>

/// <remarks>AUTH NEEDED</remarks>

public Task<ErrorResponse> FollowAsync(FollowType followType, string id)

{

return FollowAsync(followType, new List<string> { id });

}

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

/// <param name="ids">A list of the artist or the user Spotify IDs</param>

/// <returns></returns>

/// <remarks>AUTH NEEDED</remarks>

public ErrorResponse Unfollow(FollowType followType, List<string> ids)

{

JObject ob = new JObject

{

{"ids", new JArray(ids)}

};

return UploadData<ErrorResponse>(_builder.Unfollow(followType), ob.ToString(Formatting.None), "DELETE") ?? new ErrorResponse();

}

/// <summary>

/// Remove the current user as a follower of one or more artists or other Spotify users asynchronously.

/// </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</param>

/// <returns></returns>

/// <remarks>AUTH NEEDED</remarks>

public async Task<ErrorResponse> UnfollowAsync(FollowType followType, List<string> ids)

{

JObject ob = new JObject

{

{"ids", new JArray(ids)}

};

return await UploadDataAsync<ErrorResponse>(_builder.Unfollow(followType), ob.ToString(Formatting.None), "DELETE").ConfigureAwait(false) ?? new ErrorResponse();

}

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

/// <param name="id">Artists or the Users Spotify ID</param>

/// <returns></returns>

/// <remarks>AUTH NEEDED</remarks>

public ErrorResponse Unfollow(FollowType followType, string id)

{

return Unfollow(followType, new List<string> { id });

}

/// <summary>

/// Remove the current user as a follower of one or more artists or other Spotify users asynchronously.

/// </summary>

/// <param name="followType">The ID type: either artist or user.</param>

/// <param name="id">Artists or the Users Spotify ID</param>

/// <returns></returns>

/// <remarks>AUTH NEEDED</remarks>

public Task<ErrorResponse> UnfollowAsync(FollowType followType, string id)

{

return UnfollowAsync(followType, new List<string> { id });

}

/// <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 ListResponse<bool> IsFollowing(FollowType followType, List<string> ids)

{

if (!UseAuth)

throw new InvalidOperationException("Auth is required for IsFollowing");

string url = _builder.IsFollowing(followType, ids);

return DownloadList<bool>(url);

}

/// <summary>

/// Check to see if the current user is following one or more artists or other Spotify users asynchronously.

/// </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 Task<ListResponse<bool>> IsFollowingAsync(FollowType followType, List<string> ids)

{

if (!UseAuth)

throw new InvalidOperationException("Auth is required for IsFollowing");

string url = _builder.IsFollowing(followType, ids);

return DownloadListAsync<bool>(url);

}

/// <summary>

/// Check to see if the current user is following one artist or another Spotify user.

/// </summary>

/// <param name="followType">The ID type: either artist or user.</param>

/// <param name="id">Artists or the Users Spotify ID</param>

/// <returns></returns>

/// <remarks>AUTH NEEDED</remarks>

public ListResponse<bool> IsFollowing(FollowType followType, string id)

{

return IsFollowing(followType, new List<string> { id });

}

/// <summary>

/// Check to see if the current user is following one artist or another Spotify user asynchronously.

/// </summary>

/// <param name="followType">The ID type: either artist or user.</param>

/// <param name="id">Artists or the Users Spotify ID</param>

/// <returns></returns>

/// <remarks>AUTH NEEDED</remarks>

public Task<ListResponse<bool>> IsFollowingAsync(FollowType followType, string id)

{

return IsFollowingAsync(followType, new List<string> { id });

}

/// <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 ErrorResponse FollowPlaylist(string ownerId, string playlistId, bool showPublic = true)

{

JObject body = new JObject

{

{"public", showPublic}

};

return UploadData<ErrorResponse>(_builder.FollowPlaylist(ownerId, playlistId, showPublic), body.ToString(Formatting.None), "PUT");

}

/// <summary>

/// Add the current user as a follower of a playlist asynchronously.

/// </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 Task<ErrorResponse> FollowPlaylistAsync(string ownerId, string playlistId, bool showPublic = true)

{

JObject body = new JObject

{

{"public", showPublic}

};

return UploadDataAsync<ErrorResponse>(_builder.FollowPlaylist(ownerId, playlistId, showPublic), body.ToString(Formatting.None), "PUT");

}

/// <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 ErrorResponse UnfollowPlaylist(string ownerId, string playlistId)

{

return UploadData<ErrorResponse>(_builder.UnfollowPlaylist(ownerId, playlistId), "", "DELETE");

}

/// <summary>

/// Remove the current user as a follower of a playlist asynchronously.

/// </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 Task<ErrorResponse> UnfollowPlaylistAsync(string ownerId, string playlistId)

{

return UploadDataAsync<ErrorResponse>(_builder.UnfollowPlaylist(ownerId, playlistId), "", "DELETE");

}

/// <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 ListResponse<bool> IsFollowingPlaylist(string ownerId, string playlistId, List<string> ids)

{

if (!UseAuth)

throw new InvalidOperationException("Auth is required for IsFollowingPlaylist");

string url = _builder.IsFollowingPlaylist(ownerId, playlistId, ids);

return DownloadList<bool>(url);

}

/// <summary>

/// Check to see if one or more Spotify users are following a specified playlist asynchronously.

/// </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 Task<ListResponse<bool>> IsFollowingPlaylistAsync(string ownerId, string playlistId, List<string> ids)

{

if (!UseAuth)

throw new InvalidOperationException("Auth is required for IsFollowingPlaylist");

string url = _builder.IsFollowingPlaylist(ownerId, playlistId, ids);

return DownloadListAsync<bool>(url);

}

/// <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="id">A Spotify User ID</param>

/// <returns></returns>

/// <remarks>AUTH NEEDED</remarks>

public ListResponse<bool> IsFollowingPlaylist(string ownerId, string playlistId, string id)

{

return IsFollowingPlaylist(ownerId, playlistId, new List<string> { id });

}

/// <summary>

/// Check to see if one or more Spotify users are following a specified playlist asynchronously.

/// </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="id">A Spotify User ID</param>

/// <returns></returns>

/// <remarks>AUTH NEEDED</remarks>

public Task<ListResponse<bool>> IsFollowingPlaylistAsync(string ownerId, string playlistId, string id)

{

return IsFollowingPlaylistAsync(ownerId, playlistId, new List<string> { id });

}

#endregion Follow

#region Library

/// <summary>

/// Save one or more tracks to the current user’s “Your Music” library.

/// </summary>

/// <param name="ids">A list of the Spotify IDs</param>

/// <returns></returns>

/// <remarks>AUTH NEEDED</remarks>

public ErrorResponse SaveTracks(List<string> ids)

{

JArray array = new JArray(ids);

return UploadData<ErrorResponse>(_builder.SaveTracks(), array.ToString(Formatting.None), "PUT") ?? new ErrorResponse();

}

/// <summary>

/// Save one or more tracks to the current user’s “Your Music” library asynchronously.

/// </summary>

/// <param name="ids">A list of the Spotify IDs</param>

/// <returns></returns>

/// <remarks>AUTH NEEDED</remarks>

public async Task<ErrorResponse> SaveTracksAsync(List<string> ids)

{

JArray array = new JArray(ids);

return await UploadDataAsync<ErrorResponse>(_builder.SaveTracks(), array.ToString(Formatting.None), "PUT").ConfigureAwait(false) ?? new ErrorResponse();

}

/// <summary>

/// Save one track to the current user’s “Your Music” library.

/// </summary>

/// <param name="id">A Spotify ID</param>

/// <returns></returns>

/// <remarks>AUTH NEEDED</remarks>

public ErrorResponse SaveTrack(string id)

{

return SaveTracks(new List<string> { id });

}

/// <summary>

/// Save one track to the current user’s “Your Music” library asynchronously.

/// </summary>

/// <param name="id">A Spotify ID</param>

/// <returns></returns>

/// <remarks>AUTH NEEDED</remarks>

public Task<ErrorResponse> SaveTrackAsync(string id)

{

return SaveTracksAsync(new List<string> { id });

}