Services Provided

The following custom services are provided by this integration.

• Add Player Queue Items
• Check Album Favorites
• Check Artists Following
• Check Audiobook Favorites
• Check Episode Favorites
• Check Playlist Followers
• Check Show Favorites
• Check Track Favorites
• Check Users Following
• Follow Artists
• Follow Playlist
• Follow Users
• Get Album
• Get Album Favorites
• Get Album New Releases
• Get Artist
• Get Artist Albums
• Get Artist Info
• Get Artist Related Artists
• Get Artists Followed
• Get Audiobook
• Get Audiobook Chapters
• Get Audiobook Favorites
• Get Browse Categories
• Get Category Playlists
• Get Chapter
• Get Episode
• Get Episode Favorites
• Get Featured Playlists
• Get Player Devices
• Get Player Now Playing
• Get Player Playback State
• Get Player Queue Info
• Get Player Recent Tracks
• Get Playlist
• Get Playlist Cover Image
• Get Playlist Favorites
• Get Playlist Items
• Get Playlists For User
• Get Show
• Get Show Episodes
• Get Show Favorites
• Get Spotify Connect Device
• Get Spotify Connect Devices
• Get Track
• Get Track Favorites
• Get Track Recommendations
• Get Tracks Audio Features
• Get Users Top Artists
• Get Users Top Tracks
• Player Activate Devices
• Player Media Pause
• Player Media Play Context
• Player Media Play Track Favorites
• Player Media Play Tracks
• Player Media Resume
• Player Media Seek
• Player Media Skip Next
• Player Media Skip Previous
• Player Resolve Device Id
• Player Set Repeat Mode
• Player Set Shuffle Mode
• Player Set Volume Level
• Player Transfer Playback
• Playlist Change
• Playlist Cover Image Add
• Playlist Create
• Playlist Items Add
• Playlist Items Clear
• Playlist Items Remove
• Playlist Items Reorder
• Playlist Items Replace
• Remove Album Favorites
• Remove Audiobook Favorites
• Remove Episode Favorites
• Remove Show Favorites
• Remove Track Favorites
• Replace Playlist Items
• Save Album Favorites
• Save Audiobook Favorites
• Save Episode Favorites
• Save Show Favorites
• Save Track Favorites
• Search Albums
• Search Artists
• Search Audiobooks
• Search Episodes
• Search Playlists
• Search Shows
• Search Tracks
• Unfollow Artists
• Unfollow Playlist
• Unfollow Users
• ZeroConf Device Connect
• ZeroConf Device Disconnect
• ZeroConf Device GetInformation
• ZeroConf Discover Devices

Add Player Queue Items

Add one or more items to the end of the user's current Spotify Player playback queue.

Parameters

All parameters are required unless otherwise noted.

• entity_id - Entity ID of the SpotifyPlus service that will make the request to the Spotify Web API.
• uris - A list of Spotify track or episode URIs to add to the queue (spotify:track:6zd8T1PBe9JFHmuVnurdRp, spotify:track:1kWUud3vY5ij5r62zxpTRy); values can be track or episode URIs. All URIs must be of the same type - you cannot mix and match tracks and episodes. An unlimited number of items can be added in one request, but the more items the longer it will take.
• device_id (optional) - The id or name of the Spotify Connect Player device this command is targeting. If not supplied, the user's currently active device is the target. If no device is active (or an '*' is specified), then the SpotifyPlus default device is activated.
• verify_device_id (optional) - True to verify a device id is active; otherwise, false to assume that a device id is already active. Default is True.
• delay (optional) - Time delay (in seconds) to wait AFTER issuing the add request (if necessary). This delay will give the spotify web api time to process the change before another command is issued. Default is 0.15; value range is 0 - 10.

Example YAML

Add track to current player play queue.

service: spotifyplus.add_player_queue_items
data:
  entity_id: media_player.spotifyplus_john_s
  uris: spotify:track:6zd8T1PBe9JFHmuVnurdRp

Add episode to current player play queue.

service: spotifyplus.add_player_queue_items
data:
  entity_id: media_player.spotifyplus_john_s
  uris: spotify:episode:512ojhOuo1ktJprKbVcKyQ

Check Album Favorites

Check if one or more albums (or the currently playing album) exists in the current user's 'Your Library' favorites.

This service will return service response data.

Parameters

All parameters are required unless otherwise noted.

• entity_id - Entity ID of the SpotifyPlus service that will make the request to the Spotify Web API.
• ids (optional) - A comma-separated list of Spotify album id's (e.g. 6vc9OTcyd3hyzabCmsdnwE,382ObEPsp2rxGrnsizN5TX). A maximum of 50 id's may be specified. If omitted, the currently playing track album uri id value is used.

Example YAML

Check if specified albums are in current user favorites.

service: spotifyplus.check_album_favorites
data:
  entity_id: media_player.spotifyplus_john_s
  ids: 6vc9OTcyd3hyzabCmsdnwE,382ObEPsp2rxGrnsizN5TX

Check if nowplaying playing album is in current user favorites.

service: spotifyplus.check_album_favorites
data:
  entity_id: media_player.spotifyplus_john_s

Example Response

A dictionary that contains the following keys:

• user_profile: A (partial) user profile that retrieved the result.
• result: A dictionary of the ids, along with a boolean status for each that indicates if the album is saved (True) in the users 'Your Library' or not (False).

user_profile:
  country: US
  display_name: John Smith
  email: jsmith@maildomain.com
  id: 3758dfdsfjk435hjk6k79lm0n3c4
  product: premium
  type: user
  uri: spotify:user:3758dfdsfjk435hjk6k79lm0n3c4
result:
  6vc9OTcyd3hyzabCmsdnwE: true
  382ObEPsp2rxGrnsizN5TX: false

Check Artists Following

Check if one or more artists (or the currently playing artist) is followed in the current user's 'Your Library' favorites.

This service will return service response data.

Parameters

All parameters are required unless otherwise noted.

• entity_id - Entity ID of the SpotifyPlus service that will make the request to the Spotify Web API.
• ids (optional) - A comma-separated list of Spotify album id's (e.g. 2CIMQHirSU0MQqyYHq0eOx,1IQ2e1buppatiN1bxUVkrk). A maximum of 50 id's may be specified. If omitted, the currently playing artist uri id value is used.

Example YAML

Check if specified albums are in current user favorites.

service: spotifyplus.check_artists_following
data:
  entity_id: media_player.spotifyplus_john_s
  ids: 2CIMQHirSU0MQqyYHq0eOx,1IQ2e1buppatiN1bxUVkrk

Check if nowplaying playing artist is in current user favorites.

service: spotifyplus.check_artists_following
data:
  entity_id: media_player.spotifyplus_john_s

Example Response

A dictionary that contains the following keys:

• user_profile: A (partial) user profile that retrieved the result.
• result: A dictionary of the ids, along with a boolean status for each that indicates if the album is saved (True) in the users 'Your Library' or not (False).

user_profile:
  country: US
  display_name: John Smith
  email: jsmith@maildomain.com
  id: 3758dfdsfjk435hjk6k79lm0n3c4
  product: premium
  type: user
  uri: spotify:user:3758dfdsfjk435hjk6k79lm0n3c4
result:
  2CIMQHirSU0MQqyYHq0eOx: true
  1IQ2e1buppatiN1bxUVkrk: true

Check Audiobook Favorites

Check if one or more audiobooks (or the currently playing audiobook) exists in the current user's 'Your Library' favorites.

This service will return service response data.

Parameters

All parameters are required unless otherwise noted.

• entity_id - Entity ID of the SpotifyPlus service that will make the request to the Spotify Web API.
• ids (optional) - A comma-separated list of Spotify audiobook id's (e.g. 3PFyizE2tGCSRLusl2Qizf,7iHfbu1YPACw6oZPAFJtqe). A maximum of 50 id's may be specified. If omitted, the currently playing audiobook uri id value is used.

Example YAML

Check if specified audiobooks are in current user favorites.

service: spotifyplus.check_audiobook_favorites
data:
  entity_id: media_player.spotifyplus_john_s
  ids: 3PFyizE2tGCSRLusl2Qizf,7iHfbu1YPACw6oZPAFJtqe

Check if nowplaying playing audiobook is in current user favorites.

service: spotifyplus.check_audiobook_favorites
data:
  entity_id: media_player.spotifyplus_john_s

Example Response

A dictionary that contains the following keys:

• user_profile: A (partial) user profile that retrieved the result.
• result: A dictionary of the ids, along with a boolean status for each that indicates if the album is saved (True) in the users 'Your Library' or not (False).

user_profile:
  country: US
  display_name: John Smith
  email: jsmith@maildomain.com
  id: 3758dfdsfjk435hjk6k79lm0n3c4
  product: premium
  type: user
  uri: spotify:user:3758dfdsfjk435hjk6k79lm0n3c4
result:
  3PFyizE2tGCSRLusl2Qizf: true
  7iHfbu1YPACw6oZPAFJtqe: true

Check Episode Favorites

Check if one or more episodes (or the currently playing episode) exists in the current user's 'Your Library' favorites.

This service will return service response data.

Parameters

All parameters are required unless otherwise noted.

• entity_id - Entity ID of the SpotifyPlus service that will make the request to the Spotify Web API.
• ids (optional) - A comma-separated list of Spotify episode id's (e.g. 3PFyizE2tGCSRLusl2Qizf,7iHfbu1YPACw6oZPAFJtqe). A maximum of 50 id's may be specified. If omitted, the currently playing episode uri id value is used.

Example YAML

Check if specified episodes are in current user favorites.

service: spotifyplus.check_episode_favorites
data:
  entity_id: media_player.spotifyplus_john_s
  ids: 3PFyizE2tGCSRLusl2Qizf,7iHfbu1YPACw6oZPAFJtqe

Check if nowplaying playing episode is in current user favorites.

service: spotifyplus.check_episode_favorites
data:
  entity_id: media_player.spotifyplus_john_s

Example Response

A dictionary that contains the following keys:

• user_profile: A (partial) user profile that retrieved the result.
• result: A dictionary of the ids, along with a boolean status for each that indicates if the album is saved (True) in the users 'Your Library' or not (False).

user_profile:
  country: US
  display_name: John Smith
  email: jsmith@maildomain.com
  id: 3758dfdsfjk435hjk6k79lm0n3c4
  product: premium
  type: user
  uri: spotify:user:3758dfdsfjk435hjk6k79lm0n3c4
result:
  3PFyizE2tGCSRLusl2Qizf: false
  7iHfbu1YPACw6oZPAFJtqe: false

Check Playlist Followers

Check to see if the current user is following a specified playlist.

This service will return service response data.

Parameters

All parameters are required unless otherwise noted.

• entity_id - Entity ID of the SpotifyPlus service that will make the request to the Spotify Web API.
• playlist_id - The Spotify ID of the playlist (e.g. 3cEYpjA9oz9GiPac4AsH4n).
• user_ids (optional, Deprecated) - must contain the current user's Spotify Username; Maximum of 1 id. Omit to default to current user name.

Example YAML

Check if specified playlist is followed by the current user.

service: spotifyplus.check_playlist_followers
data:
  entity_id: media_player.spotifyplus_john_s
  playlist_id: 3cEYpjA9oz9GiPac4AsH4n

Example Response

A dictionary that contains the following keys:

• user_profile: A (partial) user profile that retrieved the result.
• result: A dictionary of the ids, along with a boolean status for each that indicates if the album is saved (True) in the users 'Your Library' or not (False).

user_profile:
  country: US
  display_name: John Smith
  email: jsmith@maildomain.com
  id: 3758dfdsfjk435hjk6k79lm0n3c4
  product: premium
  type: user
  uri: spotify:user:3758dfdsfjk435hjk6k79lm0n3c4
result:
  31l77y2al5lnn7mxfrmd4bpfhqke: false

Check Show Favorites

Check if one or more shows (or the currently playing show) exists in the current user's 'Your Library' favorites.

This service will return service response data.

Parameters

All parameters are required unless otherwise noted.

• entity_id - Entity ID of the SpotifyPlus service that will make the request to the Spotify Web API.
• ids (optional) - A comma-separated list of Spotify show id's (e.g. 6kAsbP8pxwaU2kPibKTuHE,4rOoJ6Egrf8K2IrywzwOMk). A maximum of 50 id's may be specified. If omitted, the currently playing show uri id value is used.

Example YAML

Check if specified shows are in current user favorites.

service: spotifyplus.check_show_favorites
data:
  entity_id: media_player.spotifyplus_john_s
  ids: 6kAsbP8pxwaU2kPibKTuHE,4rOoJ6Egrf8K2IrywzwOMk

Check if nowplaying playing show is in current user favorites.

service: spotifyplus.check_show_favorites
data:
  entity_id: media_player.spotifyplus_john_s

Example Response

A dictionary that contains the following keys:

• user_profile: A (partial) user profile that retrieved the result.
• result: A dictionary of the ids, along with a boolean status for each that indicates if the album is saved (True) in the users 'Your Library' or not (False).

user_profile:
  country: US
  display_name: John Smith
  email: jsmith@maildomain.com
  id: 3758dfdsfjk435hjk6k79lm0n3c4
  product: premium
  type: user
  uri: spotify:user:3758dfdsfjk435hjk6k79lm0n3c4
result:
  6kAsbP8pxwaU2kPibKTuHE: true
  4rOoJ6Egrf8K2IrywzwOMk: true

Check Track Favorites

Check if one or more tracks (or the currently playing track) exists in the current user's 'Your Library' favorites.

This service will return service response data.

Parameters

All parameters are required unless otherwise noted.

• entity_id - Entity ID of the SpotifyPlus service that will make the request to the Spotify Web API.
• ids (optional) - A comma-separated list of Spotify track id's (e.g. 1kWUud3vY5ij5r62zxpTRy,4eoYKv2kDwJS7gRGh5q6SK). A maximum of 50 id's may be specified. If omitted, the currently playing track uri id value is used.

Example YAML

Check if specified tracks are in current user favorites.

service: spotifyplus.check_track_favorites
data:
  entity_id: media_player.spotifyplus_john_s
  ids: 1kWUud3vY5ij5r62zxpTRy,4eoYKv2kDwJS7gRGh5q6SK

Check if nowplaying playing track is in current user favorites.

service: spotifyplus.check_track_favorites
data:
  entity_id: media_player.spotifyplus_john_s

Example Response

A dictionary that contains the following keys:

• user_profile: A (partial) user profile that retrieved the result.
• result: A dictionary of the ids, along with a boolean status for each that indicates if the album is saved (True) in the users 'Your Library' or not (False).

user_profile:
  country: US
  display_name: John Smith
  email: jsmith@maildomain.com
  id: 3758dfdsfjk435hjk6k79lm0n3c4
  product: premium
  type: user
  uri: spotify:user:3758dfdsfjk435hjk6k79lm0n3c4
result:
  1kWUud3vY5ij5r62zxpTRy: true
  4eoYKv2kDwJS7gRGh5q6SK: false

Check Users Following

Check to see if the current user is following one or more users.

This service will return service response data.

Parameters

All parameters are required unless otherwise noted.

• entity_id - Entity ID of the SpotifyPlus service that will make the request to the Spotify Web API.
• ids - A comma-separated list of Spotify user ID's to check (e.g. smedjan, smedjan123). A maximum of 50 ID's can be specified.

Example YAML

Check if specified albums are in current user favorites.

service: spotifyplus.check_users_following
data:
  entity_id: media_player.spotifyplus_john_s
  ids: smedjan, smedjan123

Example Response

A dictionary that contains the following keys:

• user_profile: A (partial) user profile that retrieved the result.
• result: A dictionary of the ids, along with a boolean status for each that indicates if the album is saved (True) in the users 'Your Library' or not (False).

user_profile:
  country: US
  display_name: John Smith
  email: jsmith@maildomain.com
  id: 3758dfdsfjk435hjk6k79lm0n3c4
  product: premium
  type: user
  uri: spotify:user:3758dfdsfjk435hjk6k79lm0n3c4
result:
  smedjan: true
  7piUznRWxNyKpaPvmOSdiZ: true

Follow Artists

Add the current user as a follower of one or more artists.

Parameters

All parameters are required unless otherwise noted.

• entity_id - Entity ID of the SpotifyPlus service that will make the request to the Spotify Web API.
• ids (optional) - A comma-separated list of Spotify artist id's (e.g. 2CIMQHirSU0MQqyYHq0eOx,1IQ2e1buppatiN1bxUVkrk). A maximum of 50 id's may be specified. If omitted, the currently playing track artist uri id value is used.

Example YAML

Follow the specified artists.

service: spotifyplus.follow_artists
data:
  entity_id: media_player.spotifyplus_john_s
  ids: 2CIMQHirSU0MQqyYHq0eOx,1IQ2e1buppatiN1bxUVkrk

Follow the currently playing track artist.

service: spotifyplus.follow_artists
data:
  entity_id: media_player.spotifyplus_john_s

Follow Playlist

Add the current user as a follower of a playlist.

Parameters

All parameters are required unless otherwise noted.

• entity_id - Entity ID of the SpotifyPlus service that will make the request to the Spotify Web API.
• playlist_id (optional) - The Spotify ID of the playlist (e.g. 37i9dQZF1E39vTG3GurFPW). If omitted, the currently playing playlist uri id value is used.
• public (optional) - If true the playlist will be included in user's public playlists, if false it will remain private. Default is True.

Example YAML

Follow the specified playlist (public).

service: spotifyplus.follow_playlist
data:
  entity_id: media_player.spotifyplus_john_s
  playlist_id: 37i9dQZF1E39vTG3GurFPW
  public: true

Follow the specified playlist (private).

service: spotifyplus.follow_playlist
data:
  entity_id: media_player.spotifyplus_john_s
  playlist_id: 37i9dQZF1E39DIjrju3A9t
  public: false

Follow Users

Add the current user as a follower of one or more users.

Parameters

All parameters are required unless otherwise noted.

• entity_id - Entity ID of the SpotifyPlus service that will make the request to the Spotify Web API.
• ids - A comma-separated list of the Spotify user IDs (e.g. smedjan,3758dfdsfjk435hjk6k79lm0n3c4). A maximum of 50 IDs can be sent in one request.

Example YAML

Follow the specified users.

service: spotifyplus.follow_users
data:
  entity_id: media_player.spotifyplus_john_s
  ids: smedjan,3758dfdsfjk435hjk6k79lm0n3c4

Get Album

Get Spotify catalog information for a single album.

This service will return service response data.

Parameters

All parameters are required unless otherwise noted.

• entity_id - Entity ID of the SpotifyPlus service that will make the request to the Spotify Web API.
• album_id (optional) - The Spotify ID of the album. If omitted, the currently playing album uri id value is used. example: 6vc9OTcyd3hyzabCmsdnwE
• market - An ISO 3166-1 alpha-2 country code. If a country code is specified, only content that is available in that market will be returned. The country associated with the user account will take priority over this parameter. example: US

Example YAML

service: spotifyplus.get_album
data:
  entity_id: media_player.spotifyplus_john_s
  album_id: 6vc9OTcyd3hyzabCmsdnwE

Example Response

A dictionary that contains the following keys:

• user_profile: A (partial) user profile that retrieved the result.
• result: An Album object that contains the album details.

user_profile:
  country: US
  display_name: John Smith
  email: jsmith@maildomain.com
  id: 3758dfdsfjk435hjk6k79lm0n3c4
  product: premium
  type: user
  uri: spotify:user:3758dfdsfjk435hjk6k79lm0n3c4
result:
  ... <data truncated for brevity - same results as Spotify Web API returns>

Get Album Favorites

Get a list of the albums saved in the current Spotify user's 'Your Library'.

This service will return service response data.

Parameters

All parameters are required unless otherwise noted.

• entity_id - Entity ID of the SpotifyPlus service that will make the request to the Spotify Web API.
• limit (optional) - The maximum number of items to return in a page of items. Default is 20, Range is 1 to 50.
• offset (optional) - The page index offset of the first item to return. Use with limit to get the next set of items. Default is 0 (the first item).
• market (optional) - An ISO 3166-1 alpha-2 country code. If a country code is specified, only content that is available in that market will be returned. The country associated with the user account will take priority over this parameter. example: US
• limit_total (optional) - The maximum number of items to return for the request. If specified, this parameter overrides the limit and offset parameter values and paging is automatically used to retrieve all available items up to the specified limit total.
• sort_result (optional) - True to sort the items by name; otherwise, False to leave the items in the same order they were returned in by the Spotify Web API. Default is True.

Example YAML

service: spotifyplus.get_album_favorites
data:
  entity_id: media_player.spotifyplus_john_s
  limit_total: 100

Example Response

A dictionary that contains the following keys:

• user_profile: A (partial) user profile that retrieved the result.
• result: An AlbumPageSaved object that contains the album details.

user_profile:
  country: US
  display_name: John Smith
  email: jsmith@maildomain.com
  id: 3758dfdsfjk435hjk6k79lm0n3c4
  product: premium
  type: user
  uri: spotify:user:3758dfdsfjk435hjk6k79lm0n3c4
result:
  ... <data truncated for brevity - same results as Spotify Web API returns>

Get Album New Releases

Get a list of new album releases featured in Spotify.

This service will return service response data.

Parameters

All parameters are required unless otherwise noted.

• entity_id - Entity ID of the SpotifyPlus service that will make the request to the Spotify Web API.
• limit (optional) - The maximum number of items to return in a page of items. Default is 20, Range is 1 to 50.
• offset (optional) - The page index offset of the first item to return. Use with limit to get the next set of items. Default is 0 (the first item).
• country (optional) - An ISO 3166-1 alpha-2 country code. If a country code is specified, only content that is available in that market will be returned. The country associated with the user account will take priority over this parameter. example: US
• limit_total (optional) - The maximum number of items to return for the request. If specified, this parameter overrides the limit and offset parameter values and paging is automatically used to retrieve all available items up to the specified limit total.
• sort_result (optional) - True to sort the items by name; otherwise, False to leave the items in the same order they were returned in by the Spotify Web API. Default is True.

Example YAML

service: spotifyplus.get_album_new_releases
data:
  entity_id: media_player.spotifyplus_john_s
  limit_total: 100

Example Response

A dictionary that contains the following keys:

• user_profile: A (partial) user profile that retrieved the result.
• result: A AlbumPageSimplified object that contains album information.

user_profile:
  country: US
  display_name: John Smith
  email: jsmith@maildomain.com
  id: 3758dfdsfjk435hjk6k79lm0n3c4
  product: premium
  type: user
  uri: spotify:user:3758dfdsfjk435hjk6k79lm0n3c4
result:
  ... <data truncated for brevity - same results as Spotify Web API returns>

Get Artist

Get Spotify catalog information for a single artist.

This service will return service response data.

Parameters

All parameters are required unless otherwise noted.

• entity_id - Entity ID of the SpotifyPlus service that will make the request to the Spotify Web API.
• artist_id (optional) - The Spotify ID of the artist. If omitted, the currently playing artist uri id value is used. Example: 6APm8EjxOHSYM5B4i3vT3q

Example YAML

service: spotifyplus.get_artist
data:
  entity_id: media_player.spotifyplus_john_s
  artist_id: 6APm8EjxOHSYM5B4i3vT3q

Example Response

A dictionary that contains the following keys:

• user_profile: A (partial) user profile that retrieved the result.
• result: A AlbumPageSimplified object that contains album information.

user_profile:
  country: US
  display_name: John Smith
  email: jsmith@maildomain.com
  id: 3758dfdsfjk435hjk6k79lm0n3c4
  product: premium
  type: user
  uri: spotify:user:3758dfdsfjk435hjk6k79lm0n3c4
result:
  ... <data truncated for brevity - same results as Spotify Web API returns>

Get Artist Albums

Get Spotify catalog information about an artist's albums.

This service will return service response data.

Parameters

All parameters are required unless otherwise noted.

• entity_id - Entity ID of the SpotifyPlus service that will make the request to the Spotify Web API.
• artist_id (optional) - The Spotify ID of the artist. If omitted, the currently playing artist uri id value is used. Example: 6APm8EjxOHSYM5B4i3vT3q
• include_groups (optional) - A comma-separated list of keywords that will be used to filter the response. If not supplied, all album types will be returned. Valid values are album, single, appears_on, compilation.
• limit (optional) - The maximum number of items to return in a page of items. Default is 20, Range is 1 to 50.
• offset (optional) - The page index offset of the first item to return. Use with limit to get the next set of items. Default is 0 (the first item).
• market (optional) - An ISO 3166-1 alpha-2 country code. If a country code is specified, only content that is available in that market will be returned. The country associated with the user account will take priority over this parameter. example: US
• limit_total (optional) - The maximum number of items to return for the request. If specified, this parameter overrides the limit and offset parameter values and paging is automatically used to retrieve all available items up to the specified limit total.
• sort_result (optional) - True to sort the items by name; otherwise, False to leave the items in the same order they were returned in by the Spotify Web API. Default is True.

Example YAML

service: spotifyplus.get_artist_albums
data:
  entity_id: media_player.spotifyplus_john_s
  artist_id: 6APm8EjxOHSYM5B4i3vT3q
  include_groups: album
  limit_total: 100

Example Response

A dictionary that contains the following keys:

• user_profile: A (partial) user profile that retrieved the result.
• result: A AlbumPageSimplified object that contains album information.

user_profile:
  country: US
  display_name: John Smith
  email: jsmith@maildomain.com
  id: 3758dfdsfjk435hjk6k79lm0n3c4
  product: premium
  type: user
  uri: spotify:user:3758dfdsfjk435hjk6k79lm0n3c4
result:
  ... <data truncated for brevity - same results as Spotify Web API returns>

Get Artist Info

Get artist about information from the Spotify Artist Biography page for the specified Spotify artist ID.

This service is not provided by the Spotify Web API.

This service will return service response data.

Parameters

All parameters are required unless otherwise noted.

• entity_id - Entity ID of the SpotifyPlus service that will make the request to the Spotify Web API.
• artist_id (optional) - The Spotify ID of the artist. If omitted, the currently playing artist uri id value is used. Example: 6APm8EjxOHSYM5B4i3vT3q

Example YAML

service: spotifyplus.get_artist_info
data:
  entity_id: media_player.spotifyplus_john_s
  artist_id: 6APm8EjxOHSYM5B4i3vT3q

Example Response

A dictionary that contains the following keys:

• user_profile: A (partial) user profile that retrieved the result.
• result: A ArtistInfo object that contains artist bio information.

user_profile:
  country: US
  display_name: John Smith
  email: jsmith@maildomain.com
  id: 3758dfdsfjk435hjk6k79lm0n3c4
  product: premium
  type: user
  uri: spotify:user:3758dfdsfjk435hjk6k79lm0n3c4
result:
  about_url_facebook: https://facebook.com/mercyme
  about_url_instagram: https://instagram.com/themercyme/
  about_url_twitter: https://twitter.com/mercyme
  about_url_wikipedia: https://en.wikipedia.org/wiki/MercyMe
  bio: >-
    MercyMe is a contemporary Christian music band formed in 1994 signed with
    Fair Trade Services. With more than 9 million units in cumulative sales,
    MercyMe has seen 28 of their songs reach No. 1 across multiple radio
    formats, in addition to garnering four mainstream radio hits. Their landmark
    song “I Can Only Imagine” was the first digital single in Christian music
    history to be certified platinum and double-platinum. In 2009, Billboard
    named MercyMe's "Word Of God Speak" the No. 1 Song of the Decade and the
    group the No. 1 Artist of the Decade in both the Christian Songs and
    Christian AC Songs categories. In addition, they have multiple GRAMMY®
    nominations, American Music Awards, and GMA Dove Awards to their credit.
    They have sold out venues throughout the US and Canada and have appeared on
    the Macy’s Thanksgiving Day Parade, The Today Show, The Tonight Show with
    Jay Leno, FOX & Friends and in the pages of Entertainment Weekly, The New
    York Times, and more. Today, MercyMe continues touring rigorously, picking
    up more No. 1 hits along the way. Their ninth studio album, Lifer, released
    in March of 2017. Lifer went No. 1 on Christian Soundscan and No. 10 on the
    Billboard Top 200 overall chart during its first week. The band is currently
    promoting the feature film titled “I Can Only Imagine,” a true story based
    on the life of lead singer Bart Millard who wrote the mega-hit song “I Can
    Only Imagine” after the loss of his father to cancer. The film will release
    in March of 2018.
  id: 6APm8EjxOHSYM5B4i3vT3q
  image_url: https://i.scdn.co/image/ab6761610000517446196125b56397cd4e0d9c4b
  image_url_default: https://i.scdn.co/image/ab6761610000e5eb46196125b56397cd4e0d9c4b
  name: MercyMe
  monthly_listeners: 2367654
  tour_events:
    - title: null
      venue_name: Crown Coliseum, Fayetteville
      event_datetime: "2024-11-07T19:00:00"
    - title: null
      venue_name: CFG Bank Arena, Baltimore
      event_datetime: "2024-11-08T19:00:00"
    - title: null
      venue_name: Cross Insurance Arena , Portland
      event_datetime: "2024-11-09T19:00:00"
    - title: null
      venue_name: TD Garden, Boston
      event_datetime: "2024-11-10T19:00:00"
  type: artist
  uri: spotify:artist:6APm8EjxOHSYM5B4i3vT3q

Get Artist Related Artists

DEPRECATED API endpoint no longer supported by Spotify as of 2024/11/27. More information about the deprecated functionality can be found on the Spotify Developer Forum Blog page.

Get Spotify catalog information about artists similar to a given artist. Similarity is based on analysis of the Spotify community's listening history.

This service will return service response data.

Parameters

All parameters are required unless otherwise noted.

• entity_id - Entity ID of the SpotifyPlus service that will make the request to the Spotify Web API.
• artist_id (optional) - The Spotify ID of the artist. If omitted, the currently playing artist uri id value is used. Example: 6APm8EjxOHSYM5B4i3vT3q

Example YAML

service: spotifyplus.get_artist_related_artists
data:
  entity_id: media_player.spotifyplus_john_s
  artist_id: 6APm8EjxOHSYM5B4i3vT3q

Example Response

A dictionary that contains the following keys:

• user_profile: A (partial) user profile that retrieved the result.
• result: A list of Artist objects that contain artist information.

user_profile:
  country: US
  display_name: John Smith
  email: jsmith@maildomain.com
  id: 3758dfdsfjk435hjk6k79lm0n3c4
  product: premium
  type: user
  uri: spotify:user:3758dfdsfjk435hjk6k79lm0n3c4
result:
  ... <data truncated for brevity - same results as Spotify Web API returns>

Get Artists Followed

Get the current user's followed artists.

This service will return service response data.

Parameters

All parameters are required unless otherwise noted.

• entity_id - Entity ID of the SpotifyPlus service that will make the request to the Spotify Web API.
• after (optional) - The last artist ID retrieved from the previous request, or null for the first request. example: "6APm8EjxOHSYM5B4i3vT3q"
• limit (optional) - The maximum number of items to return in a page of items. Default is 20, Range is 1 to 50.
• limit_total (optional) - The maximum number of items to return for the request. If specified, this parameter overrides the limit and offset parameter values and paging is automatically used to retrieve all available items up to the specified limit total.
• sort_result (optional) - True to sort the items by name; otherwise, False to leave the items in the same order they were returned in by the Spotify Web API. Default is True.

Example YAML

service: spotifyplus.get_artists_followed
data:
  entity_id: media_player.spotifyplus_john_s
  after: 6APm8EjxOHSYM5B4i3vT3q
  limit_total: 100

Example Response

A dictionary that contains the following keys:

• user_profile: A (partial) user profile that retrieved the result.
• result: A ArtistPage object that contains artist information.

user_profile:
  country: US
  display_name: John Smith
  email: jsmith@maildomain.com
  id: 3758dfdsfjk435hjk6k79lm0n3c4
  product: premium
  type: user
  uri: spotify:user:3758dfdsfjk435hjk6k79lm0n3c4
result:
  ... <data truncated for brevity - same results as Spotify Web API returns>

Get Audiobook

Get Spotify catalog information for a single audiobook.

Audiobooks are only available within the US, UK, Canada, Ireland, New Zealand and Australia markets.

This service will return service response data.

Parameters

All parameters are required unless otherwise noted.

• entity_id - Entity ID of the SpotifyPlus service that will make the request to the Spotify Web API.
• audiobook_id (optional) - The Spotify ID for the audiobook (e.g. 74aydHJKgYz3AIq3jjBSv1). If null, the currently playing audiobook uri id value is used.
• market - An ISO 3166-1 alpha-2 country code. If a country code is specified, only content that is available in that market will be returned. The country associated with the user account will take priority over this parameter.

Example YAML

service: spotifyplus.get_audiobook
data:
  entity_id: media_player.spotifyplus_john_s
  audiobook_id: 74aydHJKgYz3AIq3jjBSv1

Example Response

A dictionary that contains the following keys:

• user_profile: A (partial) user profile that retrieved the result.
• result: An Audiobook object that contains audiobook information.

user_profile:
  country: US
  display_name: John Smith
  email: jsmith@maildomain.com
  id: 3758dfdsfjk435hjk6k79lm0n3c4
  product: premium
  type: user
  uri: spotify:user:3758dfdsfjk435hjk6k79lm0n3c4
result:
  ... <data truncated for brevity - same results as Spotify Web API returns>

Get Audiobook Chapters

Get Spotify catalog information about an audiobook's chapters.

This service will return service response data.

Parameters

All parameters are required unless otherwise noted.

• entity_id - Entity ID of the SpotifyPlus service that will make the request to the Spotify Web API.
• audiobook_id (optional) - The Spotify ID for the audiobook (e.g. 74aydHJKgYz3AIq3jjBSv1). If null, the currently playing audiobook uri id value is used.
• limit (optional) - The maximum number of items to return in a page of items. Default is 20, Range is 1 to 50.
• offset (optional) - The page index offset of the first item to return. Use with limit to get the next set of items. Default is 0 (the first item).
• market - An ISO 3166-1 alpha-2 country code. If a country code is specified, only content that is available in that market will be returned. The country associated with the user account will take priority over this parameter.
• limit_total (optional) - The maximum number of items to return for the request. If specified, this parameter overrides the limit and offset parameter values and paging is automatically used to retrieve all available items up to the specified limit total.

Example YAML

service: spotifyplus.get_audiobook_chapters
data:
  entity_id: media_player.spotifyplus_john_s
  audiobook_id: 74aydHJKgYz3AIq3jjBSv1
  limit_total: 100

Example Response

A dictionary that contains the following keys:

• user_profile: A (partial) user profile that retrieved the result.
• result: A ChapterPageSimplified object that contains audiobook chapter information.

user_profile:
  country: US
  display_name: John Smith
  email: jsmith@maildomain.com
  id: 3758dfdsfjk435hjk6k79lm0n3c4
  product: premium
  type: user
  uri: spotify:user:3758dfdsfjk435hjk6k79lm0n3c4
result:
  ... <data truncated for brevity - same results as Spotify Web API returns>

Get Audiobook Favorites

Get a list of the audiobooks saved in the current Spotify user's 'Your Library'.

This service will return service response data.

Parameters

All parameters are required unless otherwise noted.

• entity_id - Entity ID of the SpotifyPlus service that will make the request to the Spotify Web API.
• limit (optional) - The maximum number of items to return in a page of items. Default is 20, Range is 1 to 50.
• offset (optional) - The page index offset of the first item to return. Use with limit to get the next set of items. Default is 0 (the first item).
• limit_total (optional) - The maximum number of items to return for the request. If specified, this parameter overrides the limit and offset parameter values and paging is automatically used to retrieve all available items up to the specified limit total.
• sort_result (optional) - True to sort the items by name; otherwise, False to leave the items in the same order they were returned in by the Spotify Web API. Default is True.

Example YAML

service: spotifyplus.get_audiobook_favorites
data:
  entity_id: media_player.spotifyplus_john_s
  limit_total: 100

Example Response

A dictionary that contains the following keys:

• user_profile: A (partial) user profile that retrieved the result.
• result: A AudiobookPageSimplified object that contains audiobook favorite information.

user_profile:
  country: US
  display_name: John Smith
  email: jsmith@maildomain.com
  id: 3758dfdsfjk435hjk6k79lm0n3c4
  product: premium
  type: user
  uri: spotify:user:3758dfdsfjk435hjk6k79lm0n3c4
result:
  ... <data truncated for brevity - same results as Spotify Web API returns>

Get Browse Categories

Get a sorted list of ALL categories used to tag items in Spotify.

This service will return service response data.

Parameters

All parameters are required unless otherwise noted.

• entity_id - Entity ID of the SpotifyPlus service that will make the request to the Spotify Web API.
• country - An ISO 3166-1 alpha-2 country code. If a country code is specified, only content that is available in that market will be returned. The country associated with the user account will take priority over this parameter.
• locale - The desired language, consisting of a lowercase ISO 639-1 language code and an uppercase ISO 3166-1 alpha-2 country code, joined by an underscore. For example es_MX, meaning Spanish (Mexico). Provide this parameter if you want the results returned in a particular language (where available). Note that if locale is not supplied, or if the specified language is not available, all strings will be returned in the Spotify default language (American English).
• refresh - True to return real-time information from the spotify web api and update the cache; otherwise, False to just return the cached value.
• sort_result (optional) - True to sort the items by name; otherwise, False to leave the items in the same order they were returned in by the Spotify Web API. Default is True.

Example YAML

service: spotifyplus.get_browse_categorys_list
data:
  entity_id: media_player.spotifyplus_john_s

Example Response

A dictionary that contains the following keys:

• user_profile: A (partial) user profile that retrieved the result.
• result: A CategoryPage object that contains the list category details.

user_profile:
  country: US
  display_name: John Smith
  email: jsmith@maildomain.com
  id: 3758dfdsfjk435hjk6k79lm0n3c4
  product: premium
  type: user
  uri: spotify:user:3758dfdsfjk435hjk6k79lm0n3c4
result:
  ... <data truncated for brevity - same results as Spotify Web API returns>

Get Category Playlists

DEPRECATED API endpoint no longer supported by Spotify as of 2024/11/27. More information about the deprecated functionality can be found on the Spotify Developer Forum Blog page.

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

This service will return service response data.

Parameters

All parameters are required unless otherwise noted.

• entity_id - Entity ID of the SpotifyPlus service that will make the request to the Spotify Web API.
• category_id - Spotify category ID (not name) for the category.
• limit (optional) - The maximum number of items to return in a page of items. Default is 20, Range is 1 to 50.
• offset (optional) - The page index offset of the first item to return. Use with limit to get the next set of items. Default is 0 (the first item).
• country (optional) - An ISO 3166-1 alpha-2 country code. If a country code is specified, only content that is available in that market will be returned. The country associated with the user account will take priority over this parameter. example: US
• limit_total (optional) - The maximum number of items to return for the request. If specified, this parameter overrides the limit and offset parameter values and paging is automatically used to retrieve all available items up to the specified limit total.
• sort_result (optional) - True to sort the items by name; otherwise, False to leave the items in the same order they were returned in by the Spotify Web API. Default is True.

Example YAML

service: spotifyplus.get_category_playlists
data:
  entity_id: media_player.spotifyplus_john_s
  category_id: dinner
  limit_total: 100

Example Response

A dictionary that contains the following keys:

• user_profile: A (partial) user profile that retrieved the result.
• result: A PlaylistPageSimplified object that contains playlist information.
• message: A string that describes what was returned (e.g. 'Popular Playlists').

user_profile:
  country: US
  display_name: John Smith
  email: jsmith@maildomain.com
  id: 3758dfdsfjk435hjk6k79lm0n3c4
  product: premium
  type: user
  uri: spotify:user:3758dfdsfjk435hjk6k79lm0n3c4
result:
  ... <data truncated for brevity - same results as Spotify Web API returns>
message:
  message: Popular Playlists

Get Chapter

Get Spotify catalog information for a single audiobook chapter identified by its unique Spotify ID.

This service will return service response data.

Parameters

All parameters are required unless otherwise noted.

• entity_id - Entity ID of the SpotifyPlus service that will make the request to the Spotify Web API.
• chapter_id (optional) - The Spotify ID for the chapter. If omitted, the currently playing chapter uri id value is used. Example: 3V0yw9UDrYAfkhAvTrvt9Y
• market - An ISO 3166-1 alpha-2 country code. If a country code is specified, only content that is available in that market will be returned. The country associated with the user account will take priority over this parameter.

Example YAML

service: spotifyplus.get_chapter
data:
  entity_id: media_player.spotifyplus_john_s
  chapter_id: 3V0yw9UDrYAfkhAvTrvt9Y

Example Response

A dictionary that contains the following keys:

• user_profile: A (partial) user profile that retrieved the result.
• result: A Chapter object that contain the audiobook chapter details.

user_profile:
  country: US
  display_name: John Smith
  email: jsmith@maildomain.com
  id: 3758dfdsfjk435hjk6k79lm0n3c4
  product: premium
  type: user
  uri: spotify:user:3758dfdsfjk435hjk6k79lm0n3c4
result:
  ... <data truncated for brevity - same results as Spotify Web API returns>

Get Episode

Get Spotify catalog information for a single episode identified by its unique Spotify ID.

This service will return service response data.

Parameters

All parameters are required unless otherwise noted.

• entity_id - Entity ID of the SpotifyPlus service that will make the request to the Spotify Web API.
• episode_id (optional) - The Spotify ID for the episode. If omitted, the currently playing episode uri id value is used. Example: 26c0zVyOv1lzfYpBXdh1zC
• market - An ISO 3166-1 alpha-2 country code. If a country code is specified, only content that is available in that market will be returned. The country associated with the user account will take priority over this parameter.

Example YAML

service: spotifyplus.get_episode
data:
  entity_id: media_player.spotifyplus_john_s
  episode_id: 26c0zVyOv1lzfYpBXdh1zC

Example Response

A dictionary that contains the following keys:

• user_profile: A (partial) user profile that retrieved the result.
• result: A Episode object that contain the episode details.

user_profile:
  country: US
  display_name: John Smith
  email: jsmith@maildomain.com
  id: 3758dfdsfjk435hjk6k79lm0n3c4
  product: premium
  type: user
  uri: spotify:user:3758dfdsfjk435hjk6k79lm0n3c4
result:
  ... <data truncated for brevity - same results as Spotify Web API returns>

Get Episode Favorites

Get a list of the episodes saved in the current Spotify user's 'Your Library'.

This service will return service response data.

Parameters

All parameters are required unless otherwise noted.

• entity_id - Entity ID of the SpotifyPlus service that will make the request to the Spotify Web API.
• limit (optional) - The maximum number of items to return in a page of items. Default is 20, Range is 1 to 50.
• offset (optional) - The page index offset of the first item to return. Use with limit to get the next set of items. Default is 0 (the first item).
• limit_total (optional) - The maximum number of items to return for the request. If specified, this parameter overrides the limit and offset parameter values and paging is automatically used to retrieve all available items up to the specified limit total.
• sort_result (optional) - True to sort the items by name; otherwise, False to leave the items in the same order they were returned in by the Spotify Web API. Default is True.

Example YAML

service: spotifyplus.get_episode_favorites
data:
  entity_id: media_player.spotifyplus_john_s
  limit_total: 100

Example Response

A dictionary that contains the following keys:

• user_profile: A (partial) user profile that retrieved the result.
• result: A EpisodePageSaved object that contains episode information.

user_profile:
  country: US
  display_name: John Smith
  email: jsmith@maildomain.com
  id: 3758dfdsfjk435hjk6k79lm0n3c4
  product: premium
  type: user
  uri: spotify:user:3758dfdsfjk435hjk6k79lm0n3c4
result:
  ... <data truncated for brevity - same results as Spotify Web API returns>

Get Featured Playlists

DEPRECATED API endpoint no longer supported by Spotify as of 2024/11/27. More information about the deprecated functionality can be found on the Spotify Developer Forum Blog page.

Get a list of Spotify featured playlists.

This service will return service response data.

Parameters

All parameters are required unless otherwise noted.

• entity_id - Entity ID of the SpotifyPlus service that will make the request to the Spotify Web API.
• limit (optional) - The maximum number of items to return in a page of items. Default is 20, Range is 1 to 50.
• offset (optional) - The page index offset of the first item to return. Use with limit to get the next set of items. Default is 0 (the first item).
• country (optional) - An ISO 3166-1 alpha-2 country code. If a country code is specified, only content that is available in that market will be returned. The country associated with the user account will take priority over this parameter. example: US
• locale (optional) - The desired language, consisting of a lowercase ISO 639-1 language code and an uppercase ISO 3166-1 alpha-2 country code, joined by an underscore. For example es_MX, meaning Spanish (Mexico). Provide this parameter if you want the results returned in a particular language (where available). Note that if locale is not supplied, or if the specified language is not available, all strings will be returned in the Spotify default language (American English).
• timestamp (optional) - A timestamp in ISO 8601 format (yyyy-MM-ddTHH:mm:ss). Use this parameter to specify the user's local time to get results tailored for that specific date and time in the day. If not provided, the response defaults to the current UTC time.
• limit_total (optional) - The maximum number of items to return for the request. If specified, this parameter overrides the limit and offset parameter values and paging is automatically used to retrieve all available items up to the specified limit total.
• sort_result (optional) - True to sort the items by name; otherwise, False to leave the items in the same order they were returned in by the Spotify Web API. Default is True.

Example YAML

service: spotifyplus.get_featured_playlists
data:
  entity_id: media_player.spotifyplus_john_s
  limit_total: 100

Example Response

A dictionary that contains the following keys:

• user_profile: A (partial) user profile that retrieved the result.
• result: A PlaylistPageSimplified object that contains playlist information.
• message: A string that describes what was returned (e.g. 'Popular Playlists').

user_profile:
  country: US
  display_name: John Smith
  email: jsmith@maildomain.com
  id: 3758dfdsfjk435hjk6k79lm0n3c4
  product: premium
  type: user
  uri: spotify:user:3758dfdsfjk435hjk6k79lm0n3c4
result:
  ... <data truncated for brevity - same results as Spotify Web API returns>

Get Player Devices

Get information about a user's available Spotify Connect player devices. Some device models are not supported and will not be listed in the API response.

This service will return service response data.

Parameters

All parameters are required unless otherwise noted.

• entity_id - Entity ID of the SpotifyPlus service that will make the request to the Spotify Web API.
• refresh - True to return real-time information from the spotify web api and update the cache; otherwise, False to just return the cached values.
• sort_result (optional) - True to sort the items by name; otherwise, False to leave the items in the same order they were returned in by the Spotify Web API. Default is True.

Example YAML

service: spotifyplus.get_player_devices
data:
  entity_id: media_player.spotifyplus_john_s
  refresh: true

Example Response

A dictionary that contains the following keys:

• user_profile: A (partial) user profile that retrieved the result.
• result: A list of Device objects that contain the device details, sorted by name.

user_profile:
  country: US
  display_name: John Smith
  email: jsmith@maildomain.com
  id: 3758dfdsfjk435hjk6k79lm0n3c4
  product: premium
  type: user
  uri: spotify:user:3758dfdsfjk435hjk6k79lm0n3c4
result:
  ... <data truncated for brevity - same results as Spotify Web API returns>

Get Player Now Playing

Get the object currently being played on the user's Spotify account.

This service will return service response data.

Parameters

All parameters are required unless otherwise noted.

• entity_id - Entity ID of the SpotifyPlus service that will make the request to the Spotify Web API.
• market - An ISO 3166-1 alpha-2 country code. If a country code is specified, only content that is available in that market will be returned. The country associated with the user account will take priority over this parameter.
• additional_types - A comma-separated list of item types that your client supports besides the default track type. Valid types are 'track' and 'episode'. Example: "episode"

Example YAML

service: spotifyplus.get_player_now_playing
data:
  entity_id: media_player.spotifyplus_john_s
  additional_types: episode

Example Response

A dictionary that contains the following keys:

• user_profile: A (partial) user profile that retrieved the result.
• result: A PlayerPlayState object that contains the player state details.

user_profile:
  country: US
  display_name: John Smith
  email: jsmith@maildomain.com
  id: 3758dfdsfjk435hjk6k79lm0n3c4
  product: premium
  type: user
  uri: spotify:user:3758dfdsfjk435hjk6k79lm0n3c4
result:
  ... <data truncated for brevity - same results as Spotify Web API returns>

Get Player Playback State

Get information about the user's current playback state, including track or episode, progress, and active device.

This service will return service response data.

Parameters

All parameters are required unless otherwise noted.

• entity_id - Entity ID of the SpotifyPlus service that will make the request to the Spotify Web API.
• market - An ISO 3166-1 alpha-2 country code. If a country code is specified, only content that is available in that market will be returned. The country associated with the user account will take priority over this parameter.
• additional_types - A comma-separated list of item types that your client supports besides the default track type. Valid types are 'track' and 'episode'. Example: "episode"

Example YAML

service: spotifyplus.get_player_playback_state
data:
  entity_id: media_player.spotifyplus_john_s
  additional_types: episode

Example Response

A dictionary that contains the following keys:

• user_profile: A (partial) user profile that retrieved the result.
• result: A PlayerPlayState object that contains the player playback state details.

user_profile:
  country: US
  display_name: John Smith
  email: jsmith@maildomain.com
  id: 3758dfdsfjk435hjk6k79lm0n3c4
  product: premium
  type: user
  uri: spotify:user:3758dfdsfjk435hjk6k79lm0n3c4
result:
  ... <data truncated for brevity - same results as Spotify Web API returns>

Get Player Queue Info

Get the list of objects that make up the user's playback queue.

This service will return service response data.

Parameters

All parameters are required unless otherwise noted.

• entity_id - Entity ID of the SpotifyPlus service that will make the request to the Spotify Web API.

Example YAML

service: spotifyplus.get_player_queue_info
data:
  entity_id: media_player.spotifyplus_john_s

Example Response

A dictionary that contains the following keys:

• user_profile: A (partial) user profile that retrieved the result.
• result: A PlayerQueueInfo object that contains the player queue information.

user_profile:
  country: US
  display_name: John Smith
  email: jsmith@maildomain.com
  id: 3758dfdsfjk435hjk6k79lm0n3c4
  product: premium
  type: user
  uri: spotify:user:3758dfdsfjk435hjk6k79lm0n3c4
result:
  ... <data truncated for brevity - same results as Spotify Web API returns>

Get Player Recent Tracks

Get tracks from the current user's recently played tracks; currently doesn't support podcast episodes, and only 50 items may be returned due to spotify limits.

This service will return service response data.

Parameters

All parameters are required unless otherwise noted.

• entity_id - Entity ID of the SpotifyPlus service that will make the request to the Spotify Web API.
• limit - The maximum number of items to return in a page of items. Default is 20, Range is 1 to 50.
• after - Returns all items after (but not including) this cursor position, which is a Unix timestamp in milliseconds. If after is specified, before must not be specified. Use with limit to get the next set of items. Default is 0 (the first item). Example: 1706218456821
• before - Returns all items before (but not including) this cursor position, which is a Unix timestamp in milliseconds. If before is specified, after must not be specified. Use with limit to get the next set of items. Default is 0 (the first item). Example: 1706218467821
• limit_total - The maximum number of items to return for the request. If specified, this parameter overrides the limit and after / before parameter values and paging is automatically used to retrieve all available items up to the specified limit total.

Example YAML

service: spotifyplus.get_player_recent_tracks
data:
  entity_id: media_player.spotifyplus_john_s
  after: 1706218456821
  limit_total: 50

Example Response

A dictionary that contains the following keys:

• user_profile: A (partial) user profile that retrieved the result.
• result: A PlayHistoryPage object that contains play history information.

user_profile:
  country: US
  display_name: John Smith
  email: jsmith@maildomain.com
  id: 3758dfdsfjk435hjk6k79lm0n3c4
  product: premium
  type: user
  uri: spotify:user:3758dfdsfjk435hjk6k79lm0n3c4
result:
  ... <data truncated for brevity - same results as Spotify Web API returns>

Get Playlist

Get a playlist owned by a Spotify user.

A call made to this service will return an exception of 404 Resource Not Found if the specified playlist id is a Spotify-owned algorithmic playlist (e.g. "Daily Mix 1", etc). This is due to the changes made by the Spotify Development team to no longer return information for Spotify-owned algorithmic playlists. This was a completely unannounced change that they implemented on 2024/11/27.

This service will return service response data.

Parameters

All parameters are required unless otherwise noted.

• entity_id - Entity ID of the SpotifyPlus service that will make the request to the Spotify Web API.
• playlist_id (optional) - The Spotify ID of the playlist. If omitted, the currently playing playlist uri id value is used. Example: "5v5ETK9WFXAnGQ3MRubKuE"
• market - An ISO 3166-1 alpha-2 country code. If a country code is specified, only content that is available in that market will be returned. The country associated with the user account will take priority over this parameter.
• fields - A comma-separated list of fields to return from the Spotify Web API. All fields are returned if omitted. Limiting fields results can improve performance. Example: description,id,name,public,snapshot_id,type,uri,tracks(limit,next,offset,previous,total,items(track(id,name,track_number,type,uri,album(id,images,name,total_tracks,type,uri,artists(id,name,type,uri)))))
• additional_types - A comma-separated list of item types that your client supports besides the default track type. Valid types are 'track' and 'episode'. Example: "episode"

Example YAML

service: spotifyplus.get_playlist
data:
  entity_id: media_player.spotifyplus_john_s
  playlist_id: 5v5ETK9WFXAnGQ3MRubKuE
  fields: >-
    description,id,name,public,snapshot_id,type,uri,tracks(limit,next,offset,previous,total,items(track(id,name,track_number,type,uri,album(id,images,name,total_tracks,type,uri,artists(id,name,type,uri)))))
  additional_types: episode

Example Response

A dictionary that contains the following keys:

• user_profile: A (partial) user profile that retrieved the result.
• result: A Playlist object that contains the playlist details.

user_profile:
  country: US
  display_name: John Smith
  email: jsmith@maildomain.com
  id: 3758dfdsfjk435hjk6k79lm0n3c4
  product: premium
  type: user
  uri: spotify:user:3758dfdsfjk435hjk6k79lm0n3c4
result:
  ... <data truncated for brevity - same results as Spotify Web API returns>

Get Playlist Cover Image

Get the current image associated with a specific playlist.

This service will return service response data.

Parameters

All parameters are required unless otherwise noted.

• entity_id - Entity ID of the SpotifyPlus service that will make the request to the Spotify Web API.
• playlist_id (optional) - The Spotify ID of the playlist (e.g. 5v5ETK9WFXAnGQ3MRubKuE). If omitted, the currently playing playlist uri id value is used.

Example YAML

service: spotifyplus.get_playlist_cover_image
data:
  entity_id: media_player.spotifyplus_john_s
  playlist_id: 5v5ETK9WFXAnGQ3MRubKuE

Example Response

A dictionary that contains the following keys:

• user_profile: A (partial) user profile that retrieved the result.
• result: An ImageObject object that contains the playlist cover image details.

user_profile:
  country: US
  display_name: John Smith
  email: jsmith@maildomain.com
  id: 3758dfdsfjk435hjk6k79lm0n3c4
  product: premium
  type: user
  uri: spotify:user:3758dfdsfjk435hjk6k79lm0n3c4
result:
  url: >-
    https://image-cdn-ak.spotifycdn.com/image/ab67706c0000bebb2a1e8b013cde907c19a30af0
  height: null
  width: null

Get Playlist Favorites

Important

As of 2024/11/27, the Spotify Web API will only return user-defined playlists in the results. It will not return any Spotify Algorithmic playlists (e.g. “Daily Mix 1”, “Discover Weekly”, and other “Made For You” playlists). It will also not return playlist folders. More information about the deprecated functionality can be found on the Spotify Developer Forum Blog page.

Get a list of the playlists owned or followed by the current Spotify user.

This service will return service response data.

Parameters

All parameters are required unless otherwise noted.

• entity_id - Entity ID of the SpotifyPlus service that will make the request to the Spotify Web API.
• limit (optional) - The maximum number of items to return in a page of items. Default is 20, Range is 1 to 50.
• offset (optional) - The page index offset of the first item to return. Use with limit to get the next set of items. Default is 0 (the first item).
• limit_total (optional) - The maximum number of items to return for the request. If specified, this parameter overrides the limit and offset parameter values and paging is automatically used to retrieve all available items up to the specified limit total.
• sort_result (optional) - True to sort the items by name; otherwise, False to leave the items in the same order they were returned in by the Spotify Web API. Default is True.

Example YAML

service: spotifyplus.get_playlist_favorites
data:
  entity_id: media_player.spotifyplus_john_s
  limit_total: 100

Example Response

A dictionary that contains the following keys:

• user_profile: A (partial) user profile that retrieved the result.
• result: A PlaylistPageSimplified object that contains the playlist information.

user_profile:
  country: US
  display_name: John Smith
  email: jsmith@maildomain.com
  id: 3758dfdsfjk435hjk6k79lm0n3c4
  product: premium
  type: user
  uri: spotify:user:3758dfdsfjk435hjk6k79lm0n3c4
result:
  ... <data truncated for brevity - same results as Spotify Web API returns>

Get Playlist Items

Get full details of the items of a playlist owned by a Spotify user.

This service will return service response data.

Parameters

All parameters are required unless otherwise noted.

• entity_id - Entity ID of the SpotifyPlus service that will make the request to the Spotify Web API.
• playlist_id (optional) - The Spotify ID of the playlist (e.g. 5v5ETK9WFXAnGQ3MRubKuE). If null, the currently playing playlist uri id value is used.
• limit (optional) - The maximum number of items to return in a page of items. Default is 20, Range is 1 to 50.
• offset (optional) - The page index offset of the first item to return. Use with limit to get the next set of items. Default is 0 (the first item).
• market (optional) - An ISO 3166-1 alpha-2 country code. If a country code is specified, only content that is available in that market will be returned. The country associated with the user account will take priority over this parameter.
• fields (optional) - Filters for the query; a comma-separated list of the fields to return. If omitted, all fields are returned. For example, specify 'items(track(name,uri))' to get just the playlist's track names and URIs.
• additional_types (optional) - A comma-separated list of item types that your client supports besides the default track type. Valid types are 'track' and 'episode'.
• limit_total (optional) - The maximum number of items to return for the request. If specified, this parameter overrides the limit and offset parameter values and paging is automatically used to retrieve all available items up to the specified limit total.

Example YAML

service: spotifyplus.get_playlist_items
data:
  entity_id: media_player.spotifyplus_john_s
  playlist_id: 5v5ETK9WFXAnGQ3MRubKuE
  fields: items(track(name,uri))
  additional_types: track
  limit_total: 100

Example Response

A dictionary that contains the following keys:

• user_profile: A (partial) user profile that retrieved the result.
• result: A PlaylistPage object that contains the playlist item information.

user_profile:
  country: US
  display_name: John Smith
  email: jsmith@maildomain.com
  id: 3758dfdsfjk435hjk6k79lm0n3c4
  product: premium
  type: user
  uri: spotify:user:3758dfdsfjk435hjk6k79lm0n3c4
result:
  ... <data truncated for brevity - same results as Spotify Web API returns>

Get Playlists For User

Get a list of the playlists owned or followed by a Spotify user.

This service will return service response data.

Parameters

All parameters are required unless otherwise noted.

• entity_id - Entity ID of the SpotifyPlus service that will make the request to the Spotify Web API.
• user_id - The user's Spotify user ID (e.g. smedjan).
• limit (optional) - The maximum number of items to return in a page of items. Default is 20, Range is 1 to 50.
• offset (optional) - The page index offset of the first item to return. Use with limit to get the next set of items. Default is 0 (the first item).
• limit_total (optional) - The maximum number of items to return for the request. If specified, this parameter overrides the limit and offset parameter values and paging is automatically used to retrieve all available items up to the specified limit total.
• sort_result (optional) - True to sort the items by name; otherwise, False to leave the items in the same order they were returned in by the Spotify Web API. Default is True.

Example YAML

service: spotifyplus.get_playlists_for_user
data:
  entity_id: media_player.spotifyplus_john_s
  user_id: smedjan
  limit_total: 75

Example Response

A dictionary that contains the following keys:

• user_profile: A (partial) user profile that retrieved the result.
• result: A PlaylistPageSimplified object that contains the playlist information.

user_profile:
  country: US
  display_name: John Smith
  email: jsmith@maildomain.com
  id: 3758dfdsfjk435hjk6k79lm0n3c4
  product: premium
  type: user
  uri: spotify:user:3758dfdsfjk435hjk6k79lm0n3c4
result:
  ... <data truncated for brevity - same results as Spotify Web API returns>

Get Show

Get Spotify catalog information for a single show identified by its unique Spotify ID.

This service will return service response data.

Parameters

All parameters are required unless otherwise noted.

• entity_id - Entity ID of the SpotifyPlus service that will make the request to the Spotify Web API.
• show_id (optional) - The Spotify ID for the show. If omitted, the currently playing show uri id value is used. Example: 5CfCWKI5pZ28U0uOzXkDHe
• market (optional) - An ISO 3166-1 alpha-2 country code. If a country code is specified, only content that is available in that market will be returned. The country associated with the user account will take priority over this parameter.

Example YAML

service: spotifyplus.get_show
data:
  entity_id: media_player.spotifyplus_john_s
  show_id: 5CfCWKI5pZ28U0uOzXkDHe

Example Response

A dictionary that contains the following keys:

• user_profile: A (partial) user profile that retrieved the result.
• result: A Show object that contain the show details.

user_profile:
  country: US
  display_name: John Smith
  email: jsmith@maildomain.com
  id: 3758dfdsfjk435hjk6k79lm0n3c4
  product: premium
  type: user
  uri: spotify:user:3758dfdsfjk435hjk6k79lm0n3c4
result:
  ... <data truncated for brevity - same results as Spotify Web API returns>

Get Show Episodes

Get Spotify catalog information about a show's episodes.

This service will return service response data.

Parameters

All parameters are required unless otherwise noted.

• entity_id - Entity ID of the SpotifyPlus service that will make the request to the Spotify Web API.
• show_id (optional) - The Spotify ID for the show. If omitted, the currently playing show uri id value is used. Example: 6kAsbP8pxwaU2kPibKTuHE
• limit (optional) - The maximum number of items to return in a page of items. Default is 20, Range is 1 to 50.
• offset (optional) - The page index offset of the first item to return. Use with limit to get the next set of items. Default is 0 (the first item).
• market (optional) - An ISO 3166-1 alpha-2 country code. If a country code is specified, only content that is available in that market will be returned. The country associated with the user account will take priority over this parameter. example: US
• limit_total (optional) - The maximum number of items to return for the request. If specified, this parameter overrides the limit and offset parameter values and paging is automatically used to retrieve all available items up to the specified limit total.

Example YAML

service: spotifyplus.get_show_episodes
data:
  entity_id: media_player.spotifyplus_john_s
  show_id: 6kAsbP8pxwaU2kPibKTuHE
  limit_total: 20

Example Response

A dictionary that contains the following keys:

• user_profile: A (partial) user profile that retrieved the result.
• result: A EpisodePageSimplified object that contains the show episodes.

user_profile:
  country: US
  display_name: John Smith
  email: jsmith@maildomain.com
  id: 3758dfdsfjk435hjk6k79lm0n3c4
  product: premium
  type: user
  uri: spotify:user:3758dfdsfjk435hjk6k79lm0n3c4
result:
  ... <data truncated for brevity - same results as Spotify Web API returns>

Get Show Favorites

Get a list of the shows saved in the current Spotify user's 'Your Library'.

This service will return service response data.

Parameters

All parameters are required unless otherwise noted.

• entity_id - Entity ID of the SpotifyPlus service that will make the request to the Spotify Web API.
• limit (optional) - The maximum number of items to return in a page of items. Default is 20, Range is 1 to 50.
• offset (optional) - The page index offset of the first item to return. Use with limit to get the next set of items. Default is 0 (the first item).
• limit_total (optional) - The maximum number of items to return for the request. If specified, this parameter overrides the limit and offset parameter values and paging is automatically used to retrieve all available items up to the specified limit total.
• sort_result (optional) - True to sort the items by name; otherwise, False to leave the items in the same order they were returned in by the Spotify Web API. Default is True.

Example YAML

service: spotifyplus.get_show_favorites
data:
  entity_id: media_player.spotifyplus_john_s
  limit_total: 100

Example Response

A dictionary that contains the following keys:

• user_profile: A (partial) user profile that retrieved the result.
• result: A ShowPageSaved object that contains playlist information.

user_profile:
  country: US
  display_name: John Smith
  email: jsmith@maildomain.com
  id: 3758dfdsfjk435hjk6k79lm0n3c4
  product: premium
  type: user
  uri: spotify:user:3758dfdsfjk435hjk6k79lm0n3c4
result:
  ... <data truncated for brevity - same results as Spotify Web API returns>

Get Spotify Connect Device

Get information about a specific Spotify Connect player device, and (optionally) activate the device if it requires it.

Resolves a Spotify Connect device from a specified device id, name, alias id, or alias name. This will ensure that the device can be found on the network, as well as connect to the device if necessary with the current user context.

The Spotify Connect discovery list is searched for the specified device value; the search will match on either a Device ID or RemoteName as well as any alias ID's or Names that are in use. The cached Spotify Connect discovery list will be used if the refreshDeviceList argument is False, or if the cache is empty; otherwise, Spotify Connect discovery list will be refreshed and the cache updated prior to the search.

The SpotifyConnectDevice object is returned if a match is found; otherwise, a null value is returned.

The device will be activated if it requires it, or if the caller forces us to do so (e.g. activate_device: true). A Spotify Connect Zeroconf discovery process is initiated to search for the device connected to the local network. It will then perform the following on the device:

• call Spotify Zeroconf API getInfo endpoint to retrieve device information.
• call Spotify Zeroconf API resetUsers endpoint to disconnect the device. This step is omitted for dynamic devices (see note below). Note that this will force any users that are connected to the device off of the device.
• call Spotify Zeroconf API addUser endpoint to connect the device. This step is omitted for dynamic devices (see note below). This should "re-awaken" the device if necessary, and make it ready for immediate use.

Dynamic Spotify Connect devices are not processed by this method, as they are temporary devices and are already active and in the device list. These devices are not found in Zeroconf discovery process, and only exist in the player device list. These are usually Spotify Connect web or mobile players with temporary device id's.

Note that the SpotifyConnectUsername, SpotifyConnectPassword, and SpotifyConnectLoginId configuration options must be specified in order to use this method. Depending on the device, they can all be required in order to reactivate a Spotify Connect device.

This service will return service response data.

Parameters

All parameters are required unless otherwise noted.

• entity_id - Entity ID of the SpotifyPlus service that will make the request to the Spotify Web API.
• device_value - The device id (e.g. '0d1841b0976bae2a3a310dd74c0f337465899bc8') or name (e.g. 'Bose-ST10-1') value to resolve.
• verify_user_context (optional) - If True, the active user context of the resolved device is checked to ensure it matches the user context specified on the class constructor. If False, the user context will not be checked. Default is True.
• verify_timeout (optional) - Maximum time to wait (in seconds) for the device to become active in the Spotify Connect device list. This value is only used if a Connect command has to be issued to activate the device. Default is 5; value range is 0 - 10.
• refresh_device_list (optional) - True to refresh the Spotify Connect device list; otherwise, False to use the Spotify Connect device list cache.
• activate_device (optional) - True to activate the device if necessary; otherwise, False.
• delay (optional) - Time delay (in seconds) to wait AFTER issuing any command to the device. This delay will give the spotify zeroconf api time to process the change before another command is issued. Default is 0.25; value range is 0 - 10.

Example YAML

service: spotifyplus.get_spotify_connect_device
data:
  entity_id: media_player.spotifyplus_john_s
  device_value: Bose-ST10-1
  verify_user_context: true
  verify_timeout: 0.5
  refresh_device_list: false
  activate_device: true  

Example Response

A dictionary that contains the following keys:

• user_profile: A (partial) user profile that retrieved the result.
• result: A list of Device objects that contain the device details, sorted by name.

user_profile:
  country: US
  display_name: John Smith
  email: jsmith@maildomain.com
  id: 3758dfdsfjk435hjk6k79lm0n3c4
  product: premium
  type: user
  uri: spotify:user:3758dfdsfjk435hjk6k79lm0n3c4
result:
  Id: 30fbc80e35598f3c242f2120413c943dfd9715fe
  Name: Bose-ST10-1
  WasReConnected: false
  DeviceInfo:
    SpotifyError: 0
    Status: 101
    StatusString: OK
    ResponseSource: null
    AccountReq: DONTCARE
    ActiveUser: ... redacted ...
    Aliases: []
    Availability: ""
    BrandDisplayName: Bose
    ClientId: ... redacted ...
    DeviceId: 30fbc80e35598f3c242f2120413c943dfd9715fe
    DeviceType: SPEAKER
    GroupStatus: NONE
    LibraryVersion: 3.88.29-gc4d4bb01
    ModelDisplayName: Soundtouch
    ProductId: 70001
    PublicKey: ... redacted ...
    RemoteName: Bose-ST10-1
    ResolverVersion: "0"
    Scope: streaming
    SupportedCapabilities: null
    SupportedDrmMediaFormats: []
    TokenType: accesstoken
    Version: 2.7.1
    VoiceSupport: "YES"
    IsActiveDevice: false
    IsInDeviceList: true
  DiscoveryResult:
    DeviceName: Bose-ST10-1
    Domain: .local
    HostIpAddress: 192.168.1.81
    HostIpAddresses:
      - 192.168.1.81
    HostIpPort: 8200
    HostTTL: 120
    Key: bose-st10-1._spotify-connect._tcp.local.
    Name: Bose-ST10-1._spotify-connect._tcp.local.
    Priority: 0
    OtherTTL: 4500
    Server: Bose-SM2-341513fbeeae.local.
    ServerKey: bose-sm2-341513fbeeae.local.
    ServiceType: _spotify-connect._tcp.local.
    Weight: 0
    Properties:
      - Name: CPath
        Value: /zc
      - Name: VERSION
        Value: "1.0"
    SpotifyConnectCPath: /zc
    SpotifyConnectIsInDeviceList: false
    SpotifyConnectVersion: "1.0"
    ZeroconfApiEndpointAddUser: http://192.168.1.81:8200/zc?action=addUser&version=1.0
    ZeroconfApiEndpointGetInformation: http://192.168.1.81:8200/zc?action=getInfo&version=1.0
    ZeroconfApiEndpointResetUsers: http://192.168.1.81:8200/zc?action=resetUsers&version=1.0

Get Spotify Connect Devices

Get information about all available Spotify Connect player (both static and dynamic) devices.

This service is similar to the Get Player Devices service, but it contains ALL available Spotify Connect devices that are known to the local network (versus just the devices known to a specific user).

This service gathers Spotify Connect device information from Zeroconf (for static devices) as well as the Get Player Devices service (for dynamic devices). Dynamic devices are Spotify Connect devices that are not found in Zeroconf discovery process, but still exist in the player device list. These are usually Spotify Connect web or mobile players with temporary device id's.

Note that only certain properties of the returned DeviceResult objects are populated if IsDynamicDevice: true, as the information is gathered from a dynamic device.

This service will return service response data.

Parameters

All parameters are required unless otherwise noted.

• entity_id - Entity ID of the SpotifyPlus service that will make the request to the Spotify Web API.
• refresh (optional) - True (default) to return real-time information from the spotify zeroconf api and update the cache; otherwise, False to just return the cached value.
• sort_result (optional) - True to sort the items by name; otherwise, False to leave the items in the same order they were returned in by the Spotify Web API. Default is True.

Example YAML

service: spotifyplus.get_spotify_connect_devices
data:
  entity_id: media_player.spotifyplus_john_s

Example Response

A dictionary that contains the following keys:

• user_profile: A (partial) user profile that retrieved the result.
• result: A SpotifyConnectDevices object that contain the device details.

user_profile:
  country: US
  display_name: John Smith
  email: jsmith@maildomain.com
  id: 3758dfdsfjk435hjk6k79lm0n3c4
  product: premium
  type: user
  uri: spotify:user:3758dfdsfjk435hjk6k79lm0n3c4
result:
  AgeLastRefreshed: 0.004431962966918945
  DateLastRefreshed: 1728347123.171437
  ItemsCount: 5
  Items:
    - Id: 30fbc80e35598f3c242f2120413c943dfd9715fe
      Name: Bose-ST10-1
      Title: Bose-ST10-1 (30fbc80e35598f3c242f2120413c943dfd9715fe)
      WasReConnected: false
      DeviceInfo:
        SpotifyError: 0
        Status: 101
        StatusString: OK
        ResponseSource: null
        AccountReq: DONTCARE
        ActiveUser: thlucas2010@gmail.com
        Aliases: []
        Availability: ""
        BrandDisplayName: Bose
        ClientId: 79ebcb2168936e9a892e795557931810
        DeviceId: 30fbc80e35598f3c242f2120413c943dfd9715fe
        DeviceType: SPEAKER
        GroupStatus: NONE
        LibraryVersion: 3.88.29-gc4d4bb01
        ModelDisplayName: Soundtouch
        ProductId: 70001
        PublicKey: eDzNVMgBm6bOGx ... cdK
        RemoteName: Bose-ST10-1
        ResolverVersion: "0"
        Scope: streaming
        SupportedCapabilities: null
        SupportedDrmMediaFormats: []
        TokenType: accesstoken
        Version: 2.7.1
        VoiceSupport: "YES"
        HasActiveUser: true
        HasAliases: false
        IsAvailable: true
        IsBrandSonos: false
        IsActiveDevice: false
        IsInDeviceList: true
      DiscoveryResult:
        DeviceName: Bose-ST10-1
        Domain: .local
        HostIpAddress: 192.168.1.81
        HostIpAddresses:
          - 192.168.1.81
        HostIpPort: 8200
        HostTTL: 120
        IsDynamicDevice: false
        Key: bose-st10-1._spotify-connect._tcp.local.
        Name: Bose-ST10-1._spotify-connect._tcp.local.
        Priority: 0
        OtherTTL: 4500
        Server: Bose-SM2-3415670beeae.local.
        ServerKey: bose-sm2-3415670beeae.local.
        ServiceType: _spotify-connect._tcp.local.
        Weight: 0
        Properties:
          - Name: CPath
            Value: /zc
          - Name: VERSION
            Value: "1.0"
        SpotifyConnectCPath: /zc
        SpotifyConnectIsInDeviceList: false
        SpotifyConnectVersion: "1.0"
        ZeroconfApiEndpointAddUser: http://192.168.1.81:8200/zc?action=addUser&version=1.0
        ZeroconfApiEndpointGetInformation: http://192.168.1.81:8200/zc?action=getInfo&version=1.0
        ZeroconfApiEndpointResetUsers: http://192.168.1.81:8200/zc?action=resetUsers&version=1.0
    - Id: 5d4931f9d0684b625d702eaa24137b2c1d99539c
      Name: Bose-ST10-2
      Title: Bose-ST10-2 (5d4931f9d0684b625d702eaa24137b2c1d99539c)
... truncated for example

Get Track

Get Spotify catalog information for a single track identified by its unique Spotify ID.

This service will return service response data.

Parameters

All parameters are required unless otherwise noted.

• entity_id - Entity ID of the SpotifyPlus service that will make the request to the Spotify Web API.
• track_id (optional) - The Spotify ID for the track. If omitted, the currently playing track uri id value is used. Example: 1kWUud3vY5ij5r62zxpTRy

Example YAML

service: spotifyplus.get_track
data:
  entity_id: media_player.spotifyplus_john_s
  track_id: 1kWUud3vY5ij5r62zxpTRy

Example Response

A dictionary that contains the following keys:

• user_profile: A (partial) user profile that retrieved the result.
• result: A Track object that contain the track details.

user_profile:
  country: US
  display_name: John Smith
  email: jsmith@maildomain.com
  id: 3758dfdsfjk435hjk6k79lm0n3c4
  product: premium
  type: user
  uri: spotify:user:3758dfdsfjk435hjk6k79lm0n3c4
result:
  ... <data truncated for brevity - same results as Spotify Web API returns>

Get Track Favorites

Get a list of the tracks saved in the current Spotify user's 'Your Library'.

This service will return service response data.

Parameters

All parameters are required unless otherwise noted.

• entity_id - Entity ID of the SpotifyPlus service that will make the request to the Spotify Web API.
• limit (optional) - The maximum number of items to return in a page of items. Default is 20, Range is 1 to 50.
• offset (optional) - The page index offset of the first item to return. Use with limit to get the next set of items. Default is 0 (the first item).
• market (optional) - An ISO 3166-1 alpha-2 country code. If a country code is specified, only content that is available in that market will be returned. The country associated with the user account will take priority over this parameter. example: US
• limit_total (optional) - The maximum number of items to return for the request. If specified, this parameter overrides the limit and offset parameter values and paging is automatically used to retrieve all available items up to the specified limit total.
• sort_result (optional) - True to sort the items by name; otherwise, False to leave the items in the same order they were returned in by the Spotify Web API. Default is True.

Example YAML

service: spotifyplus.get_track_favorites
data:
  entity_id: media_player.spotifyplus_john_s
  limit_total: 100

Example Response

A dictionary that contains the following keys:

• user_profile: A (partial) user profile that retrieved the result.
• result: A TrackPageSaved object that contains playlist information.

user_profile:
  country: US
  display_name: John Smith
  email: jsmith@maildomain.com
  id: 3758dfdsfjk435hjk6k79lm0n3c4
  product: premium
  type: user
  uri: spotify:user:3758dfdsfjk435hjk6k79lm0n3c4
result:
  ... <data truncated for brevity - same results as Spotify Web API returns>

Get Track Recommendations

DEPRECATED API endpoint no longer supported by Spotify as of 2024/11/27. More information about the deprecated functionality can be found on the Spotify Developer Forum Blog page.

Get track recommendations for specified criteria.

This service will return service response data.

Parameters

All parameters are required unless otherwise noted.

Note that at least 1 of seed_artists, seed_genres, or seed_tracks is required. They are marked (optional) below, as not ALL are required.

• entity_id - Entity ID of the SpotifyPlus service that will make the request to the Spotify Web API.
• limit (optional) - The maximum number of items to return in a page of items. Default is 20, Range is 1 to 50.
• market (optional) - An ISO 3166-1 alpha-2 country code. If a country code is specified, only content that is available in that market will be returned. The country associated with the user account will take priority over this parameter. example: US
• seed_artists (optional) - A comma separated list of Spotify IDs for seed artists (e.g. 4NHQUGzhtTLFvgF5SZesLK). Up to 5 seed values may be provided in any combination of seedArtists, seedTracks and seedGenres; only required if seedGenres and seedTracks are not set.
• seed_genres (optional) - A comma separated list of any genres in the set of available genre seeds (e.g. classical,country). Up to 5 seed values may be provided in any combination of seedArtists, seedTracks and seedGenres; only required if seedArtists and seedTracks are not set.
• seed_tracks (optional) - A comma separated list of Spotify IDs for a seed track (e.g. 0c6xIDDpzE81m2q797ordA). Up to 5 seed values may be provided in any combination of seedArtists, seedTracks and seedGenres; only required if seedArtists and seedGenres are not set.
• min_acousticness (optional) - Restrict results to only those tracks whose acousticness level is greater than the specified value. Range is 0 - 1.
• max_acousticness (optional) - Restrict results to only those tracks whose acousticness level is less than the specified value. Range is 0 - 1.
• target_acousticness (optional) - Restrict results to only those tracks whose acousticness level is equal to the specified value. Range is 0 - 1.
• min_danceability (optional) - Restrict results to only those tracks whose danceability level is greater than the specified value. Range is 0 - 1.
• max_danceability (optional) - Restrict results to only those tracks whose danceability level is less than the specified value. Range is 0 - 1.
• target_danceability (optional) - Restrict results to only those tracks whose acousticness is equal to the specified value. Range is 0 - 1.
• min_duration_ms (optional) - Restrict results to only those tracks whose duration is greater than the specified value in milliseconds.
• max_duration_ms (optional) - Restrict results to only those tracks whose duration is less than the specified value in milliseconds.
• target_duration_ms (optional) - Restrict results to only those tracks whose duration is equal to the specified value in milliseconds.
• min_energy (optional) - Restrict results to only those tracks whose energy level is greater than the specified value. Range is 0 - 1.
• max_energy (optional) - Restrict results to only those tracks whose energy level is less than the specified value. Range is 0 - 1.
• target_energy (optional) - Restrict results to only those tracks whose energy level is equal to the specified value. Range is 0 - 1.
• min_instrumentalness (optional) - Restrict results to only those tracks whose instrumentalness level is greater than the specified value. Range is 0 - 1.
• max_instrumentalness (optional) - Restrict results to only those tracks whose instrumentalness level is less than the specified value. Range is 0 - 1.
• target_instrumentalness (optional) - Restrict results to only those tracks whose instrumentalness level is equal to the specified value. Range is 0 - 1.
• min_key (optional) - Restrict results to only those tracks whose key level is greater than the specified value. Range is 0 - 11.
• max_key (optional) - Restrict results to only those tracks whose key level is less than the specified value. Range is 0 - 11.
• target_key (optional) - Restrict results to only those tracks whose key level is equal to the specified value. Range is 0 - 11.
• min_liveness (optional) - Restrict results to only those tracks whose liveness level is greater than the specified value. Range is 0 - 1.
• max_liveness (optional) - Restrict results to only those tracks whose liveness level is less than the specified value. Range is 0 - 1.
• target_liveness (optional) - Restrict results to only those tracks whose liveness level is equal to the specified value. Range is 0 - 1.
• min_loudness (optional) - Restrict results to only those tracks whose loudness level is greater than the specified value.
• max_loudness (optional) - Restrict results to only those tracks whose loudness level is less than the specified value.
• target_loudness (optional) - Restrict results to only those tracks whose loudness level is equal to the specified value.
• min_mode (optional) - Restrict results to only those tracks whose mode level is greater than the specified value. Range is 0 - 1.
• max_mode (optional) - Restrict results to only those tracks whose mode level is less than the specified value. Range is 0 - 1.
• target_mode (optional) - Restrict results to only those tracks whose mode level is equal to the specified value. Range is 0 - 1.
• min_popularity (optional) - Restrict results to only those tracks whose popularity level is greater than the specified value. Range is 0 - 100.
• max_popularity (optional) - Restrict results to only those tracks whose popularity level is less than the specified value. Range is 0 - 100.
• target_popularity (optional) - Restrict results to only those tracks whose popularity level is equal to the specified value. Range is 0 - 100.
• min_speechiness (optional) - Restrict results to only those tracks whose speechiness level is greater than the specified value. Range is 0 - 1.
• max_speechiness (optional) - Restrict results to only those tracks whose speechiness level is less than the specified value. Range is 0 - 1.
• target_speechiness (optional) - Restrict results to only those tracks whose speechiness level is equal to the specified value. Range is 0 - 1.
• min_tempo (optional) - Restrict results to only those tracks with a tempo greater than the specified number of beats per minute.
• max_tempo (optional) - Restrict results to only those tracks with a tempo less than the specified number of beats per minute.
• target_tempo (optional) - Restrict results to only those tracks with a tempo equal to the specified number of beats per minute.
• min_time_signature (optional) - Restrict results to only those tracks whose time signature is greater than the specified value. Range is 0 - 11.
• max_time_signature (optional) - Restrict results to only those tracks whose time signature is less than the specified value. Range is 0 - 11.
• target_time_signature (optional) - Restrict results to only those tracks whose time signature is equal to the specified value. Range is 0 - 11.
• min_valence (optional) - Restrict results to only those tracks whose valence level is greater than the specified value. Range is 0 - 1.
• max_valence (optional) - Restrict results to only those tracks whose valence level is less than the specified value. Range is 0 - 1.
• target_valence (optional) - Restrict results to only those tracks whose valence level is equal to the specified value. Range is 0 - 1.

Example YAML

I wanna rock! example ...

service: spotifyplus.get_track_recommendations
data:
  entity_id: media_player.spotifyplus_john_s
  limit_total: 50
  seed_genres: "rock,hard-rock,rock-n-roll"
  min_loudness: -9.201
  min_time_signature: 4
  min_energy: 0.975

I wanna wind down example - artist George Winston (e.g. 3jdODvx7rIdq0UGU7BOVR3) ...

service: spotifyplus.get_track_recommendations
data:
  entity_id: media_player.spotifyplus_john_s
  limit_total: 50
  seed_artists: "3jdODvx7rIdq0UGU7BOVR3"
  seed_genres: "piano"
  max_energy: 0.275

Example Response

A dictionary that contains the following keys:

• user_profile: A (partial) user profile that retrieved the result.
• result: A TrackPageSaved object that contains playlist information.

user_profile:
  country: US
  display_name: John Smith
  email: jsmith@maildomain.com
  id: 3758dfdsfjk435hjk6k79lm0n3c4
  product: premium
  type: user
  uri: spotify:user:3758dfdsfjk435hjk6k79lm0n3c4
result:
  ... <data truncated for brevity - same results as Spotify Web API returns>

Get Tracks Audio Features

DEPRECATED API endpoint no longer supported by Spotify as of 2024/11/27. More information about the deprecated functionality can be found on the Spotify Developer Forum Blog page.

Get audio features for multiple tracks based on their Spotify IDs.

This service will return service response data.

Parameters

All parameters are required unless otherwise noted.

• entity_id - Entity ID of the SpotifyPlus service that will make the request to the Spotify Web API.
• ids - A comma-separated list of the Spotify track IDs. Maximum of 100 IDs. Example = 7ouMYWpwJ422jRcDASZB7P,4VqPOruhp5EdPBeR92t6lQ,2takcwOaAZWiXQijPHIx7B.

Example YAML

service: spotifyplus.get_tracks_audio_features
data:
  entity_id: media_player.spotifyplus_john_s
  ids: 7ouMYWpwJ422jRcDASZB7P,4VqPOruhp5EdPBeR92t6lQ,2takcwOaAZWiXQijPHIx7B  

Example Response

A dictionary that contains the following keys:

• user_profile: A (partial) user profile that retrieved the result.
• result: A list of AudioFeatures objects that contain the audio feature details.

user_profile:
  country: US
  display_name: John Smith
  email: jsmith@maildomain.com
  id: 3758dfdsfjk435hjk6k79lm0n3c4
  product: premium
  type: user
  uri: spotify:user:3758dfdsfjk435hjk6k79lm0n3c4
result:
  - acousticness: 0.000273
    analysis_url: https://api.spotify.com/v1/audio-analysis/7ouMYWpwJ422jRcDASZB7P
    danceability: 0.366
    duration_ms: 366213
    energy: 0.963
    id: 7ouMYWpwJ422jRcDASZB7P
    instrumentalness: 0.0122
    key: 11
    liveness: 0.115
    loudness: -5.301
    mode: 0
    speechiness: 0.142
    tempo: 137.114
    time_signature: 4
    track_href: https://api.spotify.com/v1/tracks/7ouMYWpwJ422jRcDASZB7P
    type: audio_features
    uri: spotify:track:7ouMYWpwJ422jRcDASZB7P
    valence: 0.211
  ... <data truncated for brevity - same results as Spotify Web API returns>

Get Users Top Artists

Get the current user's top artists based on calculated affinity.

This service will return service response data.

Parameters

All parameters are required unless otherwise noted.

• entity_id - Entity ID of the SpotifyPlus service that will make the request to the Spotify Web API.
• time_range - Over what time frame the affinities are computed. Valid values are long_term (calculated from several years of data and including all new data as it becomes available), medium_term (approximately last 6 months), and short_term (approximately last 4 weeks). Example: "long_term"
• limit (optional) - The maximum number of items to return in a page of items. Default is 20, Range is 1 to 50.
• offset (optional) - The page index offset of the first item to return. Use with limit to get the next set of items. Default is 0 (the first item).
• limit_total (optional) - The maximum number of items to return for the request. If specified, this parameter overrides the limit and offset parameter values and paging is automatically used to retrieve all available items up to the specified limit total.
• sort_result (optional) - True to sort the items by name; otherwise, False to leave the items in the same order they were returned in by the Spotify Web API. Default is True.

Example YAML

service: spotifyplus.get_users_top_artists
data:
  entity_id: media_player.spotifyplus_john_s
  time_range: long_term
  limit_total: 20

Example Response

A dictionary that contains the following keys:

• user_profile: A (partial) user profile that retrieved the result.
• result: An ArtistPage object of matching results.

user_profile:
  country: US
  display_name: John Smith
  email: jsmith@maildomain.com
  id: 3758dfdsfjk435hjk6k79lm0n3c4
  product: premium
  type: user
  uri: spotify:user:3758dfdsfjk435hjk6k79lm0n3c4
result:
  ... <data truncated for brevity - same results as Spotify Web API returns>

Get Users Top Tracks

Get the current user's top tracks based on calculated affinity.

This service will return service response data.

Parameters

All parameters are required unless otherwise noted.

• entity_id - Entity ID of the SpotifyPlus service that will make the request to the Spotify Web API.
• time_range - Over what time frame the affinities are computed. Valid values are long_term (calculated from several years of data and including all new data as it becomes available), medium_term (approximately last 6 months), and short_term (approximately last 4 weeks). Example: "long_term"
• limit (optional) - The maximum number of items to return in a page of items. Default is 20, Range is 1 to 50.
• offset (optional) - The page index offset of the first item to return. Use with limit to get the next set of items. Default is 0 (the first item).
• limit_total (optional) - The maximum number of items to return for the request. If specified, this parameter overrides the limit and offset parameter values and paging is automatically used to retrieve all available items up to the specified limit total.
• sort_result (optional) - True to sort the items by name; otherwise, False to leave the items in the same order they were returned in by the Spotify Web API. Default is True.

Example YAML

service: spotifyplus.get_users_top_tracks
data:
  entity_id: media_player.spotifyplus_john_s
  time_range: long_term
  limit_total: 20

Example Response

A dictionary that contains the following keys:

• user_profile: A (partial) user profile that retrieved the result.
• result: A TrackPage object of matching results.

user_profile:
  country: US
  display_name: John Smith
  email: jsmith@maildomain.com
  id: 3758dfdsfjk435hjk6k79lm0n3c4
  product: premium
  type: user
  uri: spotify:user:3758dfdsfjk435hjk6k79lm0n3c4
result:
  ... <data truncated for brevity - same results as Spotify Web API returns>

Player Activate Devices

Activates all static Spotify Connect player devices, and (optionally) switches the active user context to the current user context.

A Zeroconf discovery process is initiated to search for all Spotify Connect devices connected to the local network. It will then iterate through the returned devices and perform the following on each one:

• call Spotify Zeroconf API getInfo endpoint to retrieve device information.
• call Spotify Zeroconf API resetUsers endpoint to disconnect the device. This step is omitted for dynamic devices (see note below). Note that this will force any users that are connected to the device off of the device.
• call Spotify Zeroconf API addUser endpoint to connect the device. This step is omitted for dynamic devices (see note below). This should "re-awaken" the device if necessary, and make it ready for immediate use.

Dynamic Spotify Connect devices are not processed by this method, as they are temporary devices and are already active and in the device list. These devices are not found in Zeroconf discovery process, and only exist in the player device list. These are usually Spotify Connect web or mobile players with temporary device id's.

Note that the SpotifyConnectUsername, SpotifyConnectPassword, and SpotifyConnectLoginId configuration options must be specified in order to use this method. They are all required in order to reactivate a Spotify Connect device.

This service will return service response data.

Parameters

All parameters are required unless otherwise noted.

• entity_id - Entity ID of the SpotifyPlus service that will make the request to the Spotify Web API.
• verify_user_context (optional) - If True, the active user context of the resolved device is checked to ensure it matches the specified Spotify Connect user context. If False, the user context will not be checked. Default is False.
• delay (optional) - Time delay (in seconds) to wait AFTER issuing the final Connect command (if necessary). This delay will give the spotify web api time to process the device list change before another command is issued. Default is 0.50; value range is 0 - 10.

Example YAML

Activate all Spotify Connect player devices on the local network and switch the device user context to our user context. This will disconnect other users from all spotify connect player devices defined to the local network.

service: spotifyplus.player_activate_devices
data:
  entity_id: media_player.spotifyplus_john_s
  verify_user_context: true
  delay: 0.5

Example Response

A dictionary that contains the following keys:

• user_profile: A (partial) user profile that retrieved the result.
• result: A string object that contains result details.

user_profile:
  country: US
  display_name: John Smith
  email: jsmith@maildomain.com
  id: 3758dfdsfjk435hjk6k79lm0n3c4
  product: premium
  type: user
  uri: spotify:user:3758dfdsfjk435hjk6k79lm0n3c4
result: >
  - Device Name="Bose-ST10-2", ID="5d4931f9d0684b625d702eaa24137b2c1d99539c",
  ActiveUser="3758dfdsfjk435hjk6k79lm0n3c4", Status=ACTIVE, user context switch
  not needed

  - Device Name="Bose-ST10-1", ID="30fbc80e35598f3c242f2120413c943dfd9715fe",
  ActiveUser="3758dfdsfjk435hjk6k79lm0n3c4", Status=ACTIVE, user context switch
  not needed

  - Device Name="Bose-ST300", ID="3756903295ba7b47f8c36fc9a4ff7d833431a667",
  ActiveUser="3758dfdsfjk435hjk6k79lm0n3c4", Status=ACTIVE, user context switch
  not needed

Example YAML

Activate all Spotify Connect player devices on the local network without switching the device user context.

service: spotifyplus.player_activate_devices
data:
  entity_id: media_player.spotifyplus_john_s
  verify_user_context: false
  delay: 0.5

Example Response

A dictionary that contains the following keys:

• user_profile: A (partial) user profile that retrieved the result.
• result: A string object that contains result details.

user_profile:
  country: US
  display_name: John Smith
  email: jsmith@maildomain.com
  id: 3758dfdsfjk435hjk6k79lm0n3c4
  product: premium
  type: user
  uri: spotify:user:3758dfdsfjk435hjk6k79lm0n3c4
result: >
  - Device Name="Bose-ST10-2", ID="5d4931f9d0684b625d702eaa24137b2c1d99539c",
  ActiveUser="3758dfdsfjk435hjk6k79lm0n3c4", Status=ACTIVE, caller bypassed user
  context switch

  - Device Name="Bose-ST10-1", ID="30fbc80e35598f3c242f2120413c943dfd9715fe",
  ActiveUser="3758dfdsfjk435hjk6k79lm0n3c4", Status=ACTIVE, caller bypassed user
  context switch

  - Device Name="Bose-ST300", ID="3756903295ba7b47f8c36fc9a4ff7d833431a667",
  ActiveUser="3758dfdsfjk435hjk6k79lm0n3c4", Status=ACTIVE, caller bypassed user
  context switch

Player Media Pause

Pause media play for the specified Spotify Connect device.

Parameters

All parameters are required unless otherwise noted.

• entity_id - Entity ID of the SpotifyPlus service that will make the request to the Spotify Web API.
• device_id (optional) - The id of the device this command is targeting. If not supplied, the user's currently active device is the target. If no device is active (or an "*" is specified), then the SpotifyPlus default device is activated.
• delay (optional) - Time delay (in seconds) to wait AFTER issuing the command to the player. This delay will give the spotify web api time to process the change before another command is issued. Default is 0.50; value range is 0 - 10.

Example YAML

service: spotifyplus.player_media_pause
data:
  entity_id: media_player.spotifyplus_john_s
  device_id: Office

Player Media Play Context

Start playing one or more tracks of the specified context on a Spotify Connect device.

Valid contexts are albums, artists & playlists - Audiobooks and Shows (aka podcasts) are currently not supported (Spotify Web API limitation).

Parameters

All parameters are required unless otherwise noted.

• entity_id - Entity ID of the SpotifyPlus service that will make the request to the Spotify Web API.
• context_uri - Spotify URI of the context to play. Valid contexts are albums, artists & playlists. Example: "spotify:album:6vc9OTcyd3hyzabCmsdnwE"
• offset_uri - Indicates from what Uri in the context playback should start. Only available when contextUri corresponds to an artist, album or playlist. The offsetPosition parameter will be used if this value is null. Example: "spotify:track:1301WleyT98MSxVHPZCA6M"
• offset_position - Indicates from what position in the context playback should start. The value is zero-based, and can't be negative. Only available when contextUri corresponds to an album or playlist. Example: 3
• position_ms - The position (in milliseconds) to seek to; must be a positive number. Passing in a position that is greater than the length of the track will cause the player to start playing the next track. Example: 0
• device_id - The id of the device this command is targeting. If not supplied, the user's currently active device is the target. If no device is active (or an "*" is specified), then the SpotifyPlus default device is activated.
• delay (optional) - Time delay (in seconds) to wait AFTER issuing the command to the player. This delay will give the spotify web api time to process the change before another command is issued. Default is 0.50; value range is 0 - 10.

Example YAML

Play the specified album, starting at the first track (zero offset) on the SpotifyPlus default device.

service: spotifyplus.player_media_play_context
data:
  entity_id: media_player.spotifyplus_john_s
  context_uri: spotify:album:6vc9OTcyd3hyzabCmsdnwE
  offset_position: 0
  device_id: "*"

Play the specified album, starting at the fourth track (zero offset).

service: spotifyplus.player_media_play_context
data:
  entity_id: media_player.spotifyplus_john_s
  context_uri: spotify:album:6vc9OTcyd3hyzabCmsdnwE
  offset_position: 3

Play the specified playlist, starting at the specified track URI.

service: spotifyplus.player_media_play_context
data:
  entity_id: media_player.spotifyplus_john_s
  context_uri: spotify:playlist:6M8n0Sp9895BXEE0MbGPde
  offset_uri: spotify:track:6zb0RH9FmYB8Ronad1uK02

Play the specified playlist, starting at the first track at the 50 second seek position.

service: spotifyplus.player_media_play_context
data:
  entity_id: media_player.spotifyplus_john_s
  context_uri: spotify:playlist:6M8n0Sp9895BXEE0MbGPde
  position_ms: 50000

Play the specified show (aka. podcast) on the SpotifyPlus default device.

service: spotifyplus.player_media_play_context
data:
  entity_id: media_player.spotifyplus_john_s
  context_uri: spotify:show:3IM0lmZxpFAY7CwMuv9H4g
  device_id: "*"

Player Media Play Track Favorites

Start playing track favorites on a Spotify Connect device.

This service simply calls the GetTrackFavorites method to retrieve the current users favorite tracks (200 max), then calls the PlayerMediaPlayTracks method to play them. The desired shuffle mode is also set before tracks are played.

Limitations

For Sonos devices, the tracks (up to 200 max) are loaded to a local queue on the Sonos device and played from there. This can be a lengthy operation, depending on the number of track favorites that you have. It takes about 1 second to load 5 tracks, give or take based upon the speed of your network.

Parameters

All parameters are required unless otherwise noted.

• entity_id - Entity ID of the SpotifyPlus service that will make the request to the Spotify Web API.
• device_id (optional) - The id of the device this command is targeting. If not supplied, the user's currently active device is the target. If no device is active (or an "*" is specified), then the SpotifyPlus default device is activated.
• shuffle (optional) - True to set player shuffle mode to on; otherwise, False for no shuffle. Default is True.
• delay (optional) - Time delay (in seconds) to wait AFTER issuing the command to the player. This delay will give the spotify web api time to process the change before another command is issued. Default is 0.50; value range is 0 - 10.

Example YAML

Play the specified tracks.

service: spotifyplus.player_media_play_track_favorites
data:
  entity_id: media_player.spotifyplus_john_s
  device_id: "*"
  shuffle: true
  delay: 0.50

Player Media Play Tracks

Start playing one or more tracks on a Spotify Connect device.

Valid contexts are albums, artists & playlists - Audiobooks and Shows (aka podcasts) are currently not supported (Spotify Web API limitation).

Parameters

All parameters are required unless otherwise noted.

• entity_id - Entity ID of the SpotifyPlus service that will make the request to the Spotify Web API.
• uris - A list of Spotify track URIs to play; can be track or episode URIs. Example: "spotify:track:4iV5W9uYEdYUVa79Axb7Rh,spotify:episode:512ojhOuo1ktJprKbVcKyQ".
• position_ms - The position (in milliseconds) to seek to; must be a positive number. Passing in a position that is greater than the length of the track will cause the player to start playing the next track. Example: 0
• device_id - The id of the device this command is targeting. If not supplied, the user's currently active device is the target. If no device is active (or an "*" is specified), then the SpotifyPlus default device is activated.
• delay (optional) - Time delay (in seconds) to wait AFTER issuing the command to the player. This delay will give the spotify web api time to process the change before another command is issued. Default is 0.50; value range is 0 - 10.

Example YAML

Play the specified tracks.

service: spotifyplus.player_media_play_tracks
data:
  entity_id: media_player.spotifyplus_john_s
  uris: spotify:track:6zd8T1PBe9JFHmuVnurdRp,spotify:track:1kWUud3vY5ij5r62zxpTRy

Play the specified tracks, starting at the 50 second seek position.

service: spotifyplus.player_media_play_tracks
data:
  entity_id: media_player.spotifyplus_john_s
  uris: spotify:track:6zd8T1PBe9JFHmuVnurdRp,spotify:track:1kWUud3vY5ij5r62zxpTRy
  position_ms: 50000

Player Media Resume

Resume media play for the specified Spotify Connect device.

Parameters

All parameters are required unless otherwise noted.

• entity_id - Entity ID of the SpotifyPlus service that will make the request to the Spotify Web API.
• device_id (optional) - The id of the device this command is targeting. If not supplied, the user's currently active device is the target. If no device is active (or an "*" is specified), then the SpotifyPlus default device is activated.
• delay (optional) - Time delay (in seconds) to wait AFTER issuing the command to the player. This delay will give the spotify web api time to process the change before another command is issued. Default is 0.50; value range is 0 - 10.

Example YAML

service: spotifyplus.player_media_resume
data:
  entity_id: media_player.spotifyplus_john_s
  device_id: Office

Player Media Seek

Seeks to the given absolute or relative position in the user's currently playing track for the specified Spotify Connect device.

Parameters

All parameters are required unless otherwise noted.

• entity_id - Entity ID of the SpotifyPlus service that will make the request to the Spotify Web API.
• position_ms (optional) - The absolute position in milliseconds to seek to; must be a positive number or zero if the relativePositionMS argument is specified. Passing in a position that is greater than the length of the track will cause the player to start playing the next song. Example = 25000 to start playing at the 25 second mark.
• device_id (optional) - The id of the device this command is targeting. If not supplied, the user's currently active device is the target. If no device is active (or an "*" is specified), then the SpotifyPlus default device is activated.
• delay (optional) - Time delay (in seconds) to wait AFTER issuing the command to the player. This delay will give the spotify web api time to process the change before another command is issued. Default is 0.50; value range is 0 - 10.
• relative_position_ms (optional) - The relative position in milliseconds to seek to; can be a positive or negative number, or zero if the positionMS argument is specified. Example = -10000 to seek behind by 10 seconds; 10000 to seek ahead by 10 seconds.

Example YAML

Seek ahead by 10 seconds (10000 milliseconds).

service: spotifyplus.player_media_seek
data:
  entity_id: media_player.spotifyplus_john_s
  relative_position_ms: 10000
  delay: 0

Seek behind by 25 seconds (25000 milliseconds)

service: spotifyplus.player_media_seek
data:
  entity_id: media_player.spotifyplus_john_s
  relative_position_ms: -25000
  delay: 0

Player Media Skip Next

Skips to next track in the user's queue for the specified Spotify Connect device.

Parameters

All parameters are required unless otherwise noted.

• entity_id - Entity ID of the SpotifyPlus service that will make the request to the Spotify Web API.
• device_id (optional) - The id of the device this command is targeting. If not supplied, the user's currently active device is the target. If no device is active (or an "*" is specified), then the SpotifyPlus default device is activated.
• delay (optional) - Time delay (in seconds) to wait AFTER issuing the command to the player. This delay will give the spotify web api time to process the change before another command is issued. Default is 0.50; value range is 0 - 10.

Example YAML

service: spotifyplus.player_media_skip_next
data:
  entity_id: media_player.spotifyplus_john_s
  device_id: Office

Player Media Skip Previous

Skips to previous track in the user's queue for the specified Spotify Connect device.

Parameters

All parameters are required unless otherwise noted.

• entity_id - Entity ID of the SpotifyPlus service that will make the request to the Spotify Web API.
• device_id (optional) - The id of the device this command is targeting. If not supplied, the user's currently active device is the target. If no device is active (or an "*" is specified), then the SpotifyPlus default device is activated.
• delay (optional) - Time delay (in seconds) to wait AFTER issuing the command to the player. This delay will give the spotify web api time to process the change before another command is issued. Default is 0.50; value range is 0 - 10.

Example YAML

service: spotifyplus.player_media_skip_previous
data:
  entity_id: media_player.spotifyplus_john_s
  device_id: Office

Player Resolve Device ID

Deprecated - this method will be removed in a future release. Use the Get Spotify Connect Device method instead.

Resolves a Spotify Connect device identifier from a specified device id, name, alias id, or alias name. This will ensure that the device id can be found on the network, as well as connect to the device if necessary with the current user context.

Player Set Repeat Mode

Set repeat mode for the specified Spotify Connect device.

Use this service instead of the media_player.repeat_set when you want to set the repeat mode for a specific Spotify Player device id.

Parameters

All parameters are required unless otherwise noted.

• entity_id - Entity ID of the SpotifyPlus service that will make the request to the Spotify Web API.
• state - The repeat mode state to set:
  • track - will repeat the current track.
  • context - will repeat the current context.
  • off - will turn repeat off.
• device_id (optional) - The id of the device this command is targeting. If not supplied, the user's currently active device is the target. If no device is active (or an "*" is specified), then the SpotifyPlus default device is activated.
• delay (optional) - Time delay (in seconds) to wait AFTER issuing the command to the player. This delay will give the spotify web api time to process the change before another command is issued. Default is 0.50; value range is 0 - 10.

Example YAML

Set repeat mode to repeat the currently playing track for the "Bose-ST10-1" player.

service: spotifyplus.player_set_shuffle_mode
data:
  entity_id: media_player.spotifyplus_john_s
  state: track
  device_id: Bose-ST10-1

Set repeat mode to repeat the currently playing playlist for the "Bose-ST10-1" player.

service: spotifyplus.player_set_shuffle_mode
data:
  entity_id: media_player.spotifyplus_john_s
  state: context
  device_id: Bose-ST10-1

Set repeat mode to off for the "Bose-ST10-1" player.

service: spotifyplus.player_set_shuffle_mode
data:
  entity_id: media_player.spotifyplus_john_s
  state: off
  device_id: Bose-ST10-1

Player Set Shuffle Mode

Set shuffle mode for the specified Spotify Connect device.

Use this service instead of the media_player.shuffle_set when you want to set the shuffle mode for a specific Spotify Player device id.

Parameters

All parameters are required unless otherwise noted.

• entity_id - Entity ID of the SpotifyPlus service that will make the request to the Spotify Web API.
• state - True to set player shuffle mode to on; otherwise, False for no shuffle.
• device_id (optional) - The id of the device this command is targeting. If not supplied, the user's currently active device is the target. If no device is active (or an "*" is specified), then the SpotifyPlus default device is activated.
• delay (optional) - Time delay (in seconds) to wait AFTER issuing the command to the player. This delay will give the spotify web api time to process the change before another command is issued. Default is 0.50; value range is 0 - 10.

Example YAML

Set shuffle mode to true for the "Bose-ST10-1" player.

service: spotifyplus.player_set_shuffle_mode
data:
  entity_id: media_player.spotifyplus_john_s
  state: true
  device_id: Bose-ST10-1

Player Set Volume Level

Set volume level for the specified Spotify Connect device.

Use this service instead of the media_player.volume_set when you want to set the volume level for a specific Spotify Player device id.

Parameters

All parameters are required unless otherwise noted.

• entity_id - Entity ID of the SpotifyPlus service that will make the request to the Spotify Web API.
• volume_level - The volume level to set, expressed as a percentage value (e.g. 25). Must be a value from 0 (muted) to 100 (max volume) inclusive.
• device_id (optional) - The id of the device this command is targeting. If not supplied, the user's currently active device is the target. If no device is active (or an "*" is specified), then the SpotifyPlus default device is activated.
• delay (optional) - Time delay (in seconds) to wait AFTER issuing the command to the player. This delay will give the spotify web api time to process the change before another command is issued. Default is 0.50; value range is 0 - 10.

Example YAML

Set volume level to 25 for the "Bose-ST10-1" player.

service: spotifyplus.player_set_volume_level
data:
  entity_id: media_player.spotifyplus_john_s
  volume_level: 25
  device_id: Bose-ST10-1

Player Transfer Playback

Transfer playback to a new Spotify Connect Player device and optionally begin playback.

The following log message will be generated if the device_id was supplied, but could not be resolved to a Spotify Connect device. Device value 'X' could not be resolved to an active Spotify Connect device, which denotes subsequent operations for the device will probably fail; please ensure that the specified device is available on the network.

Parameters

All parameters are required unless otherwise noted.

• entity_id - Entity ID of the SpotifyPlus service that will make the request to the Spotify Web API.
• device_id - The id or name of the Spotify Connect Player device on which playback should be started/transferred. If no device is specified, then the SpotifyPlus default device is activated. For Sonos devices, use the device name instead of the device id.
• play (optional) - True (default) to start playback on the new device; otherise, False to keep the current playback state on the existing device.
• delay (optional) - Time delay (in seconds) to wait AFTER issuing the command to the player. This delay will give the spotify web api time to process the change before another command is issued. Default is 0.50; value range is 0 - 10.
• refresh_device_list (optional) - True to refresh the Spotify Connect device list; otherwise, False to use the Spotify Connect device list cache. Default is True.
• force_activate_device (optional) - True to issue a Spotify Connect Disconnect call prior to transfer, which will force the device to reconnect to Spotify Connect; otherwise, False to not disconnect. Default is True.

Example YAML

Transfer playback to the "Bose-ST300" Spotify Connect Player device id.

service: spotifyplus.player_transfer_playback
data:
  entity_id: media_player.spotifyplus_john_s
  device_id: 6f66ef4fbf687bbba393d8c38599aad484b30901
  play: true

Transfer playback to the "Bose-ST300" Spotify Connect Player device name.

service: spotifyplus.player_transfer_playback
data:
  entity_id: media_player.spotifyplus_john_s
  device_id: "Bose-ST300"
  play: true

Transfer playback to the "Sonos-Office" Spotify Connect Player device name.

service: spotifyplus.player_transfer_playback
data:
  entity_id: media_player.spotifyplus_john_s
  device_id: "Sonos-Office"
  play: true

Playlist Change

Change a playlists details (name, description, and public / private state).

Parameters

All parameters are required unless otherwise noted.

• entity_id - Entity ID of the SpotifyPlus service that will make the request to the Spotify Web API.
• playlist_id - The Spotify ID of the playlist (e.g. 5AC9ZXA7nJ7oGWO911FuDG).
• name - The updated name for the playlist (e.g. My Updated Playlist). This name does not need to be unique; a user may have several playlists with the same name.
• description - The playlist description, as displayed in Spotify Clients and in the Web API.
• public - If true, the playlist will be public; if false, it will be private.
• collaborative - If true, the playlist will be collaborative (other users can modify it). To create a collaborative playlist you must also set the public parameter to false.
• image_path (optional) - The fully-qualified path of the image to be uploaded (e.g. www/images/spotify_playlist_default_image.png). The image must be in PNG or JPEG format, and cannot exceed 256KB in Base64 encoded size. Omit this parameter if you do not wish to update the existing playlist image.

Example YAML

service: spotifyplus.playlist_change
data:
  entity_id: media_player.spotifyplus_john_s
  playlist_id: 4ug187aPQTkPhD6Apa8d07
  name: My Updated Playlist
  description: A Playlist updated by the SpotifyPlus integration
  public: false
  collaborative: false
  image_path: www/images/spotify_playlist_default_image.png

Playlist Cover Image Add

Replace the image used to represent a specific playlist.

Parameters

All parameters are required unless otherwise noted.

• entity_id - Entity ID of the SpotifyPlus service that will make the request to the Spotify Web API.
• playlist_id - The Spotify ID of the playlist (e.g. 2hFfHs68giBGT4eMVnqVPt).
• image_path - The fully-qualified path of the image to be uploaded (e.g. www/images/spotify_playlist_default_image.png). The image must be in PNG or JPEG format, and cannot exceed 256KB in Base64 encoded size.

Example YAML

service: spotifyplus.playlist_cover_image_add
data:
  entity_id: media_player.spotifyplus_john_s
  playlist_id: 2hFfHs68giBGT4eMVnqVPt
  image_path: www/images/spotify_playlist_default_image.png

Playlist Create

Create an empty playlist for a Spotify user. The playlist will remain empty until you add tracks.

This service will return service response data.

Parameters

All parameters are required unless otherwise noted.

• entity_id - Entity ID of the SpotifyPlus service that will make the request to the Spotify Web API.
• user_id (optional) - The user's Spotify user ID (e.g. 32k99y2kg5lnn3mxhtmd2bpdkjfu). Omit this parameter to use the Spotify User ID of the player entity_id.
• name - The name for the new playlist (e.g. My New Playlist). This name does not need to be unique; a user may have several playlists with the same name.
• description - The playlist description, as displayed in Spotify Clients and in the Web API.
• public - If true, the playlist will be public; if false, it will be private.
• collaborative - If true, the playlist will be collaborative (other users can modify it). To create a collaborative playlist you must also set the public parameter to false.
• image_path (optional) - The fully-qualified path of the image to be uploaded (e.g. www/images/spotify_playlist_default_image.png). The image must be in PNG or JPEG format, and cannot exceed 256KB in Base64 encoded size. Omit this parameter if you do not wish to add a playlist image.

Example YAML

service: spotifyplus.playlist_create
data:
  entity_id: media_player.spotifyplus_john_s
  name: My New Playlist
  description: A Playlist created by the SpotifyPlus integration
  public: false
  collaborative: false
  image_path: www/images/spotify_playlist_default_image.png

Example Response

A dictionary that contains the following keys:

• user_profile: A (partial) user profile that retrieved the result.
• result: A Playlist object that contains result details.

user_profile:
  country: US
  display_name: John Smith
  email: jsmith@maildomain.com
  id: 3758dfdsfjk435hjk6k79lm0n3c4
  product: premium
  type: user
  uri: spotify:user:3758dfdsfjk435hjk6k79lm0n3c4
result:
  collaborative: false
  description: A Playlist created by the SpotifyPlus integration
  external_urls:
    spotify: https://open.spotify.com/playlist/4ug187aPQTkPhD6Apa8d07
  href: https://api.spotify.com/v1/playlists/4ug187aPQTkPhD6Apa8d07
  id: 4ug187aPQTkPhD6Apa8d07
  images: []
  name: My New Playlist
  public: true
  snapshotId: MjgsZDYxNDczOGYyOTc0OTYyMmNiYTc4M2YwOGQ4ODIzMTkwODMwNTQ4Yw==
  tracks:
    href: https://api.spotify.com/v1/playlists/4ug187aPQTkPhD6Apa8d07/tracks
    limit: 100
    next: null
    offset: 0
    previous: null
    total: 0
    items: []
  type: playlist
  uri: spotify:playlist:4ug187aPQTkPhD6Apa8d07
  followers:
    href: null
    total: 0

Playlist Items Add

Add one or more items to a user's playlist. Items are added in the order they are listed in the uris parameter.

Parameters

All parameters are required unless otherwise noted.

• entity_id - Entity ID of the SpotifyPlus service that will make the request to the Spotify Web API.
• playlist_id - The Spotify ID of the playlist (e.g. 5AC9ZXA7nJ7oGWO911FuDG).
• uris (optional) - A comma-separated list of Spotify URIs to add; can be track or episode URIs (e.g. spotify:track:4iV5W9uYEdYUVa79Axb7Rh). A maximum of 100 items can be specified in one request. If nothing is specified, then the track (or episode) uri currently playing is used.
• position - The position to insert the items, a zero-based index. For example, to insert the items in the first position use a value of zero; to insert the items in the third position use 2. Use -1 to append the items to the end of the playlist.

Example YAML

Add specified track to the beginning of the playlist.

service: spotifyplus.playlist_items_add
data:
  entity_id: media_player.spotifyplus_john_s
  playlist_id: 4yptcTKnXjCu3V92tVVafS
  uris: spotify:track:0NL83oUQmHLErXLOuvhgNX
  position: 0

Insert the specified track in the 3rd position of the playlist.

service: spotifyplus.playlist_items_add
data:
  entity_id: media_player.spotifyplus_john_s
  playlist_id: 4yptcTKnXjCu3V92tVVafS
  uris: spotify:track:0NL83oUQmHLErXLOuvhgNX
  position: 2

Add specified track to the end of the playlist.

service: spotifyplus.playlist_items_add
data:
  entity_id: media_player.spotifyplus_john_s
  playlist_id: 4yptcTKnXjCu3V92tVVafS
  uris: spotify:track:0NL83oUQmHLErXLOuvhgNX

Add currently playing track to the end of the playlist.

service: spotifyplus.playlist_items_add
data:
  entity_id: media_player.spotifyplus_john_s
  playlist_id: 4yptcTKnXjCu3V92tVVafS

Add currently playing track to the beginning of the playlist.

service: spotifyplus.playlist_items_add
data:
  entity_id: media_player.spotifyplus_john_s
  playlist_id: 4yptcTKnXjCu3V92tVVafS
  position: 0

Example Response

A dictionary that contains the following keys:

• user_profile: A (partial) user profile that retrieved the result.
• result: A string that contains a snapshot ID for the updated playlist.

user_profile:
  country: US
  display_name: John Smith
  email: jsmith@maildomain.com
  id: 3758dfdsfjk435hjk6k79lm0n3c4
  product: premium
  type: user
  uri: spotify:user:3758dfdsfjk435hjk6k79lm0n3c4
result: AAAABskyqYpbcIHu3w0M6VD69zTBI

Playlist Items Clear

Removes (clears) all items from a user's playlist.

Parameters

All parameters are required unless otherwise noted.

• entity_id - Entity ID of the SpotifyPlus service that will make the request to the Spotify Web API.
• playlist_id - The Spotify ID of the playlist (e.g. 5AC9ZXA7nJ7oGWO911FuDG).

Example YAML

service: spotifyplus.playlist_items_clear
data:
  entity_id: media_player.spotifyplus_john_s
  playlist_id: 2hFfHs68giBGT4eMVnqVPt

Example Response

A dictionary that contains the following keys:

• user_profile: A (partial) user profile that retrieved the result.
• result: A string that contains a snapshot ID for the updated playlist.

user_profile:
  country: US
  display_name: John Smith
  email: jsmith@maildomain.com
  id: 3758dfdsfjk435hjk6k79lm0n3c4
  product: premium
  type: user
  uri: spotify:user:3758dfdsfjk435hjk6k79lm0n3c4
result: AAAABskyqYpbcIHu3w0M6VD69zTBI

Playlist Items Remove

Remove one or more items from a user's playlist.

Parameters

All parameters are required unless otherwise noted.

• entity_id - Entity ID of the SpotifyPlus service that will make the request to the Spotify Web API.
• playlist_id - The Spotify ID of the playlist (e.g. 5AC9ZXA7nJ7oGWO911FuDG).
• uris (optional) - A comma-separated list of Spotify URIs to remove; can be track or episode URIs (e.g. spotify:track:0NL83oUQmHLErXLOuvhgNX). A maximum of 100 items can be specified in one request. If nothing is specified, then the track (or episode) uri currently playing is used.
• snapshot_id (optional) - The playlist's snapshot ID against which you want to make the changes (e.g. MzgsMWVkNDY3MTQ5YjVjYWE0MzAyNjkyZWMyOThjNjE3YWMwOTY0ZmJjYg==). The API will validate that the specified items exist and make the changes, even if more recent changes have been made to the playlist. If parameter is omitted, the current playlist is updated.

Example YAML

Remove specified tracks from the playlist.

service: spotifyplus.playlist_items_remove
data:
  entity_id: media_player.spotifyplus_john_s
  playlist_id: 4yptcTKnXjCu3V92tVVafS
  uris: spotify:track:0NL83oUQmHLErXLOuvhgNX,spotify:track:1HynOdAoMmGmkZOzafy492

Remove currently playing track from the playlist.

service: spotifyplus.playlist_items_remove
data:
  entity_id: media_player.spotifyplus_john_s
  playlist_id: 4yptcTKnXjCu3V92tVVafS

Example Response

A dictionary that contains the following keys:

• user_profile: A (partial) user profile that retrieved the result.
• result: A string that contains a snapshot ID for the updated playlist.

user_profile:
  country: US
  display_name: John Smith
  email: jsmith@maildomain.com
  id: 3758dfdsfjk435hjk6k79lm0n3c4
  product: premium
  type: user
  uri: spotify:user:3758dfdsfjk435hjk6k79lm0n3c4
result: AAAABskyqYpbcIHu3w0M6VD69zTBI

Playlist Items Reorder

Reorder items in a user's playlist.

Parameters

All parameters are required unless otherwise noted.

• entity_id - Entity ID of the SpotifyPlus service that will make the request to the Spotify Web API.
• playlist_id - The Spotify ID of the playlist (e.g. 5AC9ZXA7nJ7oGWO911FuDG).
• range_start - The position of the first item to be reordered. This is a one-offset integer (NOT zero-offset).
• insert_before - The position where the items should be inserted. To reorder the items to the end of the playlist, simply set insertBefore to the position after the last item. This is a one-offset integer (NOT zero-offset).
• range_length - The amount of items to be reordered; defaults to 1 if not set. The range of items to be reordered begins from the rangeStart position, and includes the rangeLength subsequent items.
• snapshot_id (optional) - The playlist's snapshot ID against which you want to make the changes (e.g. MzgsMWVkNDY3MTQ5YjVjYWE0MzAyNjkyZWMyOThjNjE3YWMwOTY0ZmJjYg==). The API will validate that the specified items exist and make the changes, even if more recent changes have been made to the playlist. If parameter is omitted, the current playlist is updated.

Example YAML

Reorder items in current playlist - move track #5 to position #1 in the list.

service: spotifyplus.playlist_items_reorder
data:
  entity_id: media_player.spotifyplus_john_s
  playlist_id: 4yptcTKnXjCu3V92tVVafS
  range_start: 5
  insert_before: 1
  range_length: 1

Reorder items in current playlist - move tracks #5,6,7 to position #1 in the list.

service: spotifyplus.playlist_items_reorder
data:
  entity_id: media_player.spotifyplus_john_s
  playlist_id: 4yptcTKnXjCu3V92tVVafS
  range_start: 5
  insert_before: 1
  range_length: 3

Reorder items in current playlist - move track #7 to position #6 in the list.

service: spotifyplus.playlist_items_reorder
data:
  entity_id: media_player.spotifyplus_john_s
  playlist_id: 4yptcTKnXjCu3V92tVVafS
  range_start: 7
  insert_before: 6
  range_length: 1

Reorder items in current playlist - move track #5 to position #10 in the list.

service: spotifyplus.playlist_items_reorder
data:
  entity_id: media_player.spotifyplus_john_s
  playlist_id: 4yptcTKnXjCu3V92tVVafS
  range_start: 5
  insert_before: 10
  range_length: 1

Reorder items in a specific playlist snapshot - move track #5 to position #10 in the list.

service: spotifyplus.playlist_items_reorder
data:
  entity_id: media_player.spotifyplus_john_s
  playlist_id: 4yptcTKnXjCu3V92tVVafS
  range_start: 5
  insert_before: 10
  range_length: 1
  snapshot_id: "AAAA0dJUdZX9JCH2G/ztzZA8MWCQ6fUh"

Example Response

A dictionary that contains the following keys:

• user_profile: A (partial) user profile that retrieved the result.
• result: A string that contains a snapshot ID for the updated playlist.

user_profile:
  country: US
  display_name: John Smith
  email: jsmith@maildomain.com
  id: 3758dfdsfjk435hjk6k79lm0n3c4
  product: premium
  type: user
  uri: spotify:user:3758dfdsfjk435hjk6k79lm0n3c4
result: AAAA0dJUdZX9JCH2G/ztzZA8MWCQ6fUh

Playlist Items Replace

Replace one or more items in a user's playlist. Replacing items in a playlist will overwrite its existing items. This service can also be used to clear a playlist.

Parameters

All parameters are required unless otherwise noted.

• entity_id - Entity ID of the SpotifyPlus service that will make the request to the Spotify Web API.
• playlist_id - The Spotify ID of the playlist (e.g. 5AC9ZXA7nJ7oGWO911FuDG).
• uris (optional) - A comma-separated list of Spotify URIs to replace; can be track or episode URIs (e.g. spotify:track:4iV5W9uYEdYUVa79Axb7Rh, spotify:episode:26c0zVyOv1lzfYpBXdh1zC). A maximum of 100 items can be specified in one request. Omit this parameter to clear all items from the specified playlist.

Example YAML

Replace all items in the playlist with the following items.

service: spotifyplus.playlist_items_replace
data:
  entity_id: media_player.spotifyplus_john_s
  playlist_id: 4yptcTKnXjCu3V92tVVafS
  uris: spotify:track:0NL83oUQmHLErXLOuvhgNX,spotify:track:1HynOdAoMmGmkZOzafy492

Clear all items from the playlist.

service: spotifyplus.playlist_items_replace
data:
  entity_id: media_player.spotifyplus_john_s
  playlist_id: 4yptcTKnXjCu3V92tVVafS

Example Response

A dictionary that contains the following keys:

• user_profile: A (partial) user profile that retrieved the result.
• result: A string that contains a snapshot ID for the updated playlist.

user_profile:
  country: US
  display_name: John Smith
  email: jsmith@maildomain.com
  id: 3758dfdsfjk435hjk6k79lm0n3c4
  product: premium
  type: user
  uri: spotify:user:3758dfdsfjk435hjk6k79lm0n3c4
result: AAAABskyqYpbcIHu3w0M6VD69zTBI

Remove Album Favorites

Remove one or more albums from the current user's 'Your Library'.

Parameters

All parameters are required unless otherwise noted.

• entity_id - Entity ID of the SpotifyPlus service that will make the request to the Spotify Web API.
• ids (optional) - A comma-separated list of Spotify album id's (e.g. 6vc9OTcyd3hyzabCmsdnwE,382ObEPsp2rxGrnsizN5TX). A maximum of 50 id's may be specified. If omitted, the currently playing track album uri id value is used.

Example YAML

Remove specified albums to current user favorites.

service: spotifyplus.remove_album_favorites
data:
  entity_id: media_player.spotifyplus_john_s
  ids: 6vc9OTcyd3hyzabCmsdnwE,382ObEPsp2rxGrnsizN5TX

Remove currently playing track album to current user favorites.

service: spotifyplus.remove_album_favorites
data:
  entity_id: media_player.spotifyplus_john_s

Remove Audiobook Favorites

Remove one or more audiobooks from the current user's 'Your Library'.

Parameters

All parameters are required unless otherwise noted.

• entity_id - Entity ID of the SpotifyPlus service that will make the request to the Spotify Web API.
• ids (optional) - A comma-separated list of Spotify audiobook id's (e.g. 3PFyizE2tGCSRLusl2Qizf,7iHfbu1YPACw6oZPAFJtqe). A maximum of 50 id's may be specified. If omitted, the currently playing audiobook uri id value is used.

Example YAML

Remove specified audiobooks to current user favorites.

service: spotifyplus.remove_audiobook_favorites
data:
  entity_id: media_player.spotifyplus_john_s
  ids: 3PFyizE2tGCSRLusl2Qizf,7iHfbu1YPACw6oZPAFJtqe

Remove currently playing track audiobook to current user favorites.

service: spotifyplus.remove_audiobook_favorites
data:
  entity_id: media_player.spotifyplus_john_s

Remove Episode Favorites

Remove one or more episodes from the current user's 'Your Library'.

Parameters

All parameters are required unless otherwise noted.

• entity_id - Entity ID of the SpotifyPlus service that will make the request to the Spotify Web API.
• ids (optional) - A comma-separated list of Spotify episode id's (e.g. 3F97boSWlXi8OzuhWClZHQ,1hPX5WJY6ja6yopgVPBqm4). A maximum of 50 id's may be specified. If omitted, the currently playing episode uri id value is used.

Example YAML

Remove specified episodes to current user favorites.

service: spotifyplus.remove_episode_favorites
data:
  entity_id: media_player.spotifyplus_john_s
  ids: 3F97boSWlXi8OzuhWClZHQ,1hPX5WJY6ja6yopgVPBqm4

Remove currently playing track episode to current user favorites.

service: spotifyplus.remove_episode_favorites
data:
  entity_id: media_player.spotifyplus_john_s

Remove Show Favorites

Remove one or more shows from the current user's 'Your Library'.

Parameters

All parameters are required unless otherwise noted.

• entity_id - Entity ID of the SpotifyPlus service that will make the request to the Spotify Web API.
• ids (optional) - A comma-separated list of Spotify show id's (e.g. 6kAsbP8pxwaU2kPibKTuHE,4rOoJ6Egrf8K2IrywzwOMk). A maximum of 50 id's may be specified. If omitted, the currently playing show uri id value is used.

Example YAML

Remove specified shows to current user favorites.

service: spotifyplus.remove_show_favorites
data:
  entity_id: media_player.spotifyplus_john_s
  ids: 6kAsbP8pxwaU2kPibKTuHE,4rOoJ6Egrf8K2IrywzwOMk

Remove currently playing track show to current user favorites.

service: spotifyplus.remove_show_favorites
data:
  entity_id: media_player.spotifyplus_john_s

Remove Track Favorites

Remove one or more tracks from the current user's 'Your Library'.

Parameters

All parameters are required unless otherwise noted.

• entity_id - Entity ID of the SpotifyPlus service that will make the request to the Spotify Web API.
• ids (optional) - A comma-separated list of Spotify track id's (e.g. 1kWUud3vY5ij5r62zxpTRy,4eoYKv2kDwJS7gRGh5q6SK). A maximum of 50 id's may be specified. If omitted, the currently playing context uri id value is used.

Example YAML

Remove specified tracks from current user favorites.

service: spotifyplus.remove_track_favorites
data:
  entity_id: media_player.spotifyplus_john_s
  ids: 0NL83oUQmHLErXLOuvhgNX,1HynOdAoMmGmkZOzafy492

Remove currently playing track from current user favorites.

service: spotifyplus.remove_track_favorites
data:
  entity_id: media_player.spotifyplus_john_s

Replace Playlist Items

Replace one or more items in a user's playlist. Replacing items in a playlist will overwrite its existing items.

This service can also be used to clear a playlist.

This service will return service response data.

Parameters

All parameters are required unless otherwise noted.

• entity_id - Entity ID of the SpotifyPlus service that will make the request to the Spotify Web API.
• playlist_id - The Spotify ID of the playlist (e.g. 5AC9ZXA7nJ7oGWO911FuDG).
• uris - A comma-separated list of Spotify URIs to replace; can be track or episode URIs (e.g. spotify:track:4iV5W9uYEdYUVa79Axb7Rh, spotify:episode:26c0zVyOv1lzfYpBXdh1zC). A maximum of 100 items can be specified in one request.

Example YAML

service: spotifyplus.replace_playlist_items
data:
  entity_id: media_player.spotifyplus_john_s
  playlist_id: 5AC9ZXA7nJ7oGWO911FuDG
  uris: spotify:track:4iV5W9uYEdYUVa79Axb7Rh, spotify:episode:26c0zVyOv1lzfYpBXdh1zC

Example Response

A dictionary that contains the following keys:

• user_profile: A (partial) user profile that retrieved the result.
• result: An string object that contains a snapshot ID for the updated playlist.

user_profile:
  country: US
  display_name: John Smith
  email: jsmith@maildomain.com
  id: 3758dfdsfjk435hjk6k79lm0n3c4
  product: premium
  type: user
  uri: spotify:user:3758dfdsfjk435hjk6k79lm0n3c4
result:
  ... <data truncated for brevity - same results as Spotify Web API returns>

Save Album Favorites

Save one or more albums to the current user's 'Your Library'.

Parameters

All parameters are required unless otherwise noted.

• entity_id - Entity ID of the SpotifyPlus service that will make the request to the Spotify Web API.
• ids (optional) - A comma-separated list of Spotify album id's (e.g. 6vc9OTcyd3hyzabCmsdnwE,382ObEPsp2rxGrnsizN5TX). A maximum of 50 id's may be specified. If omitted, the currently playing track album uri id value is used.

Example YAML

Save specified albums to current user favorites.

service: spotifyplus.save_album_favorites
data:
  entity_id: media_player.spotifyplus_john_s
  ids: 6vc9OTcyd3hyzabCmsdnwE,382ObEPsp2rxGrnsizN5TX

Save currently playing track album to current user favorites.

service: spotifyplus.save_album_favorites
data:
  entity_id: media_player.spotifyplus_john_s

Save Audiobook Favorites

Save one or more audiobooks to the current user's 'Your Library'.

Parameters

All parameters are required unless otherwise noted.

• entity_id - Entity ID of the SpotifyPlus service that will make the request to the Spotify Web API.
• ids (optional) - A comma-separated list of Spotify audiobook id's (e.g. 3PFyizE2tGCSRLusl2Qizf,7iHfbu1YPACw6oZPAFJtqe). A maximum of 50 id's may be specified. If omitted, the currently playing audiobook uri id value is used.

Example YAML

Save specified audiobooks to current user favorites.

service: spotifyplus.save_audiobook_favorites
data:
  entity_id: media_player.spotifyplus_john_s
  ids: 3PFyizE2tGCSRLusl2Qizf,7iHfbu1YPACw6oZPAFJtqe

Save currently playing audiobook to current user favorites.

service: spotifyplus.save_audiobook_favorites
data:
  entity_id: media_player.spotifyplus_john_s

Save Episode Favorites

Save one or more episodes to the current user's 'Your Library'.

Parameters

All parameters are required unless otherwise noted.

• entity_id - Entity ID of the SpotifyPlus service that will make the request to the Spotify Web API.
• ids (optional) - A comma-separated list of Spotify episode id's (e.g. 3F97boSWlXi8OzuhWClZHQ,1hPX5WJY6ja6yopgVPBqm4). A maximum of 50 id's may be specified. If omitted, the currently playing episode uri id value is used.

Example YAML

Save specified episodes to current user favorites.

service: spotifyplus.save_episode_favorites
data:
  entity_id: media_player.spotifyplus_john_s
  ids: 3F97boSWlXi8OzuhWClZHQ,1hPX5WJY6ja6yopgVPBqm4

Save currently playing episode to current user favorites.

service: spotifyplus.save_episode_favorites
data:
  entity_id: media_player.spotifyplus_john_s

Save Show Favorites

Save one or more shows to the current user's 'Your Library'.

Parameters

All parameters are required unless otherwise noted.

• entity_id - Entity ID of the SpotifyPlus service that will make the request to the Spotify Web API.
• ids (optional) - A comma-separated list of Spotify show id's (e.g. 6kAsbP8pxwaU2kPibKTuHE,4rOoJ6Egrf8K2IrywzwOMk). A maximum of 50 id's may be specified. If omitted, the currently playing show uri id value is used.

Example YAML

Save specified shows to current user favorites.

service: spotifyplus.save_show_favorites
data:
  entity_id: media_player.spotifyplus_john_s
  ids: 6kAsbP8pxwaU2kPibKTuHE,4rOoJ6Egrf8K2IrywzwOMk

Save currently playing show to current user favorites.

service: spotifyplus.save_show_favorites
data:
  entity_id: media_player.spotifyplus_john_s

Save Track Favorites

Save one or more tracks to the current user's 'Your Library'.

Parameters

All parameters are required unless otherwise noted.

• entity_id - Entity ID of the SpotifyPlus service that will make the request to the Spotify Web API.
• ids (optional) - A comma-separated list of Spotify track id's (e.g. 1kWUud3vY5ij5r62zxpTRy,4eoYKv2kDwJS7gRGh5q6SK). A maximum of 50 id's may be specified. If omitted, the currently playing context uri id value is used.

Example YAML

Save specified tracks to current user favorites.

service: spotifyplus.save_track_favorites
data:
  entity_id: media_player.spotifyplus_john_s
  ids: 0NL83oUQmHLErXLOuvhgNX,1HynOdAoMmGmkZOzafy492

Save currently playing track to current user favorites.

service: spotifyplus.save_track_favorites
data:
  entity_id: media_player.spotifyplus_john_s

Search Albums

Get Spotify catalog information about Albums that match a keyword string.

This service will return service response data.

Parameters

All parameters are required unless otherwise noted.

• entity_id - Entity ID of the SpotifyPlus service that will make the request to the Spotify Web API.
• criteria - The criteria to search for (e.g. "Daily Mix"). Example: "Daily Mix"
• limit (optional) - The maximum number of items to return in a page of items. Default is 20, Range is 1 to 50.
• offset (optional) - The page index offset of the first item to return. Use with limit to get the next set of items. Default is 0 (the first item).
• market (optional) - An ISO 3166-1 alpha-2 country code. If a country code is specified, only content that is available in that market will be returned. The country associated with the user account will take priority over this parameter. example: US
• include_external (optional) - If 'audio' is specified it signals that the client can play externally hosted audio content, and marks the content as playable in the response. By default externally hosted audio content is marked as unplayable in the response. Allowed values are 'audio'. Example: "audio"
• limit_total (optional) - The maximum number of items to return for the request. If specified, this parameter overrides the limit and offset parameter values and paging is automatically used to retrieve all available items up to the specified limit total.

Example YAML

service: spotifyplus.search_albums
data:
  entity_id: media_player.spotifyplus_john_s
  criteria: Welcome to the New
  include_external: audio
  limit_total: 2

Example Response

A dictionary that contains the following keys:

• user_profile: A (partial) user profile that retrieved the result.
• result: A AlbumPageSimplified object of matching results.

user_profile:
  country: US
  display_name: John Smith
  email: jsmith@maildomain.com
  id: 3758dfdsfjk435hjk6k79lm0n3c4
  product: premium
  type: user
  uri: spotify:user:3758dfdsfjk435hjk6k79lm0n3c4
result:
  ... <data truncated for brevity - same results as Spotify Web API returns>

Search Artists

Get Spotify catalog information about Artists that match a keyword string.

This service will return service response data.

Parameters

All parameters are required unless otherwise noted.

• entity_id - Entity ID of the SpotifyPlus service that will make the request to the Spotify Web API.
• criteria - The criteria to search for (e.g. "Daily Mix"). Example: "Daily Mix"
• limit (optional) - The maximum number of items to return in a page of items. Default is 20, Range is 1 to 50.
• offset (optional) - The page index offset of the first item to return. Use with limit to get the next set of items. Default is 0 (the first item).
• market (optional) - An ISO 3166-1 alpha-2 country code. If a country code is specified, only content that is available in that market will be returned. The country associated with the user account will take priority over this parameter. example: US
• include_external (optional) - If 'audio' is specified it signals that the client can play externally hosted audio content, and marks the content as playable in the response. By default externally hosted audio content is marked as unplayable in the response. Allowed values are 'audio'. Example: "audio"
• limit_total (optional) - The maximum number of items to return for the request. If specified, this parameter overrides the limit and offset parameter values and paging is automatically used to retrieve all available items up to the specified limit total.

Example YAML

service: spotifyplus.search_artists
data:
  entity_id: media_player.spotifyplus_john_s
  criteria: MercyMe
  include_external: audio
  limit_total: 2

Example Response

A dictionary that contains the following keys:

• user_profile: A (partial) user profile that retrieved the result.
• result: A ArtistPage object of matching results.

user_profile:
  country: US
  display_name: John Smith
  email: jsmith@maildomain.com
  id: 3758dfdsfjk435hjk6k79lm0n3c4
  product: premium
  type: user
  uri: spotify:user:3758dfdsfjk435hjk6k79lm0n3c4
result:
  ... <data truncated for brevity - same results as Spotify Web API returns>

Search Audiobooks

Get Spotify catalog information about Audiobooks that match a keyword string.

This service will return service response data.

Parameters

All parameters are required unless otherwise noted.

• entity_id - Entity ID of the SpotifyPlus service that will make the request to the Spotify Web API.
• criteria - The criteria to search for (e.g. "Daily Mix"). Example: "Daily Mix"
• limit (optional) - The maximum number of items to return in a page of items. Default is 20, Range is 1 to 50.
• offset (optional) - The page index offset of the first item to return. Use with limit to get the next set of items. Default is 0 (the first item).
• market (optional) - An ISO 3166-1 alpha-2 country code. If a country code is specified, only content that is available in that market will be returned. The country associated with the user account will take priority over this parameter. example: US
• include_external (optional) - If 'audio' is specified it signals that the client can play externally hosted audio content, and marks the content as playable in the response. By default externally hosted audio content is marked as unplayable in the response. Allowed values are 'audio'. Example: "audio"
• limit_total (optional) - The maximum number of items to return for the request. If specified, this parameter overrides the limit and offset parameter values and paging is automatically used to retrieve all available items up to the specified limit total.

Example YAML

service: spotifyplus.search_audiobooks
data:
  entity_id: media_player.spotifyplus_john_s
  criteria: The Elfstones of Shannara
  include_external: audio
  limit_total: 2

Example Response

A dictionary that contains the following keys:

• user_profile: A (partial) user profile that retrieved the result.
• result: A AudiobookPageSimplified object of matching results.

user_profile:
  country: US
  display_name: John Smith
  email: jsmith@maildomain.com
  id: 3758dfdsfjk435hjk6k79lm0n3c4
  product: premium
  type: user
  uri: spotify:user:3758dfdsfjk435hjk6k79lm0n3c4
result:
  ... <data truncated for brevity - same results as Spotify Web API returns>

Search Episodes

Get Spotify catalog information about Episodes that match a keyword string.

This service will return service response data.

Parameters

All parameters are required unless otherwise noted.

• entity_id - Entity ID of the SpotifyPlus service that will make the request to the Spotify Web API.
• criteria - The criteria to search for (e.g. "Daily Mix"). Example: "Daily Mix"
• limit (optional) - The maximum number of items to return in a page of items. Default is 20, Range is 1 to 50.
• offset (optional) - The page index offset of the first item to return. Use with limit to get the next set of items. Default is 0 (the first item).
• market (optional) - An ISO 3166-1 alpha-2 country code. If a country code is specified, only content that is available in that market will be returned. The country associated with the user account will take priority over this parameter. example: US
• include_external (optional) - If 'audio' is specified it signals that the client can play externally hosted audio content, and marks the content as playable in the response. By default externally hosted audio content is marked as unplayable in the response. Allowed values are 'audio'. Example: "audio"
• limit_total (optional) - The maximum number of items to return for the request. If specified, this parameter overrides the limit and offset parameter values and paging is automatically used to retrieve all available items up to the specified limit total.

Example YAML

service: spotifyplus.search_episodes
data:
  entity_id: media_player.spotifyplus_john_s
  criteria: Armchair Anonymous
  include_external: audio
  limit_total: 2

Example Response

A dictionary that contains the following keys:

• user_profile: A (partial) user profile that retrieved the result.
• result: A EpisodePageSimplified object of matching results.

user_profile:
  country: US
  display_name: John Smith
  email: jsmith@maildomain.com
  id: 3758dfdsfjk435hjk6k79lm0n3c4
  product: premium
  type: user
  uri: spotify:user:3758dfdsfjk435hjk6k79lm0n3c4
result:
  ... <data truncated for brevity - same results as Spotify Web API returns>

Search Playlists

Get Spotify catalog information about Playlists that match a keyword string.

This service will return service response data.

Parameters

All parameters are required unless otherwise noted.

• entity_id - Entity ID of the SpotifyPlus service that will make the request to the Spotify Web API.
• criteria - The criteria to search for (e.g. "Daily Mix"). Example: "Daily Mix"
• limit (optional) - The maximum number of items to return in a page of items. Default is 20, Range is 1 to 50.
• offset (optional) - The page index offset of the first item to return. Use with limit to get the next set of items. Default is 0 (the first item).
• market (optional) - An ISO 3166-1 alpha-2 country code. If a country code is specified, only content that is available in that market will be returned. The country associated with the user account will take priority over this parameter. example: US
• include_external (optional) - If 'audio' is specified it signals that the client can play externally hosted audio content, and marks the content as playable in the response. By default externally hosted audio content is marked as unplayable in the response. Allowed values are 'audio'. Example: "audio"
• limit_total (optional) - The maximum number of items to return for the request. If specified, this parameter overrides the limit and offset parameter values and paging is automatically used to retrieve all available items up to the specified limit total.

Example YAML

service: spotifyplus.search_playlists
data:
  entity_id: media_player.spotifyplus_john_s
  criteria: Daily Mix
  include_external: audio
  limit_total: 2

Example Response

A dictionary that contains the following keys:

• user_profile: A (partial) user profile that retrieved the result.
• result: A PlaylistPageSimplified object of matching results.

user_profile:
  country: US
  display_name: John Smith
  email: jsmith@maildomain.com
  id: 3758dfdsfjk435hjk6k79lm0n3c4
  product: premium
  type: user
  uri: spotify:user:3758dfdsfjk435hjk6k79lm0n3c4
result:
  ... <data truncated for brevity - same results as Spotify Web API returns>

Search Shows

Get Spotify catalog information about Shows that match a keyword string.

This service will return service response data.

Parameters

All parameters are required unless otherwise noted.

• entity_id - Entity ID of the SpotifyPlus service that will make the request to the Spotify Web API.
• criteria - The criteria to search for (e.g. "Daily Mix"). Example: "Daily Mix"
• limit (optional) - The maximum number of items to return in a page of items. Default is 20, Range is 1 to 50.
• offset (optional) - The page index offset of the first item to return. Use with limit to get the next set of items. Default is 0 (the first item).
• market (optional) - An ISO 3166-1 alpha-2 country code. If a country code is specified, only content that is available in that market will be returned. The country associated with the user account will take priority over this parameter. example: US
• include_external (optional) - If 'audio' is specified it signals that the client can play externally hosted audio content, and marks the content as playable in the response. By default externally hosted audio content is marked as unplayable in the response. Allowed values are 'audio'. Example: "audio"
• limit_total (optional) - The maximum number of items to return for the request. If specified, this parameter overrides the limit and offset parameter values and paging is automatically used to retrieve all available items up to the specified limit total.

Example YAML

service: spotifyplus.search_shows
data:
  entity_id: media_player.spotifyplus_john_s
  criteria: Dax Shepard
  include_external: audio
  limit_total: 2

Example Response

A dictionary that contains the following keys:

• user_profile: A (partial) user profile that retrieved the result.
• result: A ShowPageSimplified object of matching results.

user_profile:
  country: US
  display_name: John Smith
  email: jsmith@maildomain.com
  id: 3758dfdsfjk435hjk6k79lm0n3c4
  product: premium
  type: user
  uri: spotify:user:3758dfdsfjk435hjk6k79lm0n3c4
result:
  ... <data truncated for brevity - same results as Spotify Web API returns>

Search Tracks

Get Spotify catalog information about Tracks that match a keyword string.

This service will return service response data.

Parameters

All parameters are required unless otherwise noted.

• entity_id - Entity ID of the SpotifyPlus service that will make the request to the Spotify Web API.
• criteria - The criteria to search for (e.g. "Daily Mix"). Example: "Daily Mix"
• limit (optional) - The maximum number of items to return in a page of items. Default is 20, Range is 1 to 50.
• offset (optional) - The page index offset of the first item to return. Use with limit to get the next set of items. Default is 0 (the first item).
• market (optional) - An ISO 3166-1 alpha-2 country code. If a country code is specified, only content that is available in that market will be returned. The country associated with the user account will take priority over this parameter. example: US
• include_external (optional) - If 'audio' is specified it signals that the client can play externally hosted audio content, and marks the content as playable in the response. By default externally hosted audio content is marked as unplayable in the response. Allowed values are 'audio'. Example: "audio"
• limit_total (optional) - The maximum number of items to return for the request. If specified, this parameter overrides the limit and offset parameter values and paging is automatically used to retrieve all available items up to the specified limit total.

Example YAML

service: spotifyplus.search_tracks
data:
  entity_id: media_player.spotifyplus_john_s
  criteria: Dear Younger Me
  include_external: audio
  limit_total: 2

Example Response

A dictionary that contains the following keys:

• user_profile: A (partial) user profile that retrieved the result.
• result: A TrackPage object of matching results.

user_profile:
  country: US
  display_name: John Smith
  email: jsmith@maildomain.com
  id: 3758dfdsfjk435hjk6k79lm0n3c4
  product: premium
  type: user
  uri: spotify:user:3758dfdsfjk435hjk6k79lm0n3c4
result:
  ... <data truncated for brevity - same results as Spotify Web API returns>

Unfollow Artists

Remove the current user as a follower of one or more artists.

Parameters

All parameters are required unless otherwise noted.

• entity_id - Entity ID of the SpotifyPlus service that will make the request to the Spotify Web API.
• ids (optional) - A comma-separated list of Spotify artist id's (e.g. 2CIMQHirSU0MQqyYHq0eOx,1IQ2e1buppatiN1bxUVkrk). A maximum of 50 id's may be specified. If omitted, the currently playing track artist uri id value is used.

Example YAML

Unfollow the specified artists.

service: spotifyplus.unfollow_artists
data:
  entity_id: media_player.spotifyplus_john_s
  ids: 2CIMQHirSU0MQqyYHq0eOx,1IQ2e1buppatiN1bxUVkrk

Unfollow the currently playing track artist.

service: spotifyplus.unfollow_artists
data:
  entity_id: media_player.spotifyplus_john_s

Unfollow Playlist

Remove the current user as a follower of a playlist.

Parameters

All parameters are required unless otherwise noted.

• entity_id - Entity ID of the SpotifyPlus service that will make the request to the Spotify Web API.
• playlist_id (optional) - The Spotify ID of the playlist (e.g. 37i9dQZF1E39vTG3GurFPW). If omitted, the currently playing playlist uri id value is used.

Example YAML

Unfollow the specified playlist.

service: spotifyplus.unfollow_playlist
data:
  entity_id: media_player.spotifyplus_john_s
  playlist_id: 37i9dQZF1E39vTG3GurFPW

Unfollow Users

Remove the current user as a follower of one or more users.

Parameters

All parameters are required unless otherwise noted.

• entity_id - Entity ID of the SpotifyPlus service that will make the request to the Spotify Web API.
• ids - A comma-separated list of Spotify user IDs (e.g. smedjan,3758dfdsfjk435hjk6k79lm0n3c4). A maximum of 50 IDs can be sent in one request.

Example YAML

Unfollow the specified users.

service: spotifyplus.unfollow_users
data:
  entity_id: media_player.spotifyplus_john_s
  ids: smedjan,3758dfdsfjk435hjk6k79lm0n3c4

ZeroConf Device Connect

Calls the addUser Spotify Zeroconf API endpoint to issue a call to SpConnectionLoginBlob. If successful, the associated device id is added to the Spotify Connect active device list for the specified user account. This will also issue a resetUsers call prior to the addUser call.

Use the ZeroConf Discover Devices service to retrieve the various parameters for this method.

This service will return service response data.

The login (on the device) is performed asynchronously, so the return result only indicates whether the library is able to perform the login attempt. You should issue a call to the Spotify Web API Get Available Devices endpoint to check the current device list to ensure that the device id was successfully added or not.

Note that if you don't have a password setup for your Spotify account (e.g. you utilize the "Continue with Google" or other non-password methods for login), then you will need to define a "device password" in order to use the ZeroConf Connect service; use the Spotify Set Device Password page to define a device password. You will then use your Spotify username and the device password to Connect to the device.

The loginid value can be obtained by calling the ZeroConf Device Get Information service. The Spotify loginid value (aka canonical user id) is returned in the user_profile \ id value. It is also the suffix of the Spotify User uri (e.g. spotify:user:xxxxxxxxxxxx) value.

Use the verifyDeviceListEntry argument to check if the device is currently listed in the Spotify Connect device list. If True, a GetInformation call is issued to get the device id, and a GetPlayerDevice call is made to check if the device id is in the Spotify Connect device list. If the device id is found in the Spotify Connect device list then the Connect command is not issued; if the device id is NOT found in the Spotify Connect device list then the Connect command is issued

Parameters

All parameters are required unless otherwise noted.

• entity_id - Entity ID of the SpotifyPlus device that will make the request to the ZeroConf service.
• host_ipv4_address - IPV4 address at which the Spotify Connect Zeroconf API can be reached on the Spotify Connect device (e.g. '192.168.1.81').
• host_ip_port - Port number at which the Spotify Connect Zeroconf API can be reached on the Spotify Connect device (e.g. 8200).
• cpath - Spotify Connect Zeroconf API CPath property value (e.g. '/zc').
• version - (optional) Spotify Connect Zeroconf API version number that the device supports (e.g. '1.0'). Default is '1.0'.
• use_ssl - (optional) Spotify Connect Zeroconf API version number that the device supports (e.g. False). Default is False.
• username - Spotify user name to login with; this can be a standard username (e.g. 'yourusername@mail.com') or a canonical userid (e.g. '31l77y75hfnhk79f7gk6jkk878mg'). This MUST match the account name (or one of them) that was used to configure Spotify Connect on the manufacturer device.
• password - Spotify user password to login with.
• loginid - Spotify Connect login id to login with (e.g. '31l77fd87g8h9j00k89f07jf87ge'). This is also known as the canonical user id value. This MUST be the value that relates to the username argument.
• pre_disconnect - (optional) True if a Disconnect should be made prior to the Connect call. This will ensure that the active user is logged out, which must be done if switching user accounts; otherwise, False to not issue a Disconnect call. Default is False.
• verify_device_list_entry - (optional) True to ensure that the device id is present in the Spotify Connect device list before issuing a call to Connect; Connect will not be called if the device id is already in the list; otherwise, False to always call Connect to add the device. Default is False.
• delay - (optional) Time delay (in seconds) to wait AFTER issuing a command to the device. This delay will give the spotify zeroconf api time to process the change before another command is issued. Default is 0.50; value range is 0 - 10.

Example YAML

service: spotifyplus.zeroconf_device_connect
data:
  entity_id: media_player.spotifyplus_john_s
  host_ipv4_address: 192.168.1.81
  host_ip_port: 8200
  cpath: /zc
  version: 1
  use_ssl: false
  username: yourusername@mail.com
  password: yourpassword
  loginid: yourspotifyloginid
  pre_disconnect: true
  verify_device_list_entry: true

Example Response

A dictionary that contains the following keys:

• user_profile: A (partial) user profile that retrieved the result.
• result: A ZeroconfResponse object that contains the response.

user_profile:
  country: US
  display_name: John Smith
  email: jsmith@maildomain.com
  id: 3758dfdsfjk435hjk6k79lm0n3c4
  product: premium
  type: user
  uri: spotify:user:3758dfdsfjk435hjk6k79lm0n3c4
result:
  SpotifyError: 0
  Status: 101
  StatusString: OK
  ResponseSource: null

ZeroConf Device Disconnect

Calls the resetUsers Spotify Zeroconf API endpoint to issue a call to SpConnectionLogout. The currently logged in user (if any) will be logged out of Spotify Connect, and the device id removed from the active Spotify Connect device list.

Use the ZeroConf Discover Devices service to retrieve the various parameters for this method.

This service will return service response data.

Parameters

All parameters are required unless otherwise noted.

• entity_id - Entity ID of the SpotifyPlus device that will make the request to the ZeroConf service.
• host_ipv4_address - IPV4 address at which the Spotify Connect Zeroconf API can be reached on the Spotify Connect device (e.g. '192.168.1.81').
• host_ip_port - Port number at which the Spotify Connect Zeroconf API can be reached on the Spotify Connect device (e.g. 8200).
• cpath - Spotify Connect Zeroconf API CPath property value (e.g. '/zc').
• version - (optional) Spotify Connect Zeroconf API version number that the device supports (e.g. '1.0'). Default is '1.0'.
• use_ssl - (optional) Spotify Connect Zeroconf API version number that the device supports (e.g. False). Default is False.
• delay - (optional) Time delay (in seconds) to wait AFTER issuing a command to the device. This delay will give the spotify zeroconf api time to process the change before another command is issued. Default is 0.50; value range is 0 - 10.

Example YAML

service: spotifyplus.zeroconf_device_disconnect
data:
  entity_id: media_player.spotifyplus_john_s
  host_ipv4_address: 192.168.1.81
  host_ip_port: 8200
  cpath: /zc
  version: 1
  use_ssl: false

Example Response

A dictionary that contains the following keys:

• user_profile: A (partial) user profile that retrieved the result.
• result: A ZeroconfResponse object that contains the response.

user_profile:
  country: US
  display_name: John Smith
  email: jsmith@maildomain.com
  id: 3758dfdsfjk435hjk6k79lm0n3c4
  product: premium
  type: user
  uri: spotify:user:3758dfdsfjk435hjk6k79lm0n3c4
result:
  SpotifyError: 0
  Status: 101
  StatusString: OK
  ResponseSource: null

ZeroConf Device GetInformation

Calls the getInfo Spotify Zeroconf API endpoint to return information about the device.

Use the ZeroConf Discover Devices service to retrieve the various parameters for this method.

This service will return service response data.

Parameters

All parameters are required unless otherwise noted.

• entity_id - Entity ID of the SpotifyPlus device that will make the request to the ZeroConf service.
• host_ipv4_address - IPV4 address at which the Spotify Connect Zeroconf API can be reached on the Spotify Connect device (e.g. '192.168.1.81').
• host_ip_port - Port number at which the Spotify Connect Zeroconf API can be reached on the Spotify Connect device (e.g. 8200).
• cpath - Spotify Connect Zeroconf API CPath property value (e.g. '/zc').
• version - (optional) Spotify Connect Zeroconf API version number that the device supports (e.g. '1.0'). Default is '1.0'.
• use_ssl - (optional) Spotify Connect Zeroconf API version number that the device supports (e.g. False). Default is False.

Example YAML

service: spotifyplus.zeroconf_device_getinfo
data:
  entity_id: media_player.spotifyplus_john_s
  host_ipv4_address: 192.168.1.81
  host_ip_port: 8200
  cpath: /zc
  version: 1
  use_ssl: false

Example Response

A dictionary that contains the following keys:

• user_profile: A (partial) user profile that retrieved the result.
• result: A ZeroconfGetInfo object that contains the response.

user_profile:
  country: US
  display_name: John Smith
  email: jsmith@maildomain.com
  id: 3758dfdsfjk435hjk6k79lm0n3c4
  product: premium
  type: user
  uri: spotify:user:3758dfdsfjk435hjk6k79lm0n3c4
result:
  SpotifyError: 0
  Status: 101
  StatusString: OK
  ResponseSource: null
  AccountReq: DONTCARE
  ActiveUser: 31l77y2123456789012345678901
  Aliases: []
  Availability: ""
  BrandDisplayName: Bose
  ClientId: 12345678901234567890123456789012
  DeviceId: 30fbc80e35598f3c242f2121234567890d9715fe
  DeviceType: SPEAKER
  GroupStatus: NONE
  LibraryVersion: 3.88.29-gc4d4bb01
  ModelDisplayName: Soundtouch
  ProductId: 70001
  PublicKey: xxxxxxxxx
  RemoteName: Bose-ST10-1
  ResolverVersion: "0"
  Scope: streaming
  SupportedCapabilities: null
  SupportedDrmMediaFormats: []
  TokenType: accesstoken
  Version: 2.7.1
  VoiceSupport: "YES"

ZeroConf Discover Devices

Discover Spotify Connect devices on the local network via the ZeroConf (aka MDNS) service, and return details about each device.

This service will return service response data.

Parameters

All parameters are required unless otherwise noted.

• entity_id - Entity ID of the SpotifyPlus device that will make the request to the ZeroConf service.
• timeout - Maximum amount of time to wait (in seconds) for the discovery to complete. Default is 5, range is 1 thru 10.

Example YAML

service: spotifyplus.zeroconf_discover_devices
data:
  entity_id: media_player.spotifyplus_john_s
  timeout: 2

Example Response

A dictionary that contains the following keys:

• user_profile: A (partial) user profile that retrieved the result.
• result: An array of ZeroconfDiscoveryResult objects of matching results.

user_profile:
  country: US
  display_name: John Smith
  email: jsmith@maildomain.com
  id: 3758dfdsfjk435hjk6k79lm0n3c4
  product: premium
  type: user
  uri: spotify:user:3758dfdsfjk435hjk6k79lm0n3c4
result:
  - DeviceName: Bose-ST10-1
    Domain: .local
    HostIpv4Address: 192.168.1.81
    HostIpPort: 8200
    HostTTL: 120
    Key: bose-st10-1._spotify-connect._tcp.local.
    Name: Bose-ST10-1._spotify-connect._tcp.local.
    Priority: 0
    OtherTTL: 4500
    Server: Bose-SM2-341513fbeeae.local.
    ServerKey: bose-sm2-341513fbeeae.local.
    ServiceType: _spotify-connect._tcp.local.
    Weight: 0
    Properties:
      - Name: CPath
        Value: /zc
      - Name: VERSION
        Value: "1.0"
    SpotifyConnectCPath: /zc
    SpotifyConnectIsInDeviceList: false
    SpotifyConnectVersion: "1.0"
    ZeroconfApiEndpointAddUser: http://192.168.1.81:8200/zc?action=addUser&version=1.0
    ZeroconfApiEndpointGetInformation: http://192.168.1.81:8200/zc?action=getInfo&version=1.0
    ZeroconfApiEndpointResetUsers: http://192.168.1.81:8200/zc?action=resetUsers&version=1.0
  - DeviceName: Bose-ST300
    Domain: .local
    HostIpv4Address: 192.168.1.80
    HostIpPort: 8200
    HostTTL: 120
    Key: bose-st300._spotify-connect._tcp.local.
    Name: Bose-ST300._spotify-connect._tcp.local.
    Priority: 0
    OtherTTL: 4500
    Server: Bose-SM2-d43639610922.local.
    ServerKey: bose-sm2-d43639610922.local.
    ServiceType: _spotify-connect._tcp.local.
    Weight: 0
    Properties:
      - Name: CPath
        Value: /zc
      - Name: VERSION
        Value: "1.0"
    SpotifyConnectCPath: /zc
    SpotifyConnectIsInDeviceList: false
    SpotifyConnectVersion: "1.0"
    ZeroconfApiEndpointAddUser: http://192.168.1.80:8200/zc?action=addUser&version=1.0
    ZeroconfApiEndpointGetInformation: http://192.168.1.80:8200/zc?action=getInfo&version=1.0
    ZeroconfApiEndpointResetUsers: http://192.168.1.80:8200/zc?action=resetUsers&version=1.0