Amazon Music Device API

Warning: This API is DEPRECATED. Please avoid using this API and consider migrating to the new Web 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 JavaScript 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: LocalReference<T> (link); Refers to the main object in this document.
navigationNodeSummaries: object; A dictionary whose values are NavigationNodeSummary objects and whose keys assign names to these objects. When null or absent, equivalent to an empty dictionary.
navigationNodeDescriptions: object; A dictionary whose values are NavigationNodeDescription objects and whose keys assign names to these objects. When null or absent, equivalent to an empty dictionary.
itemDescriptions: object; A dictionary whose values are ItemDescription objects and whose keys assign names to these objects. When null or absent, equivalent to an empty dictionary.
trackContainerChunkDescriptions: object; A dictionary whose values are TrackContainerChunkDescription objects and whose keys assign names to these objects. When null or absent, equivalent to an empty dictionary.
trackInstances: object; A dictionary whose values are TrackInstance objects and whose keys assign names to these objects. When null or absent, equivalent to an empty dictionary.
trackDefinitions: object; A dictionary whose values are TrackDefinition 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.
generalErrorReports: object A dictionary whose values are GeneralErrorReport 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 TrackRatingResponse objects and whose keys assign names to these objects. When null or absent, equivalent to an empty dictionary.

NavigationNodeSummary

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.
numItemsOfInterest: 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 NavigationNodeDescription can be found.

NavigationNodeDescription

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

Note: A node’s parent is not the same as its enclosing node, because a node can have more than one enclosing node, but only one parent.

image: ImageInfo (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.
firstPage: 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.
lastPage `: 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.
prevPage: 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.
nextPage: 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

ItemDescription

Something that belongs to a Navigation Node.

itemLabel: string; The text that should be used to label this item in the context of its enclosing navigation node.
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.
navigationNodeSummary: LocalReference<NavigationNodeSummary> (link); This item is a reference to a NavigationNodeSummary. 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).

Note: For an item i in document d, if i.navigationNodeSummary is not null, then it is guaranteed that i.playable = d.navigationNodeSummaries[i.navigationNodeSummary].playable.

TrackContainerChunkDescription

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.
trackInstances: LocalReference<TrackInstance> (link); An array of Track Instances range of tracks belonging to the container that should be played in sequence.
firstTrackPointer: 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 trackInstances array if the nextTrack 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 nextTrackPointer member is null or absent, advancing from the last track instance in the trackInstances array should be disallowed.
lastTrackPointer: 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 trackInstances array if the prevTrackPointer 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 prevTrackPointer member is null or absent, skipping backward from the first track instance in the trackInstances array should be disallowed.
prevTrackPointer: TrackPointer (link); A pointer to the track instance in the preceeding chunk that precedes the first track instance in the current trackInstances array. When null or absent, if repeat mode is active and the lastTrackPointer member is non-null, skipping backward from the first track instance in the trackInstances array should result in playing the track instance indicated by the lastTrackPointer member. Otherwise, skipping backward from the first track instance in the trackInstances array should be disallowed.
nextTrackPointer: TrackPointer (link); A pointer to the track instance in the next chunk that follows the last track instance in the current trackInstances array. When null or absent, if repeat mode is active and the firstTrackPointer member is non-null, advancing from the last track instance in the trackInstances array should result in playing the track instance indicated by the firstTrackPointer member. Otherwise, advancing from the last track instance in the trackInstances array should be disallowed.
permitsTrackRatings: true; Tracks that belong to this track container may support ratings; that is, each track’s TrackDefinition may have a non-null trackRating 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 trackRating member of every track’s TrackDefinition will be null or absent.

Note: Although this member is defined on a track container chunk, it applies to all the tracks in the track container, including tracks that appear in other chunks. All chunks in a track container will have semantically equivalent values for this member.

TrackPointer

Identifies a particular track within a track container chunk.

chunk: RemoteReference<TrackContainerChunkDescription> (link); The TrackContainerChunkDescription that contains this track instance.
indexWithinChunk: nonnegative integer; The zero-based index into the track container chunk’s trackInstances 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 trackInstances 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.)

TrackInstance

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

trackDefinition: LocalReference<TrackDefinition> (link); The definition of this track.
playbackEventCollector: LocalReference<PlaybackEventCollector> (link); URI of the PlaybackEventCollector 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.

TrackDefinition

Defines a track.

trackTag: string (length greater than one); An opaque string value, such that two track instances with the same trackTag 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.

Note: The track definition will contain either audio or an error, never both.

autoSkipOnError: 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 autoAdvance). 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.
trackRating: object (link); A track rating object that provides the rating for this track. This member will be non-null only if the permitsTrackRatings member of the track’s TrackContainerChunkDescription object has a true value.

TrackRatingRequest

A request sent from the client to rate a track.

The track rating request must be submitted to the ratingURI provided in the trackRating element of the TrackDefinition.

thumbRating: enum {"thumbs_up", "thumbs_down", "neutral"}; Thumb rating of the track.
trackPosition: number; The distance from the beginning of the track when the track was rated, in milliseconds.
wallClockTime: timestamp (link); The actual time when the track was rated.

TrackRatingResponse

Defines a response for the track rating request.

shouldSkip: 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 naturalTrackPointer and shuffleTrackPointer 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 naturalTrackPointer 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.

ImageInfo

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 TrackRatingHandler where ratings should be reported. When null or absent, this track does not support ratings.

GeneralErrorReport

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

PlaybackEventReport

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

AvailabilityResponse

Indicates the availability of the Amazon Music service in a particular geographical area, in response to a request to an AvailabilityQuery 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.

Amazon Music Device API

JSON Object Types

Document<T>

Navigation­Node­Summary

Navigation­Node­Description

Item­Description

Track­Container­Chunk­Description

Track­Pointer

Track­Instance

Track­Definition

Track­Rating­Request

Track­Rating­Response