Amazon Music Web API

Web API Search V1.0

Important: These Amazon Music APIs are currently in a closed Beta. To join the waitlist, select 'Music Developers' in the contact us form here.

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.

Search

Search Amazon Music catalog data about albums, artists, tracks, podcast shows, and podcast episodes.

Search All
Search Tracks
Search Albums
Search Artists
Search Podcast Shows
Search Podcast Episodes
Search Playlists

Search All

GET

/v1/search

Search for a keyword or lyrics across all categories of the Amazon Music catalog (artists, albums, playlists, podcasts, stations, etc). The search results returned are auto-corrected and ranked based on relevance.

The response returns an array of data objects. Each item has an 'EntityGroups' collections which is a collection of individual EntityGroup objects, which represent different categories of search results. Results might include, for example, entities for the categories 'Top hits,' 'Artists,' 'Albums,' 'Podcasts,' and more. Each of these entities will contain a content collection with entities that represents individual items in that category. For example, a search for 'beck' might include results for both 'Beck' and 'Jeff Beck' as entities under the 'Artist' EntityGroup.

The first category returned is always 'Top hits'. These are the items determined by the algorithm to have the highest relevance to the search.

Query Parameters

Name	Data Type	Required	Description
query	string	Yes	The query text to search against. The input string needs to be non-empty.
limit	number	No	The maximum number of entities to return per type (default: 10). Minimum of 1.

Example

curl --request GET '<base url>/v1/search?query=weekend&limit=10' \
--header 'Authorization: Bearer <your auth token>' \

Responses

An array of Amazon Music response objects containing a response collection of top results for this user.

For malformed requests, such as an empty query string, this endpoint will return a 400 response.

Example

(Some lines omitted for brevity)

{
   "data": [
      {
         "_type": "View",
         "id": "catalog",
         "title": "Catalog Data",
         "content": {
            "_type": "ViewContent",
            "entityGroups": [
               {
                  "_type": "EntityGroup",
                  "id": "topHits",
                  "title": "Top Hits",
                  "viewType": "LIST",
                  "content": {
                     "_type": "EntityGroupContent"
                     "entities": [
                        {
                           "_type": "Artist",
                           "id": "B00G9Y64K6",
                           "name": "The Weeknd",
                           ...
                        },
                        {
                           "_type": "Track",
                           "id": "B0135WBIIW",
                           "title": "Weekend (feat. Miguel) [Explicit]",
                           ...
                        },
                        {
                           "_type": "Album",
                           "id": "B0135WAZD6",
                           "title": "GO:OD AM [Explicit]",
                           ...
                        },
                        ...
                     ],
                     ...
                  }
               },
               {
                  "_type": "EntityGroup",
                  "id": "artists",
                  "title": "Artists",
                  "viewType": "LIST",
                  "content": {
                     "_type": "EntityGroupContent"
                     "entities": [
                        {
                           "_type": "Artist",
                           "id": "B00G9Y64K6",
                           "name": "The Weeknd",
                           ...
                        },
                        {
                           "_type": "Artist",
                           "id": "B000TOS0V8",
                           "name": "Vampire Weekend",
                           ...
                        },
                        ...
                     ],
                     ...
                  }
               },
               {
                  "_type": "EntityGroup",
                  "id": "tracks",
                  "title": "Tracks",
                  "viewType": "LIST",
                  "content": {
                     "_type": "EntityGroupContent"
                     "entities": [
                        {
                           "_type": "Track",
                           "id": "B0135WBIIW",
                           "title": "Weekend (feat. Miguel) [Explicit]",
                           ...
                        },
                        {
                           "_type": "Track",
                           "id": "B084WKYYC3",
                           "title": "Blinding Lights",
                           ...
                        },
                        {
                           "_type": "Track",
                           "id": "B01LXAA72R",
                           "title": "Die For You",
                           ...
                        },
                        {
                           "_type": "Track",
                           "id": "B014DIXF0G",
                           "title": "The Hills [Explicit]",
                           ...
                        },
                        ...
                     ],
                     ...
                  }
               },
               ...
            ]
         }
      }
   ]
}

Search Tracks

POST

/search/tracks

Authorization Scope: [music::catalog]

Search the Amazon Music catalog meta-data for tracks based on search filters. Optional parameters can be used to limit the number of tracks returned.

Learn more about pagination.

Body Parameters

Name	Data Type	Required	Description
searchFilters	objects[]	Yes	A set of search filters in the format (field, query) to narrow the search results.
searchFilters.field	TrackFieldType	No	The field to search against. If none is specified, the search is treated as a match query.
searchFilters.query	string	Yes	The query text to search against.
limit	number	No	The maximum number of tracks to return (default: 100). Minimum of 1, maximum of 100.
token	string	No	The cursor/token for the page to continue pagination results from.
sortBy	string	No	The criteria by which the results should be sorted, accepted values: 'relevance' \| 'release' \| 'popularity' \| 'name'

TrackFieldType

enum

asin

albumId

albumName

artistId

artistName

categoryId

name

isrc

Example

curl --request POST '<baseURL>/v1/search/tracks' \
--header 'x-api-key: <your security profile ID>' \
--header 'Authorization: Bearer <your auth token>' \
--header 'Content-Type: application/json' \
--data '{
  "searchFilters": [
    {
      "field": "name",
      "query": "soja"
    }
  ],
  "limit": 2,
  "sortBy": "relevance"
}

Response

Amazon Music response object containing the search results:

Name	Data Type	Required	Description
searchTracks	Response	No	The results of the search

Example

{
  "data": {
    "searchTracks": {
      "pageInfo": {
        "hasNextPage": true,
        "token": "tztok-v2_iosmAqq9RWIFJZXCZvgM5OPd3xDn_Kt4pzA5_RnGHW4NGN7vEHQFjGfoqpdN1_wa"
      },
      "edgeCount": 2,
      "edges": [
        {
          "node": {
            "id": "B08G9TMYCZ",
            "title": "Cold",
            "url": "https://music.amazon.com/albums/B08GBBC5MV/?trackAsin=B08G9TMYCZ"
          }
        },
        {
          "node": {
            "id": "B00136J9FM",
            "title": "Cold",
            "url": "https://music.amazon.com/albums/B00136Q4S2/?trackAsin=B00136J9FM"
          }
        }
      ]
    }
  }
}

Search Albums

POST

/search/albums

Authorization Scope: [music::catalog]

Search the Amazon Music catalog meta-data for albums based on search filters. Optional parameters can be used to limit the number of albums returned.

Learn more about pagination.

Body Parameters

Name	Data Type	Required	Description
searchFilters	objects[]	Yes	A set of search filters in the format (field, query) to narrow the search results.
searchFilters.field	AlbumFieldType	No	The field to search against. If none is specified, the search is treated as a match query.
searchFilters.query	string	Yes	The query text to search against.
limit	number	No	The maximum number of albums to return (default: 100). Minimum of 1, maximum of 100.
token	string	No	The cursor/token for the page to continue pagination results from.
sortBy	string	No	The criteria by which the results should be sorted, accepted values: 'relevance' \| 'release' \| 'popularity' \| 'name'

AlbumFieldType

enum

asin

artistId

artistName

categoryId

name

Example

curl --request POST '<baseURL>/v1/search/albums' \
--header 'x-api-key: <your security profile ID>' \
--header 'Authorization: Bearer <your auth token>' \
--header 'Content-Type: application/json' \
--data '{
  "searchFilters": [
    {
      "field": "name",
      "query": "Animals"
    }
  ],
  "limit": 2,
  "sortBy": "relevance"
}

Response

Amazon Music response object containing:

Name	Data Type	Required	Description
searchAlbums	Response	No	The results of the search

Example

{
  "data": {
    "searchAlbums": {
      "pageInfo": {
        "hasNextPage": true,
        "token": "tztok-v2_yDSNVKX4qpd-k5g2XEe2TjhNXALKYbUaxlHmIV7BfzLQ2vKC_V9aPF6c-ixDOkYv"
      },
      "edgeCount": 2,
      "edges": [
        {
          "node": {
            "id": "B019HKKIV4",
            "title": "Animals [Explicit]",
            "shortTitle": "Animals",
            "duration": 2498,
            "url": "https://music.amazon.com/albums/B019HKKIV4"
          }
        },
        {
          "node": {
            "id": "B0B52C5PKM",
            "title": "Animals (2018 Remix) [Explicit]",
            "shortTitle": "Animals",
            "duration": 2498,
            "url": "https://music.amazon.com/albums/B0B52C5PKM"
          }
        }
      ]
    }
  }
}

Search Artists

POST

/search/artists

Authorization Scope: [music::catalog]

Search the Amazon Music catalog meta-data for artists based on search filters. Optional parameters can be used to limit the number of artists returned.

Learn more about pagination.

Body Parameters

Name	Data Type	Required	Description
searchFilters	objects[]	Yes	A set of search filters in the format (field, query) to narrow the search results.
searchFilters.field	ArtistFieldType	No	The field to search against. If none is specified, the search is treated as a match query.
searchFilters.query	string	Yes	The query text to search against.
limit	number	No	The maximum number of artists to return (default: 100). Minimum of 1, maximum of 100.
token	string	No	The cursor/token for the page to continue pagination results from.
sortBy	string	No	The criteria by which the results should be sorted, accepted values: 'relevance' \| 'release' \| 'popularity' \| 'name'

ArtistFieldType

enum

asin

name

Example

curl --request POST '<baseURL>/v1/search/artists' \
--header 'x-api-key: <your security profile ID>' \
--header 'Authorization: Bearer <your auth token>' \
--header 'Content-Type: application/json' \
--data '{
  "searchFilters": [
    {
      "field": "name",
      "query": "soja"
    }
  ],
  "limit": 1,
  "sortBy": "relevance"
}

Response

Amazon Music response object containing:

Name	Data Type	Required	Description
searchArtists	Response	No	The results of the search

Example

{
  "data": {
    "searchArtists": {
      "pageInfo": {
        "hasNextPage": true,
        "token": "tztok-v2_yDSNVKX4qpcJP1qqK8Cky9ICuak1PN4fYdr4Lz3j3nU8NOKn8Zd9N_DqjsnkW9pk"
      },
      "edgeCount": 1,
      "edges": [
        {
          "node": {
            "id": "B000QJRL7A",
            "name": "soja",
            "url": "https://music.amazon.com/artists/B000QJRL7A"
          }
        }
      ]
    }
  }
}

Search Podcast Shows

POST

/search/podcasts/shows

Authorization Scope: [music::catalog]

Search the Amazon Music catalog meta-data for podcast shows based on search filters. Optional parameters can be used to limit the number of podcasts returned.

Learn more about pagination.

Body Parameters

Name	Data Type	Required	Description
searchFilters	objects[]	Yes	A set of search filters in the format (field, query) to narrow the search results.
searchFilters.field	string	No	The field to search against. If none is specified, the search is treated as a match query.
searchFilters.query	string	Yes	The query text to search against.
limit	number	No	The maximum number of podcast shows to return (default: 100). Minimum of 1, maximum of 100.
token	string	No	The cursor/token for the page to continue pagination results from.
sortBy	string	No	The criteria by which the results should be sorted, accepted values: 'relevance' \| 'release' \| 'popularity' \| 'name'

Example

{
  "searchFilters": [
    {
      "field": "id",
      "query": "90c65aee-3db8-4bd1-bf28-42a85342bfe7"
    }
  ],
  "limit": 3,
  "sortBy": "relevance"
}

Example

curl --request POST '<baseURL>/v1/search/albums' \
--header 'x-api-key: <your security profile ID>' \
--header 'Authorization: Bearer <your auth token>' \
--header 'Content-Type: application/json' \
--data '{
  "searchFilters": [
    {
      "field": "name",
      "query": "Animals"
    }
  ],
  "limit": 2,
  "sortBy": "relevance"
}'

Response

Amazon Music response object containing:

Name	Data Type	Required	Description
searchPodcasts	Response	No	The results of the search

Example

{
  "data": {
    "searchPodcastShows": {
      "pageInfo": {
        "hasNextPage": true,
        "token": "tztok-v2_xnGPgD04XVHRLsoILs6prr5a13rVRvNw_OopVVXS-eYDRZuOD2xD0hNkIRkBrzNkWEAGxzPKtt4"
      },
      "edgeCount": 1,
      "edges": [
        {
          "node": {
            "id": "90c65aee-3db8-4bd1-bf28-42a85342bfe7",
            "title": "Cold",
            "url": "https://music.amazon.com/podcasts/90c65aee-3db8-4bd1-bf28-42a85342bfe7/Cold"
          }
        }
      ]
    }
  }
}

Search Podcast Episodes

POST

/search/podcasts/episodes

Authorization Scope: [music::catalog]

Search the Amazon Music catalog meta-data for podcast episodes based on search filters. Optional parameters can be used to limit the number of episodes returned.

Learn more about pagination.

Body Parameters

Name	Data Type	Required	Description
searchFilters	objects[]	Yes	A set of search filters in the format (field, query) to narrow the search results.
searchFilters.field	string	No	The field to search against. If none is specified, the search is treated as a match query.
searchFilters.query	string	Yes	The query text to search against.
limit	number	No	The maximum number of podcast episodes to return (default: 100). Minimum of 1, maximum of 100.
token	string	No	The cursor/token for the page to continue pagination results from.
sortBy	string	No	The criteria by which the results should be sorted, accepted values: 'relevance' \| 'release' \| 'popularity' \| 'name'

Example

curl --request POST '<baseURL>/v1/search/podcasts/episodes' \
--header 'x-api-key: <your security profile ID>' \
--header 'Authorization: Bearer <your auth token>' \
--header 'Content-Type: application/json' \
--data '{
  "searchFilters": [
    {
      "field": "id",
      "query": "7e39a988-6508-4171-ae11-854b1d480145"
    }
  ],
  "limit": 3,
  "sortBy": "relevance"
}

Response

Amazon Music response object containing:

Name	Data Type	Required	Description
searchPodcastEpisodes	Response	No	The results of the search

Example

{
  "data": {
    "searchPodcastEpisodes": {
      "pageInfo": {
        "hasNextPage": true,
        "token": "tztok-v2_xnGPgD04XVFj8tvPpxudssQWh0YKmbTl5b1gw4VhJnIfP9LjmuaUAliBUYyxmEJTHzlbWcxEpAU"
      },
      "edgeCount": 1,
      "edges": [
        {
          "node": {
            "id": "7e39a988-6508-4171-ae11-854b1d480145",
            "title": "Bonus Episode 2: Marshal Misdirection",
            "url": "https://music.amazon.com/podcasts/90c65aee-3db8-4bd1-bf28-42a85342bfe7/episodes/7e39a988-6508-4171-ae11-854b1d480145/ColdBonus-Episode 2: Marshal Misdirection"
          }
        }
      ]
    }
  }
}

Search Playlists

POST

/search/playlists

Authorization Scope: [music::catalog]

Search the Amazon Music catalog meta-data for playlists based on search filters. Optional parameters can be used to limit the number of playlists returned.

Learn more about pagination.

Body Parameters

Name	Data Type	Required	Description
searchFilters	objects[]	Yes	A set of search filters in the format (field, query) to narrow the search results.
searchFilters.field	SearchPlaylistFieldType	No	The field to search against. If none is specified, the search is treated as a match query.
searchFilters.query	string	Yes	The query text to search against.
limit	number	No	The maximum number of playlists to return (default: 100). Minimum of 1, maximum of 100.
token	string	No	The cursor/token for the page to continue pagination results from.
sortBy	string	No	The criteria by which the results should be sorted, accepted values: 'relevance' \| 'release' \| 'popularity' \| 'name'

SearchPlaylistFieldType

enum

asin

name

artistId

artistName

categoryId

trackId

Example

curl --request POST '<baseURL>/v1/search/playlists' \
--header 'x-api-key: <your security profile ID>' \
--header 'Authorization: Bearer <your auth token>' \
--header 'Content-Type: application/json' \
--data '{
  "searchFilters": [
    {
      "field": "name",
      "query": "music"
    }
  ],
  "limit": 3,
  "sortBy": "relevance"
}

Response

Amazon Music response object containing:

Name	Data Type	Required	Description
searchPlaylists	Response	No	The results of the search

Example

{
  "data": {
    "searchPlaylists": {
      "pageInfo": {
        "hasNextPage": true,
        "token": "tztok-v2_iosmAqq9RWIFJZXCZvgM5OPd3xDn_Kt4pzA5_RnGHW4NGN7vEHQFjGfoqpdN1_wa"
      },
      "edgeCount": 3,
      "edges": [
        {
          "node": {
            "id": "B097S46ST7",
            "title": "Cool Jazz",
            "curator": {
              "id": "",
              "name": "Amazon's Music Experts"
            },
            "trackCount": 60,
            "duration": 17698,
            "url": "https://music.amazon.com/playlists/B097S46ST7"
          }
        },
        {
          "node": {
            "id": "B00JEQPLIC",
            "title": "Christmas Classics",
            "curator": {
              "id": "",
              "name": "Amazon's Music Experts"
            },
            "trackCount": 30,
            "duration": 4800,
            "url": "https://music.amazon.com/playlists/B00JEQPLIC"
          }
        },
        {
          "node": {
            "id": "B00LADLMR6",
            "title": "Greatest Christmas Songs",
            "curator": {
              "id": "",
              "name": "Amazon's Music Experts"
            },
            "trackCount": 100,
            "duration": 19240,
            "url": "https://music.amazon.com/playlists/B00LADLMR6"
          }
        }
      ]
    }
  }
}