Amazon Music Web API

Web API Search V1.0

Search

Search Amazon Music catalog meta-data about albums, artists, tracks, podcast shows, or podcast episodes.

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

id
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

id
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

id
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

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