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 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. Whennull
or absent, equivalent to an empty dictionary.- generalErrorReports
object
A dictionary whose values are GeneralErrorReport objects and whose keys assign names to these objects. Whennull
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.
- 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. Whennull
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. Whennull
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
andTAB
. - 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. Whennull
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. Whennull
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
ornull
or absent, this item should be presented in the normal manner (not visually deemphasized).
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. Whennull
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 thenextTrack
member is null or absent and repeat mode is active. Whennull
or absent, the current chain of track container chunks does not have a first track instance. If thenextTrackPointer
member is null or absent, advancing from the last track instance in thetrackInstances
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 theprevTrackPointer
member is null or absent and repeat mode is active. Whennull
or absent, the current chain of track container chunks does not have a last track instance. If theprevTrackPointer
member is null or absent, skipping backward from the first track instance in thetrackInstances
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. Whennull
or absent, if repeat mode is active and thelastTrackPointer
member is non-null, skipping backward from the first track instance in thetrackInstances
array should result in playing the track instance indicated by thelastTrackPointer
member. Otherwise, skipping backward from the first track instance in thetrackInstances
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. Whennull
or absent, if repeat mode is active and thefirstTrackPointer
member is non-null, advancing from the last track instance in thetrackInstances
array should result in playing the track instance indicated by thefirstTrackPointer
member. Otherwise, advancing from the last track instance in thetrackInstances
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. Whenfalse
ornull
or absent, tracks that belong to this track container do not support ratings. ThetrackRating
member of every track’s TrackDefinition will benull
or absent.
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’strackInstances
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. Whennull
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. Whennull
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. Whennull
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
orfalse
.true
means that this track contains explicit language. See section Explicit Language Filter for details. Ifnull
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.
- 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
). Whenfalse
or null or absent, client applications should not automatically skip over this track, and should instead present the error report provided in theerror
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 atrue
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. Iftrue
, 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
andshuffleTrackPointer
will be the same as this track definition. Whennull
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 thenaturalTrackPointer
member should be used instead. - isExplicit
string
- Whether this playable contains music with explicit language (
true
,false
, orpartial
). See section Explicit Language Filter for details. Ifnull
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
orfalse
. Iftrue
, the image is a stock Amazon Music icon. Iffalse
,null
, or absent, then the image is an item-specific image (i.e. album art). Clients may opt not to display images withisIcon=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
orfalse
. Whentrue
, the Amazon Music service is available in the specified geographical area. Whenfalse
, 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.