Universal search enables Sonos users to find content across multiple music services on a Sonos app. Users can find content throughout different categories, such as artists, tracks, albums, or others. Users must have an account on a music service for it to be shown in the results. Sonos apps display results alphabetically by music service. This guide goes over the following:

The screen shot below shows the results of a search on the Sonos app for mobile devices.

Sonos provides two different ways of searching for content. Your service must support both methods of searching to provide your listeners with the best Sonos experience.

Listeners using the Sonos app on a Mac or PC can perform a keyword search across categories in your service. Implement this by responding to a getMetadata request for search with a list of categories. See below for details.

Listeners using the Sonos app for iOS or Android can perform a category search across multiple services at once. Implement this by sending a list of searchable categories from your presentation map. See the rest of this document for details.

---

How search works

1. User searches for an artist, album, track, or other category in the search box on the Sonos app.
2. The Sonos app sends the search request entered by the user to your service through the SMAPI search() method.
3. Your service returns the results and the Sonos app aggregates and displays them.

You can offer varying degrees of search:

• Category search – offer search results using the standard Sonos search categories.
• Custom Category – offer search results using a category customized to your music service.
• Multiple Library Search – offer search results within the context of different libraries, such as a global library and a user-specific library.

You can combine these search methods to offer an extensive solution for your service. They are described below in order of complexity.

Category search

In order to offer search across all services, Sonos standardized category names. Search categories are integrated into the presentation map. The PresentationMap element uses a “Search” type to specify your search categories and mappings. Use a Category element inside a SearchCategories element inside a Match element to map a known canonical search ID to the SMAPI ID that you’ve defined for your service, using the id and mappedId attributes, or omit the mappedId type to use a default SMAPI ID.

• The id attribute is the canonical search ID.
• The mappedId attribute is the search term that your SMAPI implementation expects.

For example, in one of the mappings below, the “user” category is mapped to the Sonos canonical search ID “people”.

See below for the full list of Sonos canonical search IDs.

Category attributes

A Category type has the following attributes:

Name	Type	Description
id	CanonicalSearchId	Defines unique identifiers for known categories of searchable items across SMAPI services. One of the following is required: artists albums composers episodes genres hosts podcasts people playlists stations tags tracks
mappedId	string	The SMAPI identifier for the category used by the music service in search. This is optional.

Custom Category search

Use a CustomCategory element inside a SearchCategories element inside a Match element to define a searchable type that is not defined as a Sonos canonical search ID.

Add text for the custom search category to the strings.xml file and use the stringId value to identify this value in the strings.xml file. Sonos apps use the string entry for the UI and pass the mappedId value back to your service through search when the listener attempts to search for it.

Be sure that your custom category doesn’t search the same fields as an existing Sonos category. If this is the case, you should use the existing category.

CustomCategory attributes

A CustomCategory type has the following attributes.

Name	Type	Description
mappedId	string	The SMAPI identifier for the category passed to search. This is required.
stringId	string	The string entry from strings.xml used for the UI for the custom search category. This is required.

Multiple Library search

Sonos supports multiple searches for the same category in different contexts, for example, if your service offers a global library of songs as well as a user-specific library of songs, a user can search for a song and see the results in the global library as well as their own user library. Sonos apps for mobile devices display the search context within the search results for your service:

And Sonos apps for Windows and Mac OS offer users the ability to choose the context to search:

Use multiple SearchCategories elements to support search results grouped by context, and then use a stringId attribute in the SearchCategories element to define the context for the search. Use a Category element inside a SearchCategories element to define search categories.

While mappedId is an optional attribute of the Category element, you should use this attribute when using multiple category groups to be sure that you can disambiguate them at the endpoint of your service.

Define the text to use in the user interface in the strings.xml file for these stringId keys.

Context search attributes

Implement context search on your existing category or custom category search using the mappedId attribute as defined below.

Name	Type	Description
mappedId	string	The SMAPI identifier for the category passed to the SMAPI search() method. You should have a method to determine the search category grouping; in the example above, this is determined by appending a “:0” and “:1”.

All search category

As part of the new search experience on Sonos, you can optimize search traffic by implementing an All search category. This category performs all-inclusive searches across your currently-supported categories, then returns a heterogeneous mix of content and category results.

Preparing for search traffic

Search requests will come from a central Sonos cloud service, not from the user’s clients.

To enable the All search category, you must allow traffic from the following IP addresses:

Prod US	Prod EU
54.174.40.169	54.155.193.190
54.86.86.14	54.228.23.52
3.89.18.155	54.78.147.117

Implementing All search category

The following example will demonstrate how to implement the new All search category.

In this example, we’ll focus on the following search categories currently present in the PMAP: Artist, Album, Track, and Playlist.

These categories are supported in this example of the Sonos search, but your implementation may differ in supported categories.

To implement All category search, add the new all category within the SearchCategories tag:

You must use all as the ID, since this will inform Sonos that the All category should be used by search experiences that support it instead of the other categories.

Fulfilling All search category requests

To fulfill a request for the new All category, ensure your service can perform cross-category searches, then return a set of cross-category results.

Your results should return in the same format type as regular SMAPI search category responses. The only difference is that the itemTypes of the responses will vary.

Testing All search category

To ensure that your SMAPI service is returning the expected results, test out the All search category calls using cURL or your preferred HTTP client.

1. In the terminal, create a POST request for the All search category id ensuring you have valid credentials for your service.

Example request

2. Send the request and verify that the resulting response contains the expected information for requests made to the All search category.

Example response

All search category ranking results

The All category search results are ranked in terms of relevancy. Up to nine results are presented in the default Sonos search results view per content provider.

If a user then browses into more results from your service, the full set of results will be displayed, grouped by category.

---

Presentation map configuration examples

The SearchCategories element details the searchable asset types that your service provides, such as tracks, albums, stations, playlists, and so on. This element was added as of build 26.1-73040 and above. Sonos apps using build 38.1 and above can add multiple SearchCategories elements to enable context search (see About My Sonos System in the Sonos app to find the build number).

The service in this example supports searchable artists, albums, and tracks using default SMAPI IDs:

This example shows a service that supports searchable artists, albums, and tracks but the SMAPI IDs for searching on those categories are different than the default:

This example shows a service that supports searchable artist, albums, and tracks using a mix of default SMAPI IDs and custom SMAPI IDs, along with a CustomCategory that is not found in the canonical search categories:

In the example above, the Sonos app will allow searching for artists, albums, tracks, and concerts. The Sonos app will use the stringId as the default display text. To localize this string, you must add an entry in strings.xml that maps the stringId to appropriate text.

---

Strings XML localization

Following the existing Sonos app localization functionality, Sonos apps will use the stringId from the presentation map configuration of a CustomCategory, and look up the string node in the strings.xml configuration with the same stringId using the language setting from the Sonos app to get the text that will be displayed to the listener. See Strings and Localization for details.

If a matching stringId is not found, the Sonos app will default to the text configured as the stringId in the presentation map as a fallback.

---

SMAPI interaction

With the proper configuration, Sonos apps will use the presentation map to configure universal search. When a listener searches for a given term, the Sonos app will submit a request to your SMAPI search endpoint for each of the SearchCategories you have defined in the presentation map simultaneously. Using the last presentation_map.xml configuration as an example, the Sonos app will emit four SMAPI calls asynchronously:

• search(“artists”, “my term”, 0, 100)
• search(“my:custom:smapi_id:album”, “my term”, 0, 100)
• search(“my:custom:smapi_id:track”, “my term”, 0, 100)
• search(“my:custom:smapi_id:concerts”, “my term”, 0, 100)

The Sonos app then aggregates the results sent by your service and displays them accordingly. See search for sample requests and responses.

---

Support search on desktop apps

You must implement search for Windows and Mac OS applications as well as Sonos apps for mobile devices. Implement search for mobile devices by sending a list of searchable categories in the SearchCategories element in the presentation map as described above. Implement it for Windows and Mac OS by sending these categories in a response to a getMetadata request on the search container.

The Sonos app displays the search results in the order you specify in the presentation map. For example, if your presentation map lists artists, albums, and songs from top to bottom, the Sonos desktop app displays these categories from left to right.

Request

The Sonos app for Windows and Mac OS sends a getMetadata request on the search container for your service:

Response

Your service should respond with the search categories:

See search for details.

Sonos app for Windows and Mac OS

In the Sonos app for Windows or Mac OS, the user searches for “rock” in the “Artists” category:

In the example above, the Sonos app sends the following request:

The service responds with: