Sonos Music API - Getting Started Guide

Music service requirements

You must do the following to implement a valid Sonos music service:

  1. Implement a core set of API requests with valid responses including both success and error handling.
  2. Implement authentication APIs if requiring user authentication to use your service. See Implementing Authentication for more details.
  3. Handle all valid API calls gracefully whether or not they are fully implemented.
  4. Handle pagination in API requests that support it.
  5. Return defined errors in the expected manner. See Error handling for more details.

Sonos strongly recommends you also do the following:

  1. Keep your Sonos music service feature set in sync with the features supported by other client interfaces to the extent possible. If SMAPI supports a feature that you implement in other client interfaces you should also implement it in your SMAPI server.
  2. Keep your Sonos interface behavior in sync with other client interfaces you support. For example, specific searches should return exactly the same response via Sonos and your web interface.
  3. Make sure changes made via Sonos show up in other clients quickly and vice versa. For example, when a user favorites a track in your mobile app their Sonos controllers should see it in close to real time. Conversely, if a user dislikes a track in Sonos it should be marked as disliked in the web application and treated accordingly. The getLastUpdate API call should be used to help manage this process.
  4. Use caching for content that is unlikely to change or that is likely to be requested repeatedly over a short period of time.
  5. Encode your audio data using container formats that keep samples organized in contiguous blocks. In other words, avoid container formats that require applications to seek repeatedly to stream audio. More information about optimizing audio files can be found in the streaming documentation.
  6. If your service uses content or APIs from a third party, be sure you understand any restrictions before integrating with Sonos. For example, if you're using a content provider that restricts the availability of content for connected devices.


SMAPI Core Methods

The following calls are core to SMAPI and must be implemented by every music service:

Note: If your service does not implement the ability to search in any of its other interfaces or clients you may omit search support in your SMAPI music service. Sonos does not expect you to implement search in your back end solely for use by Sonos.

SMAPI Authentication Methods

The following calls control household and user authentication and must be implemented if your service uses authentication:

Other SMAPI Methods

SMAPI supports many other API calls used to implement features like playlists, favorites, ratings, and reporting. Information about each supported call can be found in the Sonos Music API - Reference on Sonos Labs.