Cross reference content with the Apple Music API

Hello and welcome to WWDC. My name is Shachi Khare, and I’m an engineer on the MusicKit team. Apple Music API is a web service that provides APIs for building Apple Music experience across platforms. In this video, I’m going to talk about some enhancements to the Apple Music API that'll enable you to cross reference Apple Music content. We will start with discussing cross storefront equivalency, followed by explicit and clean mapping. Then we will go over how you can cross reference library and catalog content. And finally, we’ll talk about looking up content using the UPC identifier. So let’s get started with cross storefront equivalency. Apple Music is a worldwide service that operates in many regions. Content varies from one geographical location to another. So each request to the API is accompanied by a storefront object which defines the desired region. Alternate versions of content may be available with different IDs between storefronts. For example, this album Chromatica has a content ID as shown here in the United States storefront, but an equivalent version of this album in the Japan storefront has a different ID. So if you fetch this album with the ID shown here in the U.S. storefront, you will get a successful response from the API. But if you use the same ID to fetch the album in the Japan storefront, you will get a 404 response. As a result, sharing the link to a piece of content with someone in a different storefront may not work. In order to solve this problem, we need to get the equivalent content ID in the target storefront. So in this example, given the content ID for this album Chromatica in the U.S. storefront, we need to find the content ID which represents this album in the Japan storefront. Here is the API that returns the equivalent in the target storefront. It takes the target storefront in the path and a filter query parameter that takes the content ID in the current storefront. This API supports fetching equivalents for albums, songs, and music videos. Here is an example of this API that takes the input album ID in the U.S. storefront, and we want to find the equivalent album ID in the Japan storefront. We have taken U.S. as an example of the input storefront and Japan as the target storefront, but you can choose any storefront supported by Apple Music. The response contains the equivalent version of the album in the Japan storefront. As you can see, the ID returned in the response is different from the one in the input to the API. Next let’s look at explicit and clean mapping.

We have a similar problem with explicit and clean content. Some users prefer to restrict explicit content. Some storefronts may have regional regulations that prohibit explicit content. For these use cases, we can replace explicit content with the clean equivalent instead of completely dropping it, so users can still enjoy the clean counterpart.

Here is how you can use the API to get the clean equivalent. Similar to the previous example, you need to pass the filter parameter with the input contentID. Add the query parameter restrict=explicit to get the clean content. This API is available for albums, songs, and music videos. Let’s look at an example. We make a get request to the album’s endpoint to get the album Good News with the contentId as shown in this example. The response contains the explicit version of the album. Now if we add the restrict=explicit parameter, we can see that the response contains the clean version of the album. Now let’s look at how you can cross reference library and catalog content. Since we have launched MusicKit, we got feedback to add a way to reference catalog resource from a given library resource. This is because catalog and library content IDs have a different keyspace. For instance, as shown in this diagram, the album in the catalog has a different ID from the one in the library as shown on the right side. Similarly, other content types like artists, playlists, and songs have a completely different ID in the library. Therefore, finding the matching catalog content from the one in the library and vice versa was not possible.

This year, we have added the API that allows you to get the library ID for a given catalog content ID if the content exists in the user’s library. We have also added an API that allows you to get the catalog ID for a given library ID if the content exists in the Apple Music catalog. This API provides an easy way of determining if the content exists in the user’s library, which can be used to conditionally provide the ability to add content to the library. With this new addition, it is also easy to deep link to the catalog content from within the library. To get the catalog ID for the given library ID, simply add the query parameter relate=catalog. The response will contain the relationship “catalog” that’ll contain the resource identifier for the related catalog resource. The href from this response can be used to deep link to the catalog. To get the reverse mapping, that is, get the related library ID for a catalog ID, add the query parameter relate=library. The response will contain the relationship “library” that’ll contain the resource identifier for the related library resource. iCloud Music Library is completely personalized for the user. So the mapping from the catalog to the library is also personalized and requires a valid user authentication token. Requests may be faster when fetching data from the catalog, so it is better to use the library relationship only when needed. Let’s now go over how you can look up content using the UPC identifier.

UPC, or Universal Product Code, is an identifier that is used to represent music as an entire physical or digital product. It is typically represented by a barcode with a unique 12-digit number beneath it. We have added the ability to look up an album by its UPC code. This allows you to match content in the Apple Music catalog from other sources. We think this is a good addition to the API that we added last time to allow looking up content using the ISRC code. To get an album using its UPC, add the query parameter filter and pass the UPC ID for the album. As you can see in the response here, it returns a resource collection of the albums with a matching UPC identifier. To wrap up, we talked about various ways you can look up content available on Apple Music. We discussed referencing content across storefronts. We talked about how to fetch the version of a content with a different content rating. We explored the library and catalog relationship, and we also discussed matching content using the UPC identifier. We hope that you can leverage these APIs to build a richer Apple Music experience. To learn about other new features and concepts added to MusicKit, make sure to watch the sessions linked to this video. Thank you for watching, and we hope that you enjoy the rest of the conference. [music]