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

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

Example: https://music-api.amazon.com/flat_search/?keywords=pop%20music&type=catalog_track&type=library_track

Valid Type Values

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": {
    ...
}

1. The first step is for the client to get the value of the result field.
   1. In this example, that value is #search_desc.
   2. The search_desc object will be the starting point from which the client should build a tree of the results.
2. Retrieve the search_desc object from the navigationNodeDescriptions 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"
        ],
   }
   

   1. This is the root node in the tree of search results.
   2. 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’s itemDescriptions collection.
   3. The client should start with the first item, #catalog_albums_label_0_desc.
3. Retrieve catalog_albums_label_0_desc from the itemDescriptions 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,
            },
    }
   

   1. This is the albums results node under our root results node.
   2. This item has the label “Albums in Amazon Music.” The client should display that along with the accompanying image.
   3. The playable property for this item is null. This item is a search results category and cannot be played.
   4. The client needs to display any search results that should be nested under this node, i.e., search results in the ‘album’ category.
   5. The summary URI is #catalog_albums_search_desc_summary. The client should retrieve this summary for more information.
4. From the navigationNodeSummaries collection, retrieve catalog_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
        },
    }
   

   1. 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.
5. From the navigationNodeDescriptions collection, retrieve catalog_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
            }
        },
    }
   

   1. This object has an items collection, which should contain the sub-nodes for the client to display. In this case, the items 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.
   2. The first item is #catalog_album_0_desc.
6. Retrieve catalog_album_0_desc from the response’s itemDescriptions 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/"
            },
        },
        ...
    }
   

   1. 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 the Playables collection.
   2. The itemLabel is “Polygon.” The client should display this as the name of this album.
   3. From the artist object has the name “Battle Tapes.” The client should display this as the name of the artist.
   4. 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.
7. Repeat step 6 for each item in catalog_albums_search_desc’s item collection.
8. Return to the search_desc object from step 2. Repeat steps 2 through 7 for each item in its items 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.