Amazon Music Device API

JSON Object Types

The object types in this section define the structure and semantics of documents and objects used in API request and response entities.

Documents that belong to these types use Java­Script Object Notation (JSON) as a data interchange format. The IANA media type for JSON is application/json.

Requests whose entities are in the JSON format must include a Content-Type header with the value “application/json”. A request that can respond with an entity in JSON format will do so if the request includes an Accept header such that application/json is the most acceptable media type.

An overview is given in the section JSON Protocol.

Document<T>

This is the common object type used for all JSON-formatted response entities. It consists of a set of object dictionaries that define various objects that can be referred to by name.

result
Local­Reference<T> (link)
Refers to the main object in this document.
navigation­Node­Summaries
object
A dictionary whose values are Navigation­Node­Summary objects and whose keys assign names to these objects. When null or absent, equivalent to an empty dictionary.
navigation­Node­Descriptions
object
A dictionary whose values are Navigation­Node­Description objects and whose keys assign names to these objects. When null or absent, equivalent to an empty dictionary.
item­Descriptions
object
A dictionary whose values are Item­Description objects and whose keys assign names to these objects. When null or absent, equivalent to an empty dictionary.
track­Container­Chunk­Descriptions
object
A dictionary whose values are Track­Container­Chunk­Description objects and whose keys assign names to these objects. When null or absent, equivalent to an empty dictionary.
track­Instances
object
A dictionary whose values are Track­Instance objects and whose keys assign names to these objects. When null or absent, equivalent to an empty dictionary.
track­Definitions
object
A dictionary whose values are Track­Definition objects and whose keys assign names to these objects. When null or absent, equivalent to an empty dictionary.
playables
object :A dictionary whose values are Playable objects and whose keys assign names to these objects. When null or absent, equivalent to an empty dictionary.
general­Error­Reports
object A dictionary whose values are General­Error­Report objects and whose keys assign names to these objects. When null or absent, equivalent to an empty dictionary.
trackRatingResponses
object
A dictionary whose values are Track­Rating­Response objects and whose keys assign names to these objects. When null or absent, equivalent to an empty dictionary.

A navigation node summary provides only minimal information, such as the node title and a remote reference to the URI where the full description of the navigation node may be found.

title
string (length greater than 1)
The title of this navigation node.
num­Items­Of­Interest
nonnegative integer
An approximate count of the number of “items of interest” that can be discovered through this navigation node. The meaning of this member depends on the context in which it appears. For example, for a navigation node titled “All Albums,” this member gives an approximate count of albums available via the node. When null or absent, the number of items of interest is unknown or irrelevant.
playable
LocalReference<Playable> (link)
This navigation node is also a Playable This member provides a reference to the playable. When null or absent, this navigation node is not a playable.
description
RemoteReference<NavigationNodeDescription> (link)
Provides a reference to where the complete Navigation­Node­Description can be found.

The navigation node description provides complete information about this node, including a full list of the items that belong to the node. Child nodes of a navigation node are defined using the Item­Description type. For items that are Navigation Nodes, the item description provides a local reference to a navigation node summary for that item.

summary
LocalReference<NavigationNodeSummary> (link)
Reference to the NavigationNodeSummary for this node. Basic information such as the node’s title is available from the summary.
parent
RemoteReference<NavigationNodeSummary> (link)
Reference to the NavigationNodeSummary of this node’s parent node. When null or absent, this node has no parent.
image
Image­Info (link)
An image for this item. The image role is navigation-node for the purpose of applying the X-Amz-Music-Images-Shrink request header. When null or absent, no image exists for this navigation node, or no image is available in a format acceptable to the client according to the provided X-Amz-Music-Images-Accept header.
artist
object
An object that describes this navigation node’s artist, with the member name (string), which is the name of the artist. When null or absent, the navigation node does not have an artist.
items
array
An array of LocalReference<ItemDescription>'s for a page’s worth of items that this navigation node encloses.
first­Page
RemoteReference<NavigationNodeDescription> (link)
Reference to a NavigationNodeDescription that contains the first page of items enclosed by this navigation node. When null or absent, the first page of items enclosed by this navigation node cannot be navigated to directly.
last­Page `
RemoteReference<NavigationNodeDescription> (link)
Reference to a NavigationNodeDescription that contains the last page of items enclosed by this navigation node. When null or absent, the last page of items enclosed by this navigation node cannot be navigated to directly.
prev­Page
RemoteReference<NavigationNodeDescription> (link)
Reference to a NavigationNodeDescription that contains the previous page of items enclosed by this navigation node. When null or absent, there is no previous page of this item.
next­Page
RemoteReference<NavigationNodeDescription> (link)
Reference to a NavigationNodeDescription that contains the next page of items enclosed by this navigation node. When null or absent, there is no next page of this item.
displayTag
array
An array of suggestions for how the contents of this navigation node can be displayed, subject to the client platforms UX capabilities and design paradigms. Roughly equivalent presentations that make sense in a specific clients UX are acceptable. If ignored, navigation nodes should be displayed as usual. The possible values are INLINE and TAB.
Inline child nodes' titles can be used as a non-selectable section header, and their contents displayed as a list of results. This value is used when multiple navigation node contents can be displayed in a single long list, and these titles break the list into categories.
Tab child nodes’ titles can be used as the tab names in a tabbed display of multiple navigation nodes, and their contents displayed within each tab. This value is used when multiple navigation node contents can reasonably be presented as tabs or similarly grouped items.
When null or absent, Amazon has no display suggestions

Item­Description

Something that belongs to a Navigation Node.

item­Label
string
The text that should be used to label this item in the context of its enclosing navigation node.
image
Image­Info (link)
An image for this item. The image role is item for the purpose of applying the X-Amz-Music-Images-Shrink request header. When null or absent, no image exists for this item, or no image is available in a format acceptable to the client according to the provided X-Amz-Music-Images-Accept header.
navigation­Node­Summary
LocalReference<NavigationNodeSummary> (link)
This item is a reference to a Navigation­Node­Summary. When null or absent, this item is not a navigation node.
playable
LocalReference<Playable> (link)
This item is reference to a Playable. When null or absent, this item is not a navigation node, this item is not a playable.
artist
object
An object that describes this navigation node’s artist, with the member name (string), which is the name of the artist. When null or absent, the navigation node does not have an artist.
subtitle
string
Additional information about the item displayed under the label. When null or absent, this item does not have a subtitle.
deemphasize
true
This item’s presentation may be visually deemphasized (dimmed, grayed, blurred, etc.) due to a problem with the item or its subitems. The user should still be allowed to select the item in order to discover the specific nature of the problem, which would typically be revealed through a General Error. When false or null or absent, this item should be presented in the normal manner (not visually deemphasized).

Track­Container­Chunk­Description

Describes a track container chunk, a container for a group of tracks that belong to the container that should be played in sequence.

title
string (length greater than 1)
The title of this track container.
image
ImageInfo (link)
An image for this item. The image role is item for the purpose of applying the X-Amz-Music-Images-Shrink request header. When null or absent, no image exists for this item, or no image is available in a format acceptable to the client according to the provided X-Amz-Music-Images-Accept header.
track­Instances
LocalReference<TrackInstance> (link)
An array of Track Instances range of tracks belonging to the container that should be played in sequence.
first­Track­Pointer
TrackPointer (link)
A pointer to the first track instance in the current chain of track container chunks. This track instance should be played when advancing from the last track instance in the track­Instances array if the next­Track member is null or absent and repeat mode is active. When null or absent, the current chain of track container chunks does not have a first track instance. If the next­Track­Pointer member is null or absent, advancing from the last track instance in the track­Instances array should be disallowed.
last­Track­Pointer
TrackPointer (link)
A pointer to the last track instance in the current chain of track container chunks. This track instance should be played when skipping backward from the first track instance in the track­Instances array if the prev­Track­Pointer member is null or absent and repeat mode is active. When null or absent, the current chain of track container chunks does not have a last track instance. If the prev­Track­Pointer member is null or absent, skipping backward from the first track instance in the track­Instances array should be disallowed.
prev­Track­Pointer
TrackPointer (link)
A pointer to the track instance in the preceeding chunk that precedes the first track instance in the current track­Instances array. When null or absent, if repeat mode is active and the last­Track­Pointer member is non-null, skipping backward from the first track instance in the track­Instances array should result in playing the track instance indicated by the last­Track­Pointer member. Otherwise, skipping backward from the first track instance in the track­Instances array should be disallowed.
next­Track­Pointer
TrackPointer (link)
A pointer to the track instance in the next chunk that follows the last track instance in the current track­Instances array. When null or absent, if repeat mode is active and the first­Track­Pointer member is non-null, advancing from the last track instance in the track­Instances array should result in playing the track instance indicated by the first­Track­Pointer member. Otherwise, advancing from the last track instance in the track­Instances array should be disallowed.
permits­Track­Ratings
true
Tracks that belong to this track container may support ratings; that is, each track’s TrackDefinition may have a non-null track­Rating member. It is not guaranteed that every track supports ratings; in fact, it is possible that none of them support ratings. When false or null or absent, tracks that belong to this track container do not support ratings. The track­Rating member of every track’s Track­Definition will be null or absent.

Track­Pointer

Identifies a particular track within a track container chunk.

chunk
RemoteReference<TrackContainerChunkDescription> (link)
The TrackContainerChunkDescription that contains this track instance.
index­Within­Chunk
nonnegative integer
The zero-based index into the track container chunk’s track­Instances array where this track can be found. If the integer is negative, the –1-based index from the end of the track container chunk’s track­Instances array where this track can be found. (–1 designates the last element of the array; –2 designates the second-to-last element, and so on.)

Track­Instance

Describes the occurrence of a track within a track container chunk.

track­Definition
LocalReference<TrackDefinition> (link)
The definition of this track.
playback­Event­Collector
LocalReference<PlaybackEventCollector> (link)
URI of the Playback­Event­Collector resource to which playback event reports should be reported while playing this track.
self
RemoteReference<Playable> (link)
URI used when creating a play queue and playback of the track. This URI is transitory, and must not be used for bookmarking, storage as a local favorite, or similar user stories.

Track­Definition

Defines a track.

track­Tag
string (length greater than one)
An opaque string value, such that two track instances with the same track­Tag value are actually referring to the same track within the track container.
title
string (length greater than one)
The title of the track.
artist
object
An object that describes this track’s artist, with the member name (string), which is the name of the artist. When null or absent, the navigation node does not have an artist.
album
object
An object that describes this track’s album, with the member name (string), which is the name of the album. When null or absent, the navigation node does not have an album.
image
ImageInfo (link)
An image for this track. The image role is track for the purpose of applying the X-Amz-Music-Images-Shrink request header. When null or absent, no image exists for this item, or no image is available in a format acceptable to the client according to the provided X-Amz-Music-Images-Accept header.
duration
nonnegative integer
An approximate duration of the track stream in milliseconds. Duration information obtained from the audio data itself should be considered more reliable than the approximate duration given here. When null or absent, the track is of unknown or indefinite duration.
audio
object (link)
The audio data for this track. Every TrackDefinition will contain either an audio object or an error, never both. When null or absent, no audio stream is available for this track.
isExplicit
string
Will contain a value of true or false. true means that this track contains explicit language. See section Explicit Language Filter for details. If null or absent, then the explicitness of the track is unknown.
error
LocalReference<GeneralErrorReport> (link)
An object describing an error condition that applies to this track. This error report should be presented to the user instead of attempting playback. When null or absent, there is nothing wrong with this track.
auto­Skip­On­Error
true
In the case of an error, client applications may skip over this track when automatically advancing from the previous track (that is, when the reason code would be auto­Advance). When false or null or absent, client applications should not automatically skip over this track, and should instead present the error report provided in the error member.
track­Rating
object (link)
A track rating object that provides the rating for this track. This member will be non-null only if the permits­Track­Ratings member of the track’s Track­Container­Chunk­Description object has a true value.

Track­Rating­Request

A request sent from the client to rate a track.

The track rating request must be submitted to the rating­URI provided in the track­Rating element of the TrackDefinition.

thumb­Rating
enum {"thumbs_up", "thumbs_down", "neutral"}
Thumb rating of the track.
track­Position
number
The distance from the beginning of the track when the track was rated, in milliseconds.
wall­Clock­Time
timestamp (link)
The actual time when the track was rated.

Track­Rating­Response

Defines a response for the track rating request.

should­Skip
boolean
Indicates whether the client should skip the rated track or not. If false, continue playback. If true, immediately skip ahead to the next track.
message
string
Provides a message to display to the customer. A toast pop-up or similar transient display is appropriate.

Playable

Something that initiates playback when selected. It could be a track container or an individual track within a track container.

self
RemoteReference<Playable> (link)
A canonical reference for this playable. Client applications can store the resolved URI for later use, for example, to allow users to “bookmark” a playable.
trackDefinition
LocalReference<TrackDefinition> (link)
This item designates a particular track whose TrackDefinition is the specified value. The track definitions of the track instances pointed to by natural­Track­Pointer and shuffle­Track­Pointer will be the same as this track definition. When null or absent, this item does not designate any particular track.
naturalTrackPointer
TrackPointer (link)
Points to the track instance that should be played when this playable is selected and shuffle mode is off.
shuffleTrackPointer
TrackPointer (link)
Points to the track that should be played when this playable is selected and shuffle mode is on. When null or absent, this playable does not support shuffle mode; the track pointer given by the natural­Track­Pointer member should be used instead.
isExplicit
string
Whether this playable contains music with explicit language (true, false, or partial). See section Explicit Language Filter for details. If null or absent, then the explicitness of the track is unknown.

Image­Info

Describes an image.

uri
string
URI where the image data is located.
contentType
string
The IANA media type of the image.
width
nonnegative integer
Actual width of the image, in pixels, after applying the X-Amz-Music-Images-Shrink request header.
height
nonnegative integer
Actual height of the image, in pixels, after applying the X-Amz-Music-Images-Shrink request header.
isIcon
string
Designates an image that is a standard Amazon Music icon as opposed to image-specific art such as cover art. Values may be true or false. If true, the image is a stock Amazon Music icon. If false, null, or absent, then the image is an item-specific image (i.e. album art). Clients may opt not to display images with isIcon=true; for example, if the Amazon icon design clashes with the partner application design.

Audio

An object that contains the audio data for a TrackDefinition.

uri
string
The URI of the audio data.
contentType
string
The IANA media type of the audio data.
expires
timestamp (link)
The time at which the audio URI will expire. To play a track with an expired audio URI, clients must obtain a new audio URI by reloading the resource that this track definition was obtained from. If null or absent The audio URI does not expire. null or absent No audio stream is available for this track, or the client did not provide any site identification.

Track Rating

An object that contains track rating info for a TrackDefinition.

thumbRating
enum {"thumbs_up", "thumbs_down", "neutral"}
Provides current thumb rating of track.
ratingURI
string
Provides the URI of the Track­Rating­Handler where ratings should be reported. When null or absent, this track does not support ratings.

General­Error­Report

An object that describes an error condition. For more information on this object, see the section on errors.

Playback­Event­Report

A report sent from the client to the service when a playback event occurs. See the section on playback for more details.

Availability­Response

Indicates the availability of the Amazon Music service in a particular geographical area, in response to a request to an Availability­Query resource.

available
string
Values may be true or false. When true, the Amazon Music service is available in the specified geographical area. When false, the Amazon Music service is not available in the specified geographical area. If the user is known to reside in the specified geographical area, the client application should not offer Amazon Music to the user.