Add search

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.

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: mobile and desktop. Your service must support both methods of searching to provide your listeners with the best Sonos experience.

Listeners using the Sonos app for iOS or Android can perform a category search across multiple services at once. All mobile app search requests come from a central Sonos cloud service.
Implement this by sending a list of searchable categories from your Integration Submission Form.

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.

How search works

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

You can offer varying degrees of search:

All Category search - offer search results from all supported categories in a single All categories
Category search - offer search results using the standard Sonos search categories.
Custom Category search - 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.

All search category

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

Implementing All search category

To implement the All category, select it from the Category ID dropdown on the Search Capabilities page.

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.

For information on testing your category search, see the Testing your search categories section.

Category search

In order to offer search across all services, Sonos standardized category names. Search categories are listed under the Category ID field on the Search Capabilities page in the Integration Submission Form.

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: - all - 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.

For information on testing your category search, see the Testing your search categories section.

Custom Category search

To create a custom search category, click the Add Custom Category button on the Search Capabilities page. Fill out the title of the custom category and enter a Mapped ID for the SMAPI service to search against.

🚧
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.

For information on how to add text for your search category, see the Adding text for categories section.

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.

For information on testing your category search, see the Testing your search categories section.

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:

Add multiple search categories to support search results grouped by context, using the Catalog Type field to define the context for the search, user or global content.

For information on how to add text for your search category, see the Adding text for categories section.

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".

For information on testing your category search, see the Testing your search categories section.

Adding text for categories

Add text for search categories to the Localization Resources page and use the Name field to identify this value in the localization 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.

Examples

{
    "en-US":{
      "common":{
         ...
          },
      "integration":{
        "CATEGORY_TYPE_CONCERT": "Concerts",
        ...
      }
}

{
    "en-US":{
      "common":{
         ...
          },
      "integration":{
        "library_type_local": "Local",
        "library_type_global": "Global"
        ...
      }
}

🚧
Be sure that your custom category doesn't search the same fields as an existing Sonos category.
Instead, use the existing Sonos category.

Testing your search categories

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.

In the terminal, create a POST request for the All search category id ensuring you have valid credentials for your service.
Send the request and verify that the resulting response contains the expected information for requests made to the All search category.

👍
Once your integration is in Preview state, you can fully test search from within the Dev Portal.

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 on the Search capabilities page of your Integration Submission Form.

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 your Integration Submission Form. For example, if your form 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:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns="http://www.sonos.com/Services/1.1">
   <soapenv:Header>
      <ns:credentials>
        ...
      </ns:credentials>
   </soapenv:Header>
   <soapenv:Body>
      <ns:getMetadata>
         <ns:id>search</ns:id>
         <ns:index>0</ns:index>
         <ns:count>10</ns:count>
      </ns:getMetadata>
   </soapenv:Body>
</soapenv:Envelope>

Response

Your service should respond with the search categories:

<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns="http://www.sonos.com/Services/1.1">
   <s:Body>
      <ns:getMetadataResponse>
         <ns:getMetadataResult>
            <ns:index>0</ns:index>
            <ns:count>2</ns:count>
            <ns:total>2</ns:total>
            <ns:mediaCollection>
               <ns:id>search:songs</ns:id>
               <ns:itemType>search</ns:itemType>
               <ns:title>Songs</ns:title>
               <ns:canPlay>false</ns:canPlay>
               <ns:albumArtURI/>
            </ns:mediaCollection>
            <ns:mediaCollection>
               <ns:id>search:artists</ns:id>
               <ns:itemType>search</ns:itemType>
               <ns:title>Artists</ns:title>
               <ns:canPlay>false</ns:canPlay>
               <ns:albumArtURI/>
            </ns:mediaCollection>
         </ns:getMetadataResult>
      </ns:getMetadataResponse>
   </s:Body>
</s:Envelope>

Refer to search for details.

Sonos app example for desktop apps

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:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns="http://www.sonos.com/Services/1.1">
   <soapenv:Header>
      <ns:credentials>
         <ns:loginToken>
            <ns:token>ABCDEFGHIJK123</ns:token>
            <ns:key>keyvalue</ns:key>
            <ns:householdId>householdId</ns:householdId>
         </ns:loginToken>
      </ns:credentials>
   </soapenv:Header>
   <soapenv:Body>
      <ns:search>
         <ns:id>search:artists</ns:id>
         <ns:term>rock</ns:term>
         <ns:index>0</ns:index>
         <ns:count>10</ns:count>
      </ns:search>
   </soapenv:Body>
</soapenv:Envelope>

The service responds with:

<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns="http://www.sonos.com/Services/1.1">
   <s:Body>
      <ns:searchResponse>
         <ns:searchResult>
            <ns:index>0</ns:index>
            <ns:count>10</ns:count>
            <ns:total>10</ns:total>
            <ns:mediaCollection>
               <ns:id>artist_abc123</ns:id>
               <ns:itemType>artist</ns:itemType>
               <ns:title>Rock Sound</ns:title>
               <ns:canPlay>false</ns:canPlay>
               <ns:canEnumerate>true</ns:canEnumerate>
               <ns:albumArtURI>https://cdn.example.com/artist_abc123.jpg</ns:albumArtURI>
            </ns:mediaCollection>
            <ns:mediaCollection>
               <ns:id>artist_abc456</ns:id>
               <ns:itemType>artist</ns:itemType>
               <ns:title>Bebble Rock</ns:title>
               <ns:canPlay>false</ns:canPlay>
               <ns:canEnumerate>true</ns:canEnumerate>
               <ns:albumArtURI>https://cdn.example.com/artist_abc456.jpg</ns:albumArtURI>
            </ns:mediaCollection>
            <ns:mediaCollection>
               <ns:id>artist_bcd789</ns:id>
               <ns:itemType>artist</ns:itemType>
               <ns:title>Q107Toronto</ns:title>
               <ns:canPlay>false</ns:canPlay>
               <ns:canEnumerate>true</ns:canEnumerate>
               <ns:albumArtURI>https://cdn.example.com/artist_bcd789.jpg</ns:albumArtURI>
            </ns:mediaCollection>
            ...
         </ns:searchResult>
      </ns:searchResponse>
   </s:Body>
</s:Envelope>