Amazon Music Device API
Search
There are two search endpoints available. The regular Search endpoint returns results broken into categories. The Flat Search endpoint simply returns a list of matching tracks.
Search Endpoint
The Search endpoint will return search results broken into categories. For instance: search results from the Amazon Music catalog where the track name contains the keyword, results where the album name contains the keyword, results where the artist name contains the keyword, results from the user’s library, etc. These are organized into separate buckets.
URL : /search/?keywords=<XXX>
Method : GET
Auth required : YES
Query Parameters
Name | Data Type | Required | Description |
---|---|---|---|
keywords | string | Yes | The keyword string to search for |
type | string | No | The specific type(s) of catalog or library items to search. See table below for a list of types. |
hasExplicit | bool | No | Allow explicit songs in the results |
count | int | No | Number of results to return per category |
Example: https://music-api.amazon.com/search/?keywords=
hello
Flat Search Endpoint
The Search endpoint will return search results as a simple list of tracks without categories.
URL : /flat_search/?keywords=<XXX>
Method : GET
Auth required : YES
Query Parameters
Name | Data Type | Required | Description |
---|---|---|---|
keywords | string | Yes | The keyword string to search for |
type | string | No | The specific type(s) of catalog or library items to search. See table below for a list of types. |
hasExplicit | bool | No | Allow explicit songs in the results |
count | int | No | Number of results to return |
Valid Type Values
Type | Catalog | ||
---|---|---|---|
catalog_album | Amazon Music | ||
catalog_artist | Amazon Music | ||
catalog_playlist | Amazon Music | ||
catalog_station | Amazon Music | ||
catalog_track | Amazon Music | ||
library_album | My Music | ||
library_artist | My Music | ||
library_playlist | My Music | ||
library_track | My Music | ||
catalog | Amazon Music | ||
library | My Music |
Search for all types of music
Use the keyword
parameter to submit search terms entered by the user. The search
endpoint returns a limited number of items for each category with a “See More…” link to retrieve additional results. Currently, if there are seven (or fewer) results for a category, it will return all seven (or fewer) in the initial results. If there are more than seven, it returns five items and the “See More” link. To submit multiple keywords, use %20
as space in between keywords. All special characters should be URL encoded.
The API uses the displayTag
element in navigationNodeDescriptions
for search results as a guide for the UX. The value of the top-level search_desc
navigation node’s displayTag
is “TAB,” while Catalog Search and Library Search navigation nodes displayTag
value is “INLINE.”
You should display the navigation nodes within the search_desc (Catalog Search and Library Search) as two tabs, and the child nodes within Catalog Search and Library Search should be displayed inline under each tab with section headers as labels. A rough mock-up of the intended UX is below. Depending on your client, there may be other conceptually similar ways of grouping items that are more appropriate. If you are not able to construct a UX display along these lines and simply ignore the displayTag
member, then the results will appear as nested nodes just as the rest of the Amazon Music does. We strongly recommend use of displayTag
to support a good UX here; if this is not possible in your platform, please contact the Amazon Music team to discuss potential solutions.
Searching for Specific Types of Music
Use the type
query parameter to specify one or more specific categories to search. To search more than one category, simply append another type parameter. The Device API supports several types of music categories:
- Amazon Music types:
- catalog_album
- catalog_artist
- catalog_playlist
- catalog_station
- catalog_track
- My Music types:
- library_album
- library_artist
- library_playlist
- library_track
- Top Hit types:
- top_hit
- top_hit_album
- top_hit _artist
- top_hit _playlist
- top_hit _station
- top_hit _track
- Additional types:
- catalog
- library
Parsing search results
The format of the JSON returned by a search will look very similar to that returned by browsing navigation nodes. The following example will demonstrate how the client should parse the JSON search results.
Suppose the client makes a Flat Search for the keywords “battle tapes,” like this:
URL: https://music-api.amazon.com/flat_search/?keywords=battle tapes&hasExplicit=true
The Flat Search endpoint will return JSON results similar to this:
{
"result": "#search_desc",
"playables": {
"catalog_album_playable_0": {
...
}
- The first step is for the client to get the value of the
result
field.- In this example, that value is
#search_desc
. - The
search_desc
object will be the starting point from which the client should build a tree of the results.
- In this example, that value is
- Retrieve the
search_desc
object from thenavigationNodeDescriptions
collection. It will look like this:"search_desc": { "displayTag": [ "INLINE" ], "summary": "#search_desc_summary", "items": [ "#catalog_albums_label_0_desc", "#catalog_artists_label_1_desc", "#catalog_playlists_label_2_desc", "#catalog_tracks_label_3_desc" ], }
- This is the root node in the tree of search results.
- This object has a collection of
items
. Each one represents a category of search results. Each one must be retrieved in turn from the response’sitemDescriptions
collection. - The client should start with the first item,
#catalog_albums_label_0_desc
.
- Retrieve
catalog_albums_label_0_desc
from theitemDescriptions
collection. It should look similar to this:"itemDescriptions": { ... "catalog_albums_label_0_desc": { "itemLabel": "Albums in Amazon Music", "image": { "uri": "https://images-na.ssl-images-amazon.com/images/G/01/redbird/blue_icon_albums.png", "contentType": "image/png", "width": 488, "height": 488, "isIcon": true }, "navigationNodeSummary": "#catalog_albums_search_desc_summary", "playable": null, "artist": null, }, }
- This is the albums results node under our root results node.
- This item has the
label
“Albums in Amazon Music.” The client should display that along with the accompanying image. - The
playable
property for this item isnull
. This item is a search results category and cannot be played. - The client needs to display any search results that should be nested under this node, i.e., search results in the ‘album’ category.
- The summary URI is
#catalog_albums_search_desc_summary
. The client should retrieve this summary for more information.
- From the
navigationNodeSummaries
collection, retrievecatalog_albums_search_desc_summary
. It should look like this:"navigationNodeSummaries": { ... "catalog_albums_search_desc_summary": { "title": "Albums in Amazon Music", "description": "#catalog_albums_search_desc", "numItemsOfInterest": null, "playable": null }, }
- This summary doesn’t have much information, but it does have a
description,
which is a URI pointing towards the more helpful navigationNodeDescription for this object. The URI for this node is#catalog_albums_search_desc
.
- This summary doesn’t have much information, but it does have a
- From the
navigationNodeDescriptions
collection, retrievecatalog_albums_search_desc
."navigationNodeDescriptions": { "catalog_albums_search_desc": { "summary": "#catalog_albums_search_desc_summary", "items": [ "#catalog_album_0_desc", "#catalog_album_1_desc", "#catalog_album_2_desc", "#catalog_album_3_desc", "#catalog_album_4_desc", "#catalog_album_5_desc", "#catalog_album_6_desc", "#catalog_albums_see_more_label_7_desc" ], "image": { "uri": "https://images-na.ssl-images-amazon.com/images/G/01/redbird/blue_icon_albums.png", "contentType": "image/png", "width": 488, "height": 488, "isIcon": true } }, }
- This object has an
items
collection, which should contain the sub-nodes for the client to display. In this case, theitems
collection includes 7 albums and a “See more…” link as members. The client should retrieve each member item in turn and process it; however, for this example we will only handle the first item. - The first item is
#catalog_album_0_desc
.
- This object has an
- Retrieve
catalog_album_0_desc
from the response’sitemDescriptions
collection. It should appear similar to this:"itemDescriptions": { "catalog_album_0_desc": { "itemLabel": "Polygon", "image": { "uri": "https://m.media-amazon.com/images/I/61-bxfYCvKL.jpg", "contentType": "image/jpeg", "width": 488, "height": 488, "isIcon": false }, "navigationNodeSummary": "#catalog_album_0_summary", "playable": "#catalog_album_playable_0", "artist": { "name": "Battle Tapes", "asin": "B007U2KQNM", "uri": "../catalog/artists/B007U2KQNM/" }, }, ... }
- The
playable
property for this item is not null, so playback can be initiated on this item. If the user selects the item, the client should retrieve the referenced object from thePlayables
collection. - The
itemLabel
is “Polygon.” The client should display this as the name of this album. - From the
artist
object has the name “Battle Tapes.” The client should display this as the name of the artist. - The image object provides album art. The request header
X-Amz-Music-Images-Shrink
can be used to specify the maximum dimensions of an image (see Request Headers for more details) for the client.
- The
- Repeat step 6 for each item in
catalog_albums_search_desc
’s item collection. - Return to the
search_desc
object from step 2. Repeat steps 2 through 7 for each item in itsitems
collection.
This ends the example.
Page Size Header
The x-amzn-page-size
header specifies the approximate upper bound of results in a response. For example, if x-amzn-page-size: 25
is provided, and no type
parameter is specified, a response may provide three items in each of nine categories: two music items and a “See more” navigation node reference for each one. If the number of items in one category is greater than or equals 49, the “See more” link will not be provided, because the current “See more” link only supports a maximum of 50 items for each category. Pagination of more results is expected to be added. Please support a mix of navigation nodes and playables, as described in other sections.
Note that when you provide a x-amzn-page-size
header when accessing the “See more” link from the search result, the items inside “See more” link will approximately match the page size provided, and no “See more” link will be contained inside a “See more” link. If no page size is provided, the “See more” link will contain a default number of items. The default size may change without warning.
Some examples:
https://music-api.amazon.com/flat_search/?keywords=<XXX>&type=catalog_track&type=library_track
Header: x-amzn-page-size: 25
https://music-api.amazon.com/flat_search/?keywords=<XXX>&type=catalog_track
Header: x-amzn-page-size: 50
https://music-api.amazon.com/flat_search/?keywords=<XXX>&type=catalog_track&type=library_track
Search for Top Hits
Besides searching the catalog and library, you can also search Amazon Music’s Top Hits. This allows the customer to see the top hits for the given search keywords. The top hit results would contain the most relevant search result from each of the Amazon Music types (catalog_album, catalog_artist, catalog_playlist, catalog_station, catalog_track). The maximum number of the top hit results is 5. The structure of the search results is shown below. Please contact the Amazon Music team to enable the top hit feature for your platform.
Some API call examples:
Response with top results only:
https://music-api.amazon.com/search/?keywords=<XXX>&type=top_hit
Response with catalog only:
https://music-api.amazon.com/search/?keywords=<XXX>&type=catalog
Response with library only:
https://music-api.amazon.com/search/?keywords=<XXX>&type=library
On clients with speedy connections, the UX may be enhanced by serving auto-completed suggestions as they type in the search box. Click here to learn more about search suggestions.