|Notice to customers|
|Starting Oct 2nd, the onboarding to the Groove Music API is disabled. As part of the partnership, the Groove Music Pass service will be discontinued on December 31, 2017.|
After that date, Groove Music Pass content will not stream or play and our API features will not be accessible. Please check our FAQ on https://aka.ms/groovepartnerfaq . All features of the Music API will be supported until Dec 31st.|
Groove Service REST Reference
The Groove Service delivers Groove functionality to third-party application developers for integration within their own apps.
The API follows the REST API convention and returns JSON (or XML) results. The following calling conventions are used:
- Parameters are provided as query parameters in the GET HTTP method. Response content is serialized in JSON by default, but can be switched to XML if the HTTP header
Accept: application/xmlis provided.
- The API is versioned. Version is to be prepended to the URI. Currently, all Groove RESTful API calls must begin with /1/.
- Third-party developer authentication is mandatory in all methods and is done by passing an OAuth token as a mandatory query parameter in all methods.
- GZIP compression is supported and responses are compressed if the HTTP header
Accept-Encoding: gzipis provided in the request.
- CORS is supported in the standard way, by using the headers
- JSONP is also supported via an optional query parameter, &jsonp=value, in all methods.
- Flash cross-domain calls are supported as well.
- Locale parameters are the same across all methods; they all have two optional query parameters, language and country, whose values are two-letter standard language and country codes. When no country information is provided via the country parameter or user authentication, the country is determined by geolocation of the caller's IP address.
- All APIs share a common notion of namespace that indicates the type of content referred to. Currently the only supported namespace is music.
|Album (JSON)||A musical recording.|
|Artist (JSON)||The creator or creators of a musical recording.|
|CollectionState (JSON)||The state of the user's collection (if the request was user-authenticated).|
|ContentItem (JSON)||Media content (either an Album or an Artist).|
|ContentResponse (JSON)||The output element for most content APIs.|
|Contributor (JSON)||An artist and the artist's role|
|CreateRadioRequest (JSON)||The input element for every radio station creation request|
|Error (JSON)||Error object for attempts to query the Music catalog.|
|Genre (JSON)||A Musical genre|
|PaginatedList (JSON)||Describes paginated lists, a type of response from the Groove Service that can be continued by using a token.|
|Playlist (JSON)||A list of tracks and their metadata.|
|PlaylistAction (JSON)||The input element for every playlist action request: create, update, and delete.|
|PlaylistActionResponse (JSON)||The output element for every playlist action request: create, update, and delete.|
|PlaylistActionResult (JSON)||The object describing a playlist action result, used by add and delete.|
|Radio (JSON)||A radio station|
|RadioResponse (JSON)||A list of tracks for a given radio along with the radio session id|
|Seed (JSON)||A radio seed|
|StreamResponse (JSON)||Response to all stream APIs.|
|Track (JSON)||Describes a track, an individual piece of musical content from an album.|
|TrackAction (JSON)||An action (such as add or delete) on a specific track.|
|TrackActionRequest (JSON)||The input element for every track action request: add and delete.|
|TrackActionResponse (JSON)||The output element for every track action request: add and delete.|
|TrackActionResult (JSON)||The object describing a track action result, used by add and delete.|
|UserProfileResponse (JSON)||Profile of the user, including subscription, collection, and culture information.|
Parameters common to every Groove RESTful API
Describes the parameters common to all methods in the Groove RESTful API.
Extra parameters for Lookup API
Optional query parameter that allows requesting a list of extra fields that are by default not included in the responses.
Description of the different namespaces used across the Groove RESTful API .
orderBy parameter for Catalog and Collection Browse APIs
Allows ordering browse results in a specific order.
Groove RESTful API HTTP Status Codes
Describes the standard HTTP status codes that are returned by the service.