HAQM Music Web API
Web API Overview V1.0
HAQM Music Web API
The HAQM Music Web API is a new, simplified API allowing quick retrieval of meta-data about albums, tracks, artists, playlists, podcasts, and more from the HAQM 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 HAQM 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 HAQM 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 HAQM 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 'http://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 closed Beta status and access is limited to already approved developers.
Authentication (OAuth 2.0 Protocol)
All HAQM Music Web API endpoints require a valid OAuth 2.0 authentication token for access. HAQM provides a single, unified authentication service called Login With HAQM (LWA) which provides valid OAuth 2.0 tokens for most HAQM services, including the HAQM 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 HAQM, click here.
Calls to the HAQM 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 HAQM Music Service in order for authorization to be successful. Reach out to your HAQM 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 HAQM 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 HAQM 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 HAQM Music POC.
Click here to learn more about common error responses and how to handle them.