Explore the catalog with the Apple Music API

♪ Bass music playing ♪ ♪ Graham Seyffert: Hello and welcome to WWDC 2021.

My name is Graham Seyffert, and I’m a MusicKit engineer.

Over the past few years, we’ve enhanced the ability of developers to fetch new, enriched data from the Apple Music catalog.

Today we’re excited to introduce some of those improvements to you.

In this presentation, we’ll be going over enhancements to the search functionality in the API, as well as new ways to request data by relating resources, extending attributes, and requesting relationship views for resources in your responses.

Finally, we’ll go over some new enhancements to the Charts API.

Before going over some of the search enhancements, I’d like to quickly recap the current /search/hints endpoint.

You might already use this endpoint today to fetch a list of suggested search terms.

As an example, here’s some results you might get back for the search term “taylor”.

Today, we’re introducing the /search/suggestions endpoint which replaces the /search/hints endpoint.

This endpoint provides access to the same terms as the /search/hints endpoint, and you can continue to fetch these by specifying kinds=terms on your request.

However, you can see that the response from this endpoint is a bit different.

suggested results now indicate their kind, which will match one of the kinds specified on the request.

It also differentiates the term that should be used for the search query from the term that should be displayed to the user.

More importantly, this endpoint now also allows access to the top suggested search results -- ideal for powering typeahead results.

These may be requested by specifying kinds=topResults on the request, as well as some resource types that you’re interested in fetching results for.

Resources for topResults kinds can be found under the content key.

It’s worth noting that the results you’ll get from this endpoint might be noticeably different from the results you’d get from a regular search, as this response prioritizes speed over breadth.

As such, this is not intended to be a replacement for the regular /search endpoint, but rather a complement to it.

Before going into how to modify resources, I’d like to reintroduce what a resource is for those that may not be familiar.

All resources have what we call a “resource identifier,” which is the minimal amount of information you’d need in order to look a resource up in the API.

Resource identifiers will include a resource’s ID, its type, and its href.

The complete representation of a resource will also include that resource’s attributes, such as its name, and potentially relationships if they’ve been requested using the include parameter.

Relationships are collections of related resources, such as a song’s genres or a playlist’s tracks.

With that, I’d like to now introduce the concept of relating resources.

Relationships requested with relate are different from relationships requested with include in that they only return the aforementioned Resource Identifiers for the resources in that relationship.

This means that relating a relationship results in a faster response if all you need access to is a resource's reference.

You can relate a relationship by using the relate query parameter and classifying it with the resource type you’re targeting, followed by a list of relationship names you’re interested in getting back.

For example, on the /search /suggestions endpoint, you may decide that when a user selects a song result that you want to pop out to the album page for that song.

In this case, all you need is the href for that song’s album in order to navigate there, so we can specify relate=albums in order to get that data.

After doing that, we can see that song results in our response now include the resource identifiers for their respective albums.

So relate is great to use when we want to quickly reference additional related content, but what if we want to learn more about the resources we’re already getting back in our responses? As mentioned previously, every resource today has a default set of attributes -- things like its name, its artwork, et cetera.

But resources may also have extended attributes.

Extended attributes are either more expensive to calculate or are less frequently needed, such that including them by default might either slow down responses noticeably or bloat the object model.

Similar to what we just saw with the relate query param, you can request extended attributes on resources by using the extend query param, classifying it with a resource type, and following it with a list of attribute names that you’re interested in.

Building on our /suggestions request, we might decide that, for song results, we also want to allow users the ability to link out to that artist’s page on Apple Music.

In order to do this, you could simply append extend=artistUrl to your request.

Indeed, after doing this, we can see the songs resources in our responses now include the artistUrl attribute.

Now I’d like to introduce the concept of relationship views.

Compared to relationships, views are more loosely coupled to their resource.

They don’t necessarily represent some ground truth about a resource like relationships do.

This makes views ideally suited for driving product page experiences, such as an album page.

Compare this to relationships which may be useful to use on, for instance, search result pages.

Additionally, views may have attributes -- like a title -- as well as data.

Views are also only requestable on direct resource fetches.

This means that there are two different ways you can fetch them.

You can either use the views query parameter and specify a list, or a single one via /view/{viewName} right after the resource’s ID in the request path.

In this response, we have an example of what it might look like to include the Top Songs view on an artist resource.

Other examples include Top Music Videos or an artist’s singles.

The full list of supported views for a given resource type can of course be found in the official Apple Music API documentation.

Finally, let’s take a look at the updates to the Charts API.

Today, Apple Music supports chart playlists for the world, storefronts, and more recently, specific cities.

Users can add these chart playlists to their libraries, which will update automatically.

You can now fetch these directly from the /charts endpoint by specifying types=playlists and using the "with" query parameter to indicate which sets you’d like -- either dailyGlobalTopCharts or cityCharts, or both.

And here we have an example of how a chart’s response with those query parameters might look.

So in summary, today we went over enhancements to the search and charts endpoints, and looked at new ways to fetch data for resources in our responses.

If you’d like to learn more about the Apple Music API, I’d highly suggest this year’s session on how to Cross reference content on the Apple Music API, or 2017’s Introducing MusicKit presentation, which goes over some of the API’s core concepts in even greater detail.

Thanks so much for watching, and we hope you enjoy this year’s WWDC.

♪