Amazon Music Web API
Web API schema V1.0
Important:
These Amazon Music documents are in preview status. Be aware that content may change. Please use the
developer forum for any questions or comments.
Web API Object Schema
This is the object schema for the Amazon Music Web API.
Primary Entity Types
Album
Name |
Data Type |
Required |
Description |
id
|
string
|
Yes |
Identifier associated with this album. |
url
|
string
|
No |
The Amazon Music url for this album. |
globalAsin
|
string
|
No |
Globally unique identifier for this album. |
localAsin
|
string
|
No |
musicTerritory localized identifier for this album. |
title
|
string
|
No |
The title of this album. |
shortTitle
|
string
|
No |
The shortened title for this album |
duration
|
double
|
No |
The duration of this album in seconds. |
release
|
Release
|
No |
Release date information for this album. |
releaseDate
|
string
|
No |
The date the album was first released. |
musicTerritory
|
musicTerritory
|
No |
Localized territory identifier for this album. |
market
|
Market
|
No |
Market this album is referenced from |
availableMarkets
|
market[]
|
No |
An array of markets this album is available in. |
artists
|
artist[]
|
No |
Array of Artists associated with this album |
eligibility
|
Eligibility
|
No |
The eligibility associated with this album. |
parentalSettings
|
ParentalSettings
|
No |
Parental settings associated with this album |
tracks
|
track[]
|
No |
The tracks associated with this album. |
trackCount
|
double
|
No |
The number of tracks within this album. |
images
|
Image[]
|
No |
Array of Images associated with this album. |
label
|
string
|
No |
Label associated with this Album |
Artist
Name |
Data Type |
Required |
Description |
id
|
string
|
Yes |
Identifier associated with this artist. |
url
|
string
|
No |
The Amazon Music url for this artist. |
globalAsin
|
string
|
No |
Globally unique identifier for this artist. |
localAsin
|
string
|
No |
musicTerritory localized identifier for this artist. |
followerCount
|
double
|
No |
The count of followers for this artist. |
related
|
Artist connection
|
No |
A list of related artists |
images
|
Image[]
|
No |
Images associated with this artist. |
musicTerritory
|
musicTerritory
|
No |
musicTerritory localized identifier for this artist. |
market
|
Market
|
No |
Market this Asset is referenced from |
name
|
string
|
No |
The name of this Artist. |
albums
|
albums connection
|
No |
A connection list of albums for this artist |
tracks
|
tracks connection
|
No |
A connection list of tracks for this artist |
InitialPlaybackSessionResponse
Name |
Data Type |
Required |
Description |
pageInfo
|
PageInfo
|
No |
Object used for pagination. |
entities
|
PlaybackData[]
|
No |
Data associated with this playback object. |
metadata
|
PlaybackMetadata[]
|
No |
Metadata associated with this playback object. |
Playback
Name |
Data Type |
Required |
Description |
sessionId
|
string
|
Yes |
Identifier associated with this playback session. |
entityReferenceId
|
string
|
No |
Identifier associated with this object. |
metricId
|
string
|
No |
Identifier associated with event tracking. |
actions
|
Action[]
|
No |
A collection of Action objects specifying which are currently allowed and which are not. |
track
|
Track
|
No |
An object describing the current track. |
PlaybackDataResponse
Name |
Data Type |
Required |
Description |
pageInfo
|
PageInfo
|
No |
Object used for pagination. |
entities
|
PlaybackData[]
|
No |
Data associated with this playback object. |
Playlist
Name |
Data Type |
Required |
Description |
id
|
string
|
Yes |
Identifier associated with this playlist. |
url
|
string
|
No |
The Amazon Music URL for this playlist. |
title
|
string
|
No |
The title of this playlist. |
description
|
string
|
No |
The description of this playlist. |
duration
|
double
|
No |
The duration of this playlist in seconds. |
eligibility
|
Eligibility
|
No |
The eligibility associated with this playlist. |
tracks
|
Track Connection
|
No |
The tracks associated with this playlist. |
trackCount
|
double
|
No |
The number of tracks within this playlist. |
visibility
|
VisibilityType
|
No |
The visible state of this playlist to the public. |
curator
|
User
|
No |
The owner and creator of this playlist. |
images
|
Image[]
|
No |
Array of images associated with this playlist. |
PlayParams
Name |
Data Type |
Required |
Description |
id
|
string
|
Yes |
Identifier associated with this playable. |
containerId
|
string
|
No |
Identifier associated with this playable's container. |
selections
|
Selections[]
|
No |
Array of allowed selections. |
PodcastShow
Name |
Data Type |
Required |
Description |
id
|
string
|
Yes |
Identifier associated with this podcast. |
url
|
string
|
No |
The Amazon Music URL for this podcast. |
title
|
string
|
No |
The title of this podcast. |
type
|
string
|
No |
The type of podcast. |
description
|
string
|
No |
The description of this podcast. |
episodes
|
Podcast Episode Connection
|
No |
Episodes related to this podcast. |
author
|
string
|
No |
The author of this podcast. |
images
|
Image[]
|
No |
Array of images associated with this podcast. |
PodcastEpisode
Name |
Data Type |
Required |
Description |
id
|
string
|
Yes |
Identifier associated with this podcast episode. |
url
|
string
|
No |
The Amazon Music URL for this podcast episode. |
title
|
string
|
No |
The title of this podcast episode. |
type
|
string
|
No |
The type of podcast episode. |
description
|
string
|
No |
The description of this podcast episode. |
podcast
|
PodcastShow
|
No |
The podcast episode this is associated with. |
author
|
string
|
No |
The author of this podcast episode. |
seasonNumber
|
double
|
No |
The season for this podcast episode. |
episodeNumber
|
double
|
No |
The number of this podcast episode. |
images
|
Image[]
|
No |
Array of images associated with this podcast episode. |
duration
|
double
|
No |
The duration of this podcast episode in seconds. |
releaseDate
|
string
|
No |
The date this podcast episode was made available on Amazon Music. |
Station
Name |
Data Type |
Required |
Description |
id
|
string
|
Yes |
Identifier associated with this station. |
url
|
string
|
No |
The Amazon Music url for this station. |
name
|
string
|
No |
The name of this station. |
parentalSettings
|
ParentalSettings
|
No |
Parental settings associated with this station. |
images
|
Image[]
|
No |
Array of images associated with this station. |
Track
Name |
Data Type |
Required |
Description |
id
|
string
|
No |
Identifier associated with this track. |
url
|
string
|
No |
The Amazon Music URL for this track. |
mediaType
|
mediaType
|
No |
MediaType affiliated with this track. |
globalAsin
|
string
|
No |
Globally unique identifier for this track. |
localAsin
|
string
|
No |
musicTerritory localized identifier for this track. |
title
|
double
|
No |
The title of this track. |
shortTitle
|
string
|
No |
The shortened title of this track |
duration
|
double
|
No |
The duration of this track in seconds. |
release
|
Release
|
No |
Release date information relative to this track. |
isrc
|
string
|
No |
The ISRC code associated with this track. |
artists
|
Artist[]
|
No |
An array of artists associated with this track |
album
|
Album
|
No |
The album associated with this track |
musicTerritory
|
musicTerritory
|
No |
musicTerritory localized identifier for this track. |
market
|
Market
|
No |
Market this track is referenced from. |
availableMarkets
|
Market[]
|
No |
The list of markets this track is available in. |
eligibility
|
Eligibility[]
|
No |
The eligibility associated with this track. |
parentalSettings
|
ParentalSettings
|
No |
Parental settings associated with this track. |
previewUrl
|
string
|
No |
Sample playback URL for this track if supported. |
images
|
Image[]
|
No |
An array of images associated with this track. |
label
|
string
|
No |
Label associated with this track. |
dmid
|
string
|
No |
Unique internal identifier of this track. |
audioVideoTimestamps
|
AudioVideoTimestamps
|
No |
Timestamp mapping for each second between audio and video with confidence score |
User
Name |
Data Type |
Required |
Description |
id
|
string
|
Yes |
Identifier associated with this user. |
url
|
string
|
No |
The Amazon Music URL for this user. |
name
|
string
|
No |
The name of this user. |
images
|
Image[]
|
No |
Array of images associated with this user. |
tier
|
UserTier
|
No |
The subscription tier of this user |
visibility
|
VisibilityType
|
No |
The visibility of this user |
playbackVisibility
|
VisibilityType
|
No |
The playback visibility of this user |
playlists
|
Playlist Connection
|
No |
The playlists accociated with this user |
tracks
|
Track Connection
|
No |
The tracks accociated with this user |
podcastEpisodes
|
Podcast Episode Connection
|
No |
The podcast episodes accociated with this user |
followers
|
User Connection
|
No |
The followers accociated with this user |
followedUsers
|
User Connection
|
No |
The other users this user is following |
followedPlaylists
|
Playlist Connection
|
No |
The playlists this user is following |
recentTrackPlayback
|
Track Connection
|
No |
The recent tracks this user has played |
followedPodcastShows
|
Podcast Connection
|
No |
Podcast shows this user is following |
recentEntitiesPlayback
|
Entities Connection
|
No |
List of entities recently played by this user |
ViewView
Name |
Data Type |
Required |
Description |
id
|
string
|
Yes |
Identifier associated with this view. |
title
|
string
|
No |
The name of this view. |
entity
|
Entity
|
No |
The entity-type of this view (e.g. Artist). |
images
|
Image[]
|
No |
A background image. |
content
|
ViewContent
|
No |
List of entity groups with pagination tokens |
ViewContent
Name |
Data Type |
Required |
Description |
entityGroups
|
EntityGroup[]
|
Yes |
Array of EntityGroup objects |
nextPageToken
|
string
|
No |
A token to be used for pagination. |
EntityGroup
Name |
Data Type |
Required |
Description |
id
|
string
|
Yes |
Identifier associated with this container |
title
|
string
|
No |
Title of container |
viewType
|
ViewType
|
Yes |
A rendering type which determines the recommended layout of the container |
content
|
EntityGroupContent
|
Yes |
The list of entity groups with pagination tokens |
EntityGroupContent
Name |
Data Type |
Required |
Description |
entities
|
EntityGroup[]
|
Yes |
Array of EntityGroup objects |
nextPageToken
|
string
|
No |
A token to be used for pagination. |
ViewView
Name |
Data Type |
Required |
Description |
id
|
string
|
Yes |
Identifier associated with this view. |
title
|
string
|
No |
The name of this view. |
entity
|
Entity
|
No |
The entity-type of this view (e.g. Artist). |
images
|
Image[]
|
No |
A background image. |
content
|
ViewContent
|
No |
List of entity groups with pagination tokens |
ViewContent
Name |
Data Type |
Required |
Description |
entityGroups
|
EntityGroup[]
|
Yes |
Array of EntityGroup objects |
nextPageToken
|
string
|
No |
A token to be used for pagination. |
EntityGroup
Name |
Data Type |
Required |
Description |
id
|
string
|
Yes |
Identifier associated with this container |
title
|
string
|
No |
Title of container |
viewType
|
ViewType
|
Yes |
A rendering type which determines the recommended layout of the container |
content
|
EntityGroupContent
|
Yes |
The list of entity groups with pagination tokens |
EntityGroupContent
Name |
Data Type |
Required |
Description |
entities
|
EntityGroup[]
|
Yes |
Array of EntityGroup objects |
nextPageToken
|
string
|
No |
A token to be used for pagination. |
General Base Types
Connection
The Connection base type is a generalized form of a collection container for pageable lists of entities. These will be found as return values for functions returning lists such as Get Current User's Albums. Connections contain an array of the specialized type along with a count of the items and a PageInfo object used for pagination.
Name |
Data Type |
Required |
Description |
edges
|
Edge[]
|
Yes |
Array of Edges for the specialized object type |
edgeCount
|
double
|
No |
The count of items in the edge Array |
pageInfo
|
pageinfo
|
No |
Information used for Pagination |
Edges
An Array of Nodes. Nodes are a generalized base object of the entity returned in a Connection.
Name |
Data Type |
Required |
Description |
node
|
node
|
Yes |
Generalized base object of the entity returned in a Connection |
Node
A Node (also known as an Edge) is a generalized type for entity objects returned in pageable Connection lists. They typically contain a limited subset of data representing the type. It may be necessary to use GET
on the resource in question to get full details of the object.
Name |
Data Type |
Required |
Description |
id
|
string
|
Yes |
Key identifier for the specialised object |
cursor
|
string
|
No |
Used for pagination. Identifies the current position within a list |
Entity
Generalized type to describe entities. May have other properties depending on the specialized object.
Name |
Data Type |
Required |
Description |
id
|
string
|
No |
Identifier associated with this type. |
url
|
string
|
No |
The Amazon Music url for this entity. |
PageInfo
Information used for pagination.
Name |
Data Type |
Required |
Description |
hasNextPage
|
Boolean
|
Yes |
Flag indicating if the paginated result has a next page. |
token
|
string
|
No |
Token pointing to the next page. |
Response
The generic response type for all rerturned data within the API.
Name |
Data Type |
Required |
Description |
data
|
object
|
No |
The data returned from the query. Typically an array of entities or a response collection |
errors
|
map
|
No |
A collection of key-value pairs describing the error |
Response Collection
A generalized object for a returned collection. It is used in responses that return pageable lists. Trypically contains header information including the ID and name of the parent of the collection, along with Connections containing the lists of specialized returned objects.
Name |
Data Type |
Required |
Description |
[header type]
|
base object
|
No |
This header will be named after the reference or perent for this query, For example, it may be titled 'artist' for a list of albums related to that artist |
id
|
string
|
No |
The Amazon ID for this entity |
name
|
string
|
No |
The name of this entity |
[connection type]
|
connection
|
No |
The name of this connection object is based on the collection type returned. For example, it would be 'albums' if a list of albums is being returned |
Primitives
Action
Name |
Data Type |
Required |
Description |
isAllowed
|
bool
|
Yes |
Specifies whether an action is allowed (true or false). |
AudioVideoTimestamps
Name |
Data Type |
Required |
Description |
audioTimestamps
|
double[]
|
Yes |
An array of audio timestamps in seconds |
audioToVideoConfidence
|
double[]
|
Yes |
An array of confidence scores of the mapping between audio and video seconds |
videoTimestamps
|
double[]
|
Yes |
An array of video timestamps in seconds |
videoToAudioConfidence
|
double[]
|
Yes |
Confidence scores of the mapping between video and audio seconds |
Category
Name |
Data Type |
Required |
Description |
id
|
string
|
Yes |
Identifier associated with this category. |
url
|
string
|
No |
The Amazon Music url for this category. |
name
|
string
|
No |
The name of this category. |
images
|
Image[]
|
No |
Array of images associated with this category. |
albums
|
SearchAlbumResults
|
No |
A search result list of albums in this category. |
tracks
|
SearchTrackResults
|
No |
A search result list of tracks in this category. |
playlists
|
SearchPlaylistResults
|
No |
A search result list of playlists in this category. |
subcategories
|
Category[]
|
No |
An array of sub categories in this category. |
categoryType
|
CategoryType
|
No |
The category type of this category. |
Eligibility
Name |
Data Type |
Required |
Description |
isDownloadable
|
boolean
|
No |
Flag indicating if this asset is available for download. |
isPurchaseable
|
string
|
No |
Flag indicating if this asset is available for purchase. |
isPreviewable
|
boolean
|
No |
Flag indicating if this asset is previewable. |
isPrimeEligible
|
boolean
|
No |
Flag indicating if this asset is Prime eligible on retail website. |
Image
Name |
Data Type |
Required |
Description |
width
|
double
|
No |
Width of the image in pixels. |
height
|
double
|
No |
Height of the image in pixels. |
aspectRatio
|
double
|
No |
Aspect ratio of the image. |
url
|
string
|
Yes |
URL of the image. |
imageType
|
ImageType
|
Yes |
The type of image. Describes its intended use. |
description
|
string
|
No |
Description of the image. |
Market
Name |
Data Type |
Required |
Description |
id
|
string
|
Yes |
Two digit ISO 3166-1 country code. |
name
|
string
|
Yes |
Name of the country. |
musicTerritory
Name |
Data Type |
Required |
Description |
code
|
string
|
Yes |
Two digit ISO 3166-1 country code. |
territoryName
|
string
|
No |
Name of the country. |
ParentalSettings
Name |
Data Type |
Required |
Description |
isKidFriendly
|
Boolean
|
Yes |
Flag indicating if the content is kid friendly. |
hasExplicitLanguage
|
Boolean
|
Yes |
Flag indicating explicit content. |
Release
Name |
Data Type |
Required |
Description |
streetDate
|
string
|
No |
The date this asset became available. |
localOriginalReleaseDate
|
string
|
No |
The date this asset became available relative to its musicTerritory |
SaveTrackResponse
Name |
Data Type |
Required |
Description |
track
|
track
|
No |
Basic information about the track whose save state was changed |
saveState
|
string
|
No |
The save state of the track can be SAVED or REMOVED |
Enumerations
AlbumFieldType
Types used for searching albums
id |
asin |
artistId |
artistName |
categoryId |
name |
ArtistFieldType
Types used for searching artists
CategoryType
Enum
EntityType
Album |
Artist |
Category |
Playlist |
PodcastEpisode |
PodcastShow |
Track |
User |
ImageType
BACKGROUND |
PRIMARY |
PROFILE |
PlaylistSortBy
enum
NAME | Ascending by Playlist name |
LAST_MODIFIED_DATE | Ascending by Playlist last modified date |
FOLLOWERS | Descending by number of followers for the Playlist |
SearchPlaylistFieldType
Types used for searching playlists
id |
asin |
name |
artistId |
artistName |
categoryId |
trackId |
Selections
Types used for allowed selections in playParams
SortByType
Used for sorting search results
relevance |
release |
popularity |
TrackFieldType
Types used for searching tracks
id |
asin |
albumId |
albumName |
artistId |
artistName |
categoryId |
name |
isrc |
UserTier
The subscription tier for a customer
VisibilityType
ViewType
LIST |
GRID |
TABLE |
STACK |
TEXT |