Amazon Music Web API
Web API Overview V1.0
Amazon Music Web API
The Amazon Music Web API is a new, simplified API allowing quick retrieval of meta-data about albums, tracks, artists, playlists, podcasts, and more from the Amazon Music catalog’s millions of songs. It provides a consistent, unified experience across services, fast round trip resolution via caching strategies, and built-in optimization on queries. Partners can use this API to build web-based services that allow users to quickly and easily transfer their playlists between services, provide deep links into the Amazon Music service, and more.
Some user information—such as user-created playlists, personal library, and saved podcast episodes—is also available, if the user grants permission. There is some limited editing functionality for items such as playlists, also with user permission.
The API is a RESTful service, an architecture which will be familiar to many developers, making integration as easy and painless as possible. API resources are provided by Amazon as a series of endpoints. These endpoints can be queried via HTTPS requests using standard HTTP methods. Results use standard JavaScript Object Notation (JSON) as a data-interchange format. Results are returned in the form a response object. These results can be parsed to retrieve the desired information. For instance, querying for information about “Daft Punk” might return the artist’s name, a URL for the Amazon Music catalog, and a URL for an image of the artist, all contained within the data field of the response object. For details about the JSON results, see the response example for each individual endpoint.
Base URL
Use this URL wherever you encounter <base url>.
An example request for a list of albums might appear as follows:
curl --location 'https://api.music.amazon.dev/v1/albums/?ids=B0064UPU4G%2CB091BHTFTZ%2CB0869N1S7F' \
--header 'x-api-key: <your security profile ID>' \
--header 'Authorization: Bearer <your auth token>'
Accessing the APIs
The APIs are currently in Beta status and access is limited to approved developers. If you have a compelling business case and need access to the APIs reach out to your Amazon Point of Contact. If you don't have a POC, you may use the contact us form. Select the Music Developers Category and provide as much information as possible about you, your business and use case. To enable access you will need to log into the developer console, accept the terms of the developer service agreement. Then create a Security Profile in the LWA Console.
Authentication (OAuth 2.0 Protocol)
All Amazon Music Web API endpoints require a valid OAuth 2.0 authentication token for access. Amazon provides a single, unified authentication service called Login With Amazon (LWA) which provides valid OAuth 2.0 tokens for most Amazon services, including the Amazon Music Web API. To use LWA, you will need to create an LWA account and security profile to receive the client ID and device ID you use for authentication. When authenticating with LWA, a scope is required. The LWA scope profile is an example that can be used for scope when authenticating.
To learn more about Login with Amazon, click here.
Calls to the Amazon Music Web API must always include two header parameters: Authorization and x-api-key. The value of Authorization should be the bearer token you received from the LWA service. And the value of x-api-key should be your LWA Security Profile ID. The Security Profile ID is not the same as the Client ID you used to acquire the LWA token. You will find it in the general tab of the Security Profile Management page in the LWA Console the ID looks like amzn1.application.xxxxxxxxxx, which is different than the Client ID with is prefixed with amzn1.application-oa2-client.xxx
The Security Profile ID(s) used by Music client applications must be enabled by the Amazon Music Service in order for authorization to be successful. Reach out to your Amazon Music point-of-contact for more information.
Where to Start
Depending on the use cases you are looking to implement, you might need to use only a subset of the API endpoints.
If you are aiming to build a visual experience for customers to discover Amazon Music content and start playback on your platform, we recommend you check out the endpoints for Views, Search and Playback.
Other endpoints focus on specific entity types, such as Playlists with dedicated endpoints to list, create and modify user playlists.
Error handling and throttling
To protect The Amazon Music service, Transaction Per Second (TPS) limits are enforced on the APIs. When exceeding this limit, the API will return a 429 response with a message like "Too Many Requests - Rate limiting has been applied." Implement an exponential back-off algorithm when retrying to avoid compounding the service overload problem. To request an increase over the default limits, contact your Amazon Music POC.
Click here to learn more about common error responses and how to handle them.