Sign In
Sign In

Amazon Music Device API

API Device

The Root Node

Users browse Amazon Music starting from the root node endpoint.

URL : https://music-api.amazon.com/

Method : GET

Auth required : YES

Performing an HTTP GET request against the root node will return a JSON document object containing a hierarchy of browsable nodes. Example JSON is shown below.

By starting at the root node, users can browse Amazon Music as a hierarchy of nested navigation nodes. As a best practice, we ask you to start at the root node and not sub-nodes, which are subject to change based on content availability and/or licensing.

A node containing three navigation nodesIn the figure above, the root node (Amazon Music) contains three items, one of which is labeled Prime Music. Prime Music is also a navigation node, containing three additional items, as shown in the figure. (Note: the actual service response is likely to differ from this example)

Representation of Nodes

There are two JSON object types used to define navigation nodes:

  • Navigation­Node­Summary: A navigation node summary provides only minimal information, such as the node title and a remote reference to the URI where the full description may be found
  • Navigation­Node­Description: The navigation node description provides complete information, including a full list of the items that belong to the node. Child nodes of a navigation node are defined using the Item­Description type. For items that are navigation nodes, the item description provides a local reference to a navigation node summary for that item.

All of these objects–navigation node summaries, navigation node descriptions, and item descriptions–are represented together using a Document object. The root node in the example above would be defined as the result member of the document with a structure like the one shown below (NOTE: Some portions omitted for brevity):

{
    "result": "#catalog_desc",
    "navigationNodeDescriptions": {
        "catalog_desc": {
            "summary": "#catalog_desc_summary",
            "items": ["#label_0_desc", "#label_1_desc", "#label_2_desc", ... ],
        }
    },
    "navigationNodeSummaries": {
        "label_0_summary": { "title": "Try Amazon Music Unlimited", "description": "upsell-banner/#upsell_banner" },
        "label_1_summary": { "title": "Playlists", "description": "catalog/playlists/#prime_playlists" },
        "label_2_summary": { "title": "Stations", "description": "catalog/stations/#prime_stations" },
        ...
        "catalog_desc_summary": { "title": "Browse", "description": "#catalog_desc" }
    },
    "itemDescriptions": {
        "label_0_desc": {
            "itemLabel": "Try Amazon Music Unlimited", "navigationNodeSummary": "#label_0_summary" ... },
        "label_1_desc": {
            "itemLabel": "Playlists", "navigationNodeSummary": "#label_1_summary", ... },
        "label_2_desc": {
            "itemLabel": "Stations", "navigationNodeSummary": "#label_2_summary", .... },
    },
}

One thing to point out from this example is that a navigation node description’s summary member is a local reference, but a navigation node summary’s description member may be a local reference, or it may be a remote reference. The consequence is that given a navigation node description, a client can always find the corresponding navigation node summary without making an additional HTTP request, but given a navigation node summary, a client may need to make an additional HTTP request to fetch the corresponding navigation node description. In this example, label_1_summary.description refers to a navigation node description available from a different URI. If it were a local reference, the description would be found under navigationNodeDescriptions.

Also, note that the root node specified by the result member may not be the first object listed in the document.

Interaction Example

The following sequence of steps illustrate how a client application should interact with Navigation Nodes:

  • When the application starts up (post LWA authentication), it should fetch the navigation node description of the root node by sending an HTTP GET request to an Amazon Music Web Service API endpoint domain. For example: https://music-api.amazon.com
  • The service will respond with a JSON document (NOTE: Some portions omitted for brevity):
{
    "result": "#catalog_desc",
    "navigationNodeDescriptions": {
        "catalog_desc": {
            "summary": "#catalog_desc_summary",
            "items": ["#label_0_desc", "#label_1_desc", "#label_2_desc", ... ],
        }
    },
    "navigationNodeSummaries": {
        "label_0_summary": { "title": "Try Amazon Music Unlimited", "description": "upsell-banner/#upsell_banner" },
        "label_1_summary": { "title": "Playlists", "description": "catalog/playlists/#prime_playlists" },
        "label_2_summary": { "title": "Stations", "description": "catalog/stations/#prime_stations" },
        ...
        "catalog_desc_summary": { "title": "Browse", "description": "#catalog_desc" }
    },
    "itemDescriptions": {
        "label_0_desc": {
            "itemLabel": "Try Amazon Music Unlimited", "navigationNodeSummary": "#label_0_summary" ... },
        "label_1_desc": {
            "itemLabel": "Playlists", "navigationNodeSummary": "#label_1_summary", ... },
        "label_2_desc": {
            "itemLabel": "Stations", "navigationNodeSummary": "#label_2_summary", .... },
    },
}
  • The application locates the top node’s navigation node description, navigation node summary, and list of item descriptions:
    • document.result is #catalog_desc, so the top node’s navigation node description can be found at document.navigationNodeDescriptions.catalog_desc.
    • document.navigationNodeDescriptions.catalog_desc.summary is #catalog_desc_summary, so the top node’s navigation node summary can be found at document.navigationNodeSummaries.catalog_desc_summary.
    • document.navigationNodeDescriptions.catalog_desc.items is an array of the values: #label_0_desc, #label_1_desc, etc. The respective item descriptions can be found at document.itemDescriptions.label_0_desc and document.itemDescriptions.label_1_desc. You can expect to receive several more sequentially numbered label items than are listed here.
  • The application presents the items (each labeled with its item­Label member) as a menu to the user. The application must display each item returned by the API, and not omit or exclude any returned content.

Suppose the user selects the Playlists item:

  • The application locates the navigation node summary and navigation node description for the Playlists item:

    • document.itemDescriptions.playlists_item.navigationNodeSummary is playlists_node_summary, so the navigation node summary can be found at document.navigationNodeSummaries.playlists_node_summary.
    • The application examines the value of the navigation node summary’s description member: catalog/playlists/ (a non-local URI). The application resolves it to an absolute URI, yielding https://music-api.amazon.com/catalog/playlists/#prime_playlists.
    • The application sends an HTTP GET request to this URI to fetch the navigation node description for Prime Playlists. The sequence begins again as shown above.

Paged Item Lists

Some nodes that represent very long lists (e.g., “All Songs”) are divided into pages for performance reasons. Each page is described by its own Navigation­Node­Description, but all pages are considered to be part of the same navigation node. Each page in a paged list provides references to the first, last, previous, and next pages, if they exist. Clients are encouraged to present paged lists in such a way that users do not perceive the page breaks. If that is not possible, clients should provide controls to allow users to manually navigate through paged lists.

Now that your client allows users to browse items, you will also want to allow them to search items. Click here to learn about search.