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