Services Provided

The following custom services are provided by this integration.

Follow Artists
Follow Playlist
Follow Users
Get Album
Get Album Favorites
Get Album New Releases
Get Artist
Get Artists Albums
Get Artists Followed
Get Browse Categories
Get Category Playlists
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 Favorites
Get Show
Get Show Episodes
Get Show Favorites
Get Spotify Connect Devices
Get Track Favorites
Get Users Top Artists
Get Users Top Tracks
Player Activate Devices
Player Media Play Context
Player Media Play Track Favorites
Player Media Play Tracks
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
Save Album Favorites
Save Track Favorites
Remove Album Favorites
Remove 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

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 - The Spotify ID of the playlist (e.g. 37i9dQZF1E39vTG3GurFPW).
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 - The Spotify ID of the album. 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: [email protected]
  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 - The maximum number of items to return in a page of items. Default is 20, Range is 1 to 50.
offset - 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. example: US
limit_total - 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_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: [email protected]
  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 - The maximum number of items to return in a page of items. Default is 20, Range is 1 to 50.
offset - 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 - 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 - 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_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: [email protected]
  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 - The Spotify ID of the artist. 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: [email protected]
  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 - The Spotify ID of the artist. Example: 6APm8EjxOHSYM5B4i3vT3q
include_groups - 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 - The maximum number of items to return in a page of items. Default is 20, Range is 1 to 50.
offset - 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. example: US
limit_total - 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_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: [email protected]
  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 - The last artist ID retrieved from the previous request, or null for the first request. example: "6APm8EjxOHSYM5B4i3vT3q"
limit - The maximum number of items to return in a page of items. Default is 20, Range is 1 to 50.
limit_total - 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_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: [email protected]
  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.

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: [email protected]
  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

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 - The maximum number of items to return in a page of items. Default is 20, Range is 1 to 50.
offset - 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 - 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 - 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_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: [email protected]
  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 Featured Playlists

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 - The maximum number of items to return in a page of items. Default is 20, Range is 1 to 50.
offset - 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 - 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 - 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 - 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 - 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_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: [email protected]
  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.

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: [email protected]
  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: [email protected]
  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: [email protected]
  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: [email protected]
  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: [email protected]
  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.

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. 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: [email protected]
  id: 3758dfdsfjk435hjk6k79lm0n3c4
  product: premium
  type: user
  uri: spotify:user:3758dfdsfjk435hjk6k79lm0n3c4
result:
  ... <data truncated for brevity - same results as Spotify Web API returns>

Get Playlist Favorites

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 - The maximum number of items to return in a page of items. Default is 20, Range is 1 to 50.
offset - 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 - 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_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: [email protected]
  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 - The Spotify ID for the show. Example: 5CfCWKI5pZ28U0uOzXkDHe
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_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: [email protected]
  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 - The Spotify ID for the show. Example: 6kAsbP8pxwaU2kPibKTuHE
limit - The maximum number of items to return in a page of items. Default is 20, Range is 1 to 50.
offset - 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. example: US
limit_total - 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: [email protected]
  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 - The maximum number of items to return in a page of items. Default is 20, Range is 1 to 50.
offset - 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 - 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_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: [email protected]
  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 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 Device objects are populated, as the information is gathered from both static and dynamic devices. The populated properties are: id, name, and type.

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_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 list of Device objects that contain the device details, sorted by name.

user_profile:
  country: US
  display_name: John Smith
  email: [email protected]
  id: 3758dfdsfjk435hjk6k79lm0n3c4
  product: premium
  type: user
  uri: spotify:user:3758dfdsfjk435hjk6k79lm0n3c4
result:
  - id: 30fbc80e35598f3c242f2120413c943dfd9715fe
    is_active: true
    is_private_session: false
    is_restricted: false
    name: Bose-ST10-1
    supports_volume: false
    type: SPEAKER
    volume_percent: 0
  - id: 5d4931f9d0684b625d702eaa24137b2c1d99539c
    is_active: true
    is_private_session: false
    is_restricted: false
    name: Bose-ST10-2
    supports_volume: false
    type: SPEAKER
    volume_percent: 0
  - id: 3756903295ba7b47f8c36fc9a4ff7d833431a667
    is_active: true
    is_private_session: false
    is_restricted: false
    name: Bose-ST300
    supports_volume: false
    type: SPEAKER
    volume_percent: 0
  - id: 753b8ed0c25b783c48c4dea784cd4ce8c29030f5
    is_active: true
    is_private_session: false
    is_restricted: false
    name: Web Player (Chrome)
    supports_volume: false
    type: Computer
    volume_percent: 0

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 - The maximum number of items to return in a page of items. Default is 20, Range is 1 to 50.
offset - 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. example: US
limit_total - 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_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: [email protected]
  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 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 - The maximum number of items to return in a page of items. Default is 20, Range is 1 to 50.
offset - 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 - 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_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: [email protected]
  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 - The maximum number of items to return in a page of items. Default is 20, Range is 1 to 50.
offset - 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 - 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_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: [email protected]
  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. A Spotify Zeroconf API getInfo call is then issued for each device that was found to retrieve device information. A Spotify Zeroconf API addUser call is also issued for each device that does not have an active user context established, OR if the currently active user context does not match the Spotify Connect Username value specified in the integration configuration options and the verify_user_context argument is True.

The user context switch is bypassed if the verify_user_context argument is False. If the user context is to be switched, then a Disconnect will be issued if a user context is active on the device followed by a Connect to the user context specified in the integration configuration options.

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.

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: [email protected]
  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: [email protected]
  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 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 Resolve Device ID

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.

A Zeroconf discovery process is initiated to search for all Spotify Connect devices connectedto the local network. A Spotify Zeroconf API getInfo call is then issued for each device that was found, searching for a match on the device_value argument. Depending on the format of the 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 (for multi-room configurations).

The device ID value is returned if a match is found; otherwise, null is returned.

A user context switch will also be performed if a device id is resolved AND the active user of the device does not match the Spotify Connect Username value specified in the integration configuration options. The user context switch is bypassed if the verify_user_context argument is False, or if the Spotify Connect Username was not supplied in the integration configuration options. If the user context is to be switched, then a Disconnect will be issued if a user context is active on the device followed by a Connect to the user context specified in the integration configuration options.

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 in the integration configuration options. If False, the user context will not be checked. Default is True.
verify_timeout (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 5.0; value range is 0 - 10.

Example YAML

Resolve Spotify Connect player device by it's name value.

service: spotifyplus.player_resolve_device_id
data:
  entity_id: media_player.spotifyplus_john_s
  device_value: Bose-ST10-1
  verify_user_context: true
  verify_timeout: 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: [email protected]
  id: 3758dfdsfjk435hjk6k79lm0n3c4
  product: premium
  type: user
  uri: spotify:user:3758dfdsfjk435hjk6k79lm0n3c4
result: 30fbc80e35598f3c242f2120413c943dfd9715fe

Example YAML

Resolve Spotify Connect player device by it's ID value.

service: spotifyplus.player_resolve_device_id
data:
  entity_id: media_player.spotifyplus_john_s
  device_value: 30fbc80e35598f3c242f2120413c943dfd9715fe
  verify_user_context: true
  verify_timeout: 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: [email protected]
  id: 3758dfdsfjk435hjk6k79lm0n3c4
  product: premium
  type: user
  uri: spotify:user:3758dfdsfjk435hjk6k79lm0n3c4
result: 30fbc80e35598f3c242f2120413c943dfd9715fe

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.

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: [email protected]
  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

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

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

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

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 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 - The maximum number of items to return in a page of items. Default is 20, Range is 1 to 50.
offset - 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. example: US
include_external - 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 - 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: [email protected]
  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 - The maximum number of items to return in a page of items. Default is 20, Range is 1 to 50.
offset - 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. example: US
include_external - 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 - 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: [email protected]
  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 - The maximum number of items to return in a page of items. Default is 20, Range is 1 to 50.
offset - 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. example: US
include_external - 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 - 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: [email protected]
  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 - The maximum number of items to return in a page of items. Default is 20, Range is 1 to 50.
offset - 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. example: US
include_external - 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 - 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: [email protected]
  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 - The maximum number of items to return in a page of items. Default is 20, Range is 1 to 50.
offset - 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. example: US
include_external - 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 - 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: [email protected]
  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 - The maximum number of items to return in a page of items. Default is 20, Range is 1 to 50.
offset - 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. example: US
include_external - 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 - 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: [email protected]
  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 - The maximum number of items to return in a page of items. Default is 20, Range is 1 to 50.
offset - 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. example: US
include_external - 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 - 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: [email protected]
  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 - The Spotify ID of the playlist (e.g. 37i9dQZF1E39vTG3GurFPW).

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. '[email protected]') 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.

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: [email protected]
  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: [email protected]
  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.

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: [email protected]
  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: [email protected]
  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: [email protected]
  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