Amazon Music Web API

Web API Search V1.0

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 meta-data about albums, artists, tracks, podcast shows, or podcast episodes.

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

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"
          }
        }
      ]
    }
  }
}