Spotify Web API
  1. category-browse
Spotify Web API
  • category-albums
    • Get Multiple Albums
      GET
    • Get an Album
      GET
    • Get an Album's Tracks
      GET
  • category-artists
    • Get Multiple Artists
      GET
    • Get an Artist
      GET
    • Get an Artist's Albums
      GET
    • Get an Artist's Related Artists
      GET
    • Get an Artist's Top Tracks
      GET
  • category-tracks
    • Get Audio Analysis for a Track
      GET
    • Get Audio Features for Several Tracks
      GET
    • Get Audio Features for a Track
      GET
    • Get Several Tracks
      GET
    • Get a Track
      GET
  • category-browse
    • Get All Categories
      GET
    • Get a Category
      GET
    • Get a Category's Playlists
      GET
    • Get All Featured Playlists
      GET
    • Get All New Releases
      GET
    • Get Recommendations
      GET
    • Get Recommendation Genres
      GET
  • category-episodes
    • Get Multiple Episodes
      GET
    • Get an Episode
      GET
  • category-markets
    • Get Available Markets
      GET
  • category-users-profile
    • Get Current User's Profile
    • Get a User's Profile
  • category-library
    • Remove Albums for Current User
    • Get User's Saved Albums
    • Save Albums for Current User
    • Check User's Saved Albums
    • Remove User's Saved Episodes
    • Get User's Saved Episodes
    • Save Episodes for User
    • Check User's Saved Episodes
    • Remove User's Saved Shows
    • Get User's Saved Shows
    • Save Shows for Current User
    • Check User's Saved Shows
    • Remove User's Saved Tracks
    • Get User's Saved Tracks
    • Save Tracks for User
    • Check User's Saved Tracks
  • category-follow
    • Unfollow Artists or Users
    • Get User's Followed Artists
    • Follow Artists or Users
    • Get Following State for Artists/Users
    • Unfollow Playlist
    • Follow a Playlist
    • Check if Users Follow a Playlist
  • category-player
    • Get Information About The User's Current Playback
    • Transfer a User's Playback
    • Get the User's Currently Playing Track
    • Get a User's Available Devices
    • Skip User’s Playback To Next Track
    • Pause a User's Playback
    • Start/Resume a User's Playback
    • Skip User’s Playback To Previous Track
    • Add an item to queue
    • Get Current User's Recently Played Tracks
    • Set Repeat Mode On User’s Playback
    • Seek To Position In Currently Playing Track
    • Toggle Shuffle For User’s Playback
    • Set Volume For User's Playback
  • category-playlists
    • Get a List of Current User's Playlists
    • Get a Playlist
    • Change a Playlist's Details
    • Get a Playlist Cover Image
    • Upload a Custom Playlist Cover Image
    • Remove Items from a Playlist
    • Get a Playlist's Items
    • Add Items to a Playlist
    • Reorder or Replace a Playlist's Items
    • Get a List of a User's Playlists
    • Create a Playlist
  • category-personalization
    • Get a User's Top Artists and Tracks
  • category-search
    • Search for an Item
  • category-shows
    • Get Multiple Shows
    • Get a Show
    • Get a Show's Episodes
  1. category-browse

Get Recommendations

Developing
GET
/recommendations
category-browse
Recommendations are generated based on the available information for a given seed entity and matched against similar artists and tracks. If there is sufficient information about the provided seeds, a list of tracks will be returned together with pool size details.
Request Request Example
Shell
JavaScript
Java
Swift
curl --location --request GET 'https://api.spotify.com/v1/recommendations?seed_artists=&seed_genres=&seed_tracks=' \
--header 'Authorization;'
Response Response Example
200 - Example 1
{
  "seeds": [
    {
      "afterFilteringSize": 0,
      "afterRelinkingSize": 0,
      "href": "string",
      "id": "string",
      "initialPoolSize": 0,
      "type": "string"
    }
  ],
  "tracks": [
    {
      "album": {
        "album_group": "string",
        "album_type": "string",
        "artists": [
          {
            "external_urls": {
              "spotify": "string"
            },
            "href": "string",
            "id": "string",
            "name": "string",
            "type": "string",
            "uri": "string"
          }
        ],
        "available_markets": [
          "string"
        ],
        "external_urls": {
          "spotify": "string"
        },
        "href": "string",
        "id": "string",
        "images": [
          {
            "height": 0,
            "url": "string",
            "width": 0
          }
        ],
        "name": "string",
        "release_date": "string",
        "release_date_precision": "string",
        "restrictions": {
          "reason": "string"
        },
        "total_tracks": 0,
        "type": "string",
        "uri": "string"
      },
      "artists": [
        {
          "external_urls": {
            "spotify": "string"
          },
          "followers": {
            "href": "string",
            "total": 0
          },
          "genres": [
            "string"
          ],
          "href": "string",
          "id": "string",
          "images": [
            {
              "height": 0,
              "url": "string",
              "width": 0
            }
          ],
          "name": "string",
          "popularity": 0,
          "type": "string",
          "uri": "string"
        }
      ],
      "available_markets": [
        "string"
      ],
      "disc_number": 0,
      "duration_ms": 0,
      "explicit": true,
      "external_ids": {
        "ean": "string",
        "isrc": "string",
        "upc": "string"
      },
      "external_urls": {
        "spotify": "string"
      },
      "href": "string",
      "id": "string",
      "is_local": true,
      "is_playable": true,
      "linked_from": {
        "external_urls": {
          "spotify": "string"
        },
        "href": "string",
        "id": "string",
        "type": "string",
        "uri": "string"
      },
      "name": "string",
      "popularity": 0,
      "preview_url": "string",
      "restrictions": {
        "reason": "string"
      },
      "track_number": 0,
      "type": "string",
      "uri": "string"
    }
  ]
}

Request

Query Params
limit
integer 
optional
The target size of the list of recommended tracks. 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. Debugging information for such cases is available in the response. Default: 20. Minimum: 1. Maximum: 100.
market
string 
optional
An ISO 3166-1 alpha-2 country code or the string from_token. 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. Original, non-relinked tracks are available via the linked_from attribute of the relinked track response.
seed_artists
string 
required
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.
seed_genres
string 
required
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.
seed_tracks
string 
required
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.
min_acousticness
number 
optional
For each tunable track attribute, a hard floor on the selected track attribute's value can be provided. See tunable track attributes below for the list of available options. For example, min_tempo=140 would restrict results to only those tracks with a tempo of greater than 140 beats per minute.
max_acousticness
number 
optional
For each tunable track attribute, a hard ceiling on the selected track attribute's value can be provided. See tunable track attributes below for the list of available options. For example, max_instrumentalness=0.35 would filter out most tracks that are likely to be instrumental.
target_acousticness
number 
optional
For each of the tunable track attributes (below) a target value may be provided. Tracks with the attribute values nearest to the target values will be preferred. For example, you might request target_energy=0.6 and target_danceability=0.8. All target values will be weighed equally in ranking results.
min_danceability
number 
optional
For each tunable track attribute, a hard floor on the selected track attribute's value can be provided. See tunable track attributes below for the list of available options. For example, min_tempo=140 would restrict results to only those tracks with a tempo of greater than 140 beats per minute.
max_danceability
number 
optional
For each tunable track attribute, a hard ceiling on the selected track attribute's value can be provided. See tunable track attributes below for the list of available options. For example, max_instrumentalness=0.35 would filter out most tracks that are likely to be instrumental.
target_danceability
number 
optional
For each of the tunable track attributes (below) a target value may be provided. Tracks with the attribute values nearest to the target values will be preferred. For example, you might request target_energy=0.6 and target_danceability=0.8. All target values will be weighed equally in ranking results.
min_duration_ms
integer 
optional
For each tunable track attribute, a hard floor on the selected track attribute's value can be provided. See tunable track attributes below for the list of available options. For example, min_tempo=140 would restrict results to only those tracks with a tempo of greater than 140 beats per minute.
max_duration_ms
integer 
optional
For each tunable track attribute, a hard ceiling on the selected track attribute's value can be provided. See tunable track attributes below for the list of available options. For example, max_instrumentalness=0.35 would filter out most tracks that are likely to be instrumental.
target_duration_ms
integer 
optional
Target duration of the track (ms)
min_energy
number 
optional
For each tunable track attribute, a hard floor on the selected track attribute's value can be provided. See tunable track attributes below for the list of available options. For example, min_tempo=140 would restrict results to only those tracks with a tempo of greater than 140 beats per minute.
max_energy
number 
optional
For each tunable track attribute, a hard ceiling on the selected track attribute's value can be provided. See tunable track attributes below for the list of available options. For example, max_instrumentalness=0.35 would filter out most tracks that are likely to be instrumental.
target_energy
number 
optional
For each of the tunable track attributes (below) a target value may be provided. Tracks with the attribute values nearest to the target values will be preferred. For example, you might request target_energy=0.6 and target_danceability=0.8. All target values will be weighed equally in ranking results.
min_instrumentalness
number 
optional
For each tunable track attribute, a hard floor on the selected track attribute's value can be provided. See tunable track attributes below for the list of available options. For example, min_tempo=140 would restrict results to only those tracks with a tempo of greater than 140 beats per minute.
max_instrumentalness
number 
optional
For each tunable track attribute, a hard ceiling on the selected track attribute's value can be provided. See tunable track attributes below for the list of available options. For example, max_instrumentalness=0.35 would filter out most tracks that are likely to be instrumental.
target_instrumentalness
number 
optional
For each of the tunable track attributes (below) a target value may be provided. Tracks with the attribute values nearest to the target values will be preferred. For example, you might request target_energy=0.6 and target_danceability=0.8. All target values will be weighed equally in ranking results.
min_key
integer 
optional
For each tunable track attribute, a hard floor on the selected track attribute's value can be provided. See tunable track attributes below for the list of available options. For example, min_tempo=140 would restrict results to only those tracks with a tempo of greater than 140 beats per minute.
max_key
integer 
optional
For each tunable track attribute, a hard ceiling on the selected track attribute's value can be provided. See tunable track attributes below for the list of available options. For example, max_instrumentalness=0.35 would filter out most tracks that are likely to be instrumental.
target_key
integer 
optional
For each of the tunable track attributes (below) a target value may be provided. Tracks with the attribute values nearest to the target values will be preferred. For example, you might request target_energy=0.6 and target_danceability=0.8. All target values will be weighed equally in ranking results.
min_liveness
number 
optional
For each tunable track attribute, a hard floor on the selected track attribute's value can be provided. See tunable track attributes below for the list of available options. For example, min_tempo=140 would restrict results to only those tracks with a tempo of greater than 140 beats per minute.
max_liveness
number 
optional
For each tunable track attribute, a hard ceiling on the selected track attribute's value can be provided. See tunable track attributes below for the list of available options. For example, max_instrumentalness=0.35 would filter out most tracks that are likely to be instrumental.
target_liveness
number 
optional
For each of the tunable track attributes (below) a target value may be provided. Tracks with the attribute values nearest to the target values will be preferred. For example, you might request target_energy=0.6 and target_danceability=0.8. All target values will be weighed equally in ranking results.
min_loudness
number 
optional
For each tunable track attribute, a hard floor on the selected track attribute's value can be provided. See tunable track attributes below for the list of available options. For example, min_tempo=140 would restrict results to only those tracks with a tempo of greater than 140 beats per minute.
max_loudness
number 
optional
For each tunable track attribute, a hard ceiling on the selected track attribute's value can be provided. See tunable track attributes below for the list of available options. For example, max_instrumentalness=0.35 would filter out most tracks that are likely to be instrumental.
target_loudness
number 
optional
For each of the tunable track attributes (below) a target value may be provided. Tracks with the attribute values nearest to the target values will be preferred. For example, you might request target_energy=0.6 and target_danceability=0.8. All target values will be weighed equally in ranking results.
min_mode
integer 
optional
For each tunable track attribute, a hard floor on the selected track attribute's value can be provided. See tunable track attributes below for the list of available options. For example, min_tempo=140 would restrict results to only those tracks with a tempo of greater than 140 beats per minute.
max_mode
integer 
optional
For each tunable track attribute, a hard ceiling on the selected track attribute's value can be provided. See tunable track attributes below for the list of available options. For example, max_instrumentalness=0.35 would filter out most tracks that are likely to be instrumental.
target_mode
integer 
optional
For each of the tunable track attributes (below) a target value may be provided. Tracks with the attribute values nearest to the target values will be preferred. For example, you might request target_energy=0.6 and target_danceability=0.8. All target values will be weighed equally in ranking results.
min_popularity
integer 
optional
For each tunable track attribute, a hard floor on the selected track attribute's value can be provided. See tunable track attributes below for the list of available options. For example, min_tempo=140 would restrict results to only those tracks with a tempo of greater than 140 beats per minute.
max_popularity
integer 
optional
For each tunable track attribute, a hard ceiling on the selected track attribute's value can be provided. See tunable track attributes below for the list of available options. For example, max_instrumentalness=0.35 would filter out most tracks that are likely to be instrumental.
target_popularity
integer 
optional
For each of the tunable track attributes (below) a target value may be provided. Tracks with the attribute values nearest to the target values will be preferred. For example, you might request target_energy=0.6 and target_danceability=0.8. All target values will be weighed equally in ranking results.
min_speechiness
number 
optional
For each tunable track attribute, a hard floor on the selected track attribute's value can be provided. See tunable track attributes below for the list of available options. For example, min_tempo=140 would restrict results to only those tracks with a tempo of greater than 140 beats per minute.
max_speechiness
number 
optional
For each tunable track attribute, a hard ceiling on the selected track attribute's value can be provided. See tunable track attributes below for the list of available options. For example, max_instrumentalness=0.35 would filter out most tracks that are likely to be instrumental.
target_speechiness
number 
optional
For each of the tunable track attributes (below) a target value may be provided. Tracks with the attribute values nearest to the target values will be preferred. For example, you might request target_energy=0.6 and target_danceability=0.8. All target values will be weighed equally in ranking results.
min_tempo
number 
optional
For each tunable track attribute, a hard floor on the selected track attribute's value can be provided. See tunable track attributes below for the list of available options. For example, min_tempo=140 would restrict results to only those tracks with a tempo of greater than 140 beats per minute.
max_tempo
number 
optional
For each tunable track attribute, a hard ceiling on the selected track attribute's value can be provided. See tunable track attributes below for the list of available options. For example, max_instrumentalness=0.35 would filter out most tracks that are likely to be instrumental.
target_tempo
number 
optional
Target tempo (BPM)
min_time_signature
integer 
optional
For each tunable track attribute, a hard floor on the selected track attribute's value can be provided. See tunable track attributes below for the list of available options. For example, min_tempo=140 would restrict results to only those tracks with a tempo of greater than 140 beats per minute.
max_time_signature
integer 
optional
For each tunable track attribute, a hard ceiling on the selected track attribute's value can be provided. See tunable track attributes below for the list of available options. For example, max_instrumentalness=0.35 would filter out most tracks that are likely to be instrumental.
target_time_signature
integer 
optional
For each of the tunable track attributes (below) a target value may be provided. Tracks with the attribute values nearest to the target values will be preferred. For example, you might request target_energy=0.6 and target_danceability=0.8. All target values will be weighed equally in ranking results.
min_valence
number 
optional
For each tunable track attribute, a hard floor on the selected track attribute's value can be provided. See tunable track attributes below for the list of available options. For example, min_tempo=140 would restrict results to only those tracks with a tempo of greater than 140 beats per minute.
max_valence
number 
optional
For each tunable track attribute, a hard ceiling on the selected track attribute's value can be provided. See tunable track attributes below for the list of available options. For example, max_instrumentalness=0.35 would filter out most tracks that are likely to be instrumental.
target_valence
number 
optional
For each of the tunable track attributes (below) a target value may be provided. Tracks with the attribute values nearest to the target values will be preferred. For example, you might request target_energy=0.6 and target_danceability=0.8. All target values will be weighed equally in ranking results.
Header Params
Authorization
string 
required
A valid user access token or your client credentials.

Responses

🟢200On success, the HTTP status code in the response header is `200 OK` and the response body contains a recommendations response object in JSON format.
application/json
Body
seeds
array[object (RecommendationSeedObject) {6}] 
optional
An array of recommendation seed objects.
afterFilteringSize
integer <int32>
optional
The number of tracks available after min_* and max_* filters have been applied.
afterRelinkingSize
integer <int32>
optional
The number of tracks available after relinking for regional availability.
href
string 
optional
A link to the full track or artist data for this seed. For tracks this will be a link to a Track Object. For artists a link to an Artist Object. For genre seeds, this value will be null.
id
string 
optional
The id used to select this seed. This will be the same as the string used in the seed_artists, seed_tracks or seed_genres parameter.
initialPoolSize
integer <int32>
optional
The number of recommended tracks available for this seed.
type
string 
optional
The entity type of this seed. One of artist, track or genre.
tracks
array[object (TrackObject) {20}] 
optional
An array of track object ordered according to the parameters supplied.
album
object (SimplifiedAlbumObject) 
optional
artists
array[object (ArtistObject) {10}] 
optional
The artists who performed the track. Each artist object includes a link in href to more detailed information about the artist.
available_markets
array[string]
optional
A list of the countries in which the track can be played, identified by their ISO 3166-1 alpha-2 code.
disc_number
integer <int32>
optional
The disc number (usually 1 unless the album consists of more than one disc).
duration_ms
integer <int32>
optional
The track length in milliseconds.
explicit
boolean 
optional
Whether or not the track has explicit lyrics ( true = yes it does; false = no it does not OR unknown).
external_ids
object (ExternalIdObject) 
optional
external_urls
object (ExternalUrlObject) 
optional
href
string 
optional
A link to the Web API endpoint providing full details of the track.
id
string 
optional
The Spotify ID for the track.
is_local
boolean 
optional
Whether or not the track is from a local file.
is_playable
boolean 
optional
Part of the response when Track Relinking is applied. If true , the track is playable in the given market. Otherwise false.
linked_from
object (LinkedTrackObject) 
optional
name
string 
optional
The name of the track.
popularity
integer <int32>
optional
The popularity of the track. The value will be between 0 and 100, with 100 being the most popular.
The popularity of a track is a value between 0 and 100, with 100 being the most popular. The popularity is calculated by algorithm and is based, in the most part, on the total number of plays the track has had and how recent those plays are.
Generally speaking, songs that are being played a lot now will have a higher popularity than songs that were played a lot in the past. Duplicate tracks (e.g. the same track from a single and an album) are rated independently. Artist and album popularity is derived mathematically from track popularity. Note that the popularity value may lag actual popularity by a few days: the value is not updated in real time.
preview_url
string 
optional
A link to a 30 second preview (MP3 format) of the track. Can be null
restrictions
object (TrackRestrictionObject) 
optional
track_number
integer <int32>
optional
The number of the track. If an album has several discs, the track number is the number on the specified disc.
type
string 
optional
The object type: "track".
uri
string 
optional
The Spotify URI for the track.
🔴500500
Modified at 2022-09-12 10:04:50
Previous
Get All New Releases
Next
Get Recommendation Genres
Built with