Amazon Music Web API
Web API Views Overview V1.0
The Views APIs
The Views APIs enable the listener to fluidly browse the Amazon Music catalog and their own libraries. They also surface content relevant to the listener, powered by recommendations based on their listening history.
Some Views endpoints provide multiple UI views for different categories of content. For instance, the Home View might return UI views of featured artists, top podcasts, recently played songs, etc. There are also specific View endpoints for playlists, stations, podcasts, artist details, and more.
Example of an Amazon Music homepage
Use views to build an interface for browsing the Amazon Music service. A typical use case for view-based browsing might go something like this:
The user starts on the home page. The client calls the Home View, which responds with views for sections such as featured artists, popular albums this week, new releases, DJ Mode stations, and so on. The user selects one of the specific artists shown. They are then taken to the view for that artist, which shows them new releases, top songs, related stations, etc. They click on the first top song and it begins playing.
The example above involves two endpoints: /views/home and /views/artist/{id}. The initial homepage view and the featured artist section both come from /views/home. Once the user has selected a specific artist, /views/artist/{id} should be called to continue the browsing experience.
Parsing the response object
The Views APIs responses contain collections of objects - called entityGroups - that contain entityGroup objects.
An entityGroup represents a UI element displaying some category of entities from the Amazon Music catalog. For instance, an entityGroup might contain several artists, or several albums, or a mix of both types of entity.
Each entityGroup has a viewType which will specify the appropriate layout. For example, the Home view might have an entityGroup called "Featured This Week" which contains entities of the playlist type. "Featured This Week" might have viewType LIST, which indicates that those playlists should be displayed as a horizontal scrolling list. See the display formatting section for a complete list of viewTypes with an explanation for each.
Each entityGroup has an entities collection. Entities in the collection may be of different kinds or all of the same kind, depending on the entityGroup. Entities in the entities collections will always be views, but they may sometimes also be playables (see below for the definition of a playable). A view will only drill down one level, so if an entity should have its own sub-entities, it may require a separate call to the appropriate view to retrieve them. For instance, the Home view might retrieve the playlists in "Featured This Week." But retrieving the tracks in one of those playlists would require an API call to the Playlist view.
Here is an example response from calling /views/home, omitting lines that do not pertain directly to entityGroups and entities:
{
"data": {
"_type": "View",
"id": "home",
"images": [],
"content": {
"_type": "ViewContent",
"nextPageToken": "a9634283-7988-428a-a5c7-1d17d61f388e",
"entityGroups": [{
"_type": "EntityGroup",
"id": "mp3-subscription-gateway_mp3YourHeaviestListeningStrategy",
"title": "Your Frequent Plays",
"viewType": "LIST",
"content": {
"_type": "EntityGroupContent",
"nextPageToken": "75edff21-5b28-43f9-8272-f533182fd896",
"entities": [{
"_type": "Album",
"id": "B0BBB43TGW",
"title": "Never Before Seen, Never Again Found [Explicit]",
"artists": [{
"id": "B07VPCLT49",
"name": "Arm's Length"
}],
"images": [{
"url": "https://..."
}],
"playParams": {
"id": "mrn:1.0:catalog:album:asin:B0BBB43TGW?territory=US",
"selections": [
"PLAY",
"SHUFFLE",
"STATION"
]
}
},
{
"_type": "Artist",
"id": "B07VPCLT49",
"images": [
{
"url": "https://..."
}
],
"name": "Arm's Length",
"playParams": {
"id": "mrn:1.0:catalog:artist:asin:B07VPCLT49?territory=US",
"selections": [
"PLAY",
"SHUFFLE",
"STATION"
]
}
},
...
},
...
]
}
}
}
In the above example, the home.content object contains an entityGroups collection which holds the EntityGroup object "Your Frequent Plays" with a viewType of LIST. "Your Frequent Plays" in turn contains its own entities collection which includes both an album and an artist, two separate entity types. The album is both a container of tracks and a playable. Entities that are playables such as this one will have a playParams object. For more information on the playParams object, see here.
The customer might wish to see all the songs in the album, in which case a call must be made to the album details view with the album's ID. Or they might wish to begin playing the playlist immediately. The client has the flexibility to present the options that work best for its interface.
Pagination
Pagination for views works slightly differently than pagination for other Amazon Music Web APIs.
Because some View APIs return multiple entity groups, an entity-group-id must also be provided in pagination calls to specify for which group an additional page is being requested. If there are not multiple groups, pagination may proceed as usual by providing a cursor parameter obtained from the nextPageToken of the current page. If there is no nextPageToken then no further pages are available.
Example of standard view pagination
<base url>/v1/views/home?cursor=<nextPageToken>
Example of entity group pagination
<base url>/v1/views/home/<entity-group-id>?cursor=<nextPageToken>
See All
It is recommended that each group or view displayed to the user include a 'See All' button. When the user selects 'See All' they should be shown an expanded version of the relevant view, listing all entities or at least the first page.
To retrieve a 'See All' for a specific entity group, call the relevant View endpoint again with id as a path parameter. Use the ID of the entity group you wish to retrieve as the value. The API response will then contain only results for the specified entity group.
Example
<base url>/v1/views/home/<entity-group-id>
Display formatting
If an entity is a view, it has a viewType specifying the layout that should be displayed to the end user.
Sometimes a view needs to display some combination of artists, albums, stations, playlists, and even individual songs. These will be referred to below as 'entities'. Some views may need to display multiple entities together. Others display only a single type, or single entity.
List
Lists should be displayed as a single horizontal row of images with a short label beneath each.
Example use case: Playlists in a view with multiple entities.
Grid
Grids should be displayed as a two-dimensional matrix of images with a short label beneath each.
Example use case: Albums in a single-entity view.
Table
Tables should be displayed in multiple columns of images with accompanying text to the right of each image.
Example use case: Songs in a view with multiple entities.
Stack
Stacks should be displayed as vertical lists of images with a longer text blurb to the right of each image.
Example use case: Podcasts in a single entity view.
Message
A message should be displayed as a simple block of text with no accompanying image.
Example use case: Empty content of the My Library page with message informing the user that they can add songs to their library to view them here.
