The following topics offer a detailed reference to the options provided by the Nokia MixRadio API.
This section explains some of the basic concepts that will help you to understand how the API works.
As with all music services, we license content from record labels per country and therefore availability varies. We work to localise our catalogue with the most relevant content for each country. For this reason, the the MixRadio API requires a country code to filter the availability. By default, we use the device Region settings to determine the user's home country, but we also allow advanced use where you can obtain an ISO 3166-2 country code yourself and validate the country with the CheckAvailability method.
The API requires applications to authenticate themselves with a unique ID known as a Client ID (we used to refer to this as AppId, they are interchangable in terms of the API usage).
The Client ID must be passed in the MusicClient constructor as shown in the following example:
MusicClient client = new MusicClient(MyAppId);
You can sign up for credentials by registering application(s) on our registration page.
Asynchronous Programming Model
The Nokia MixRadio API uses an asynchronous programming model that helps your app stay responsive when it calls out to our REST API over the Internet, where (depending upon connection speeds), a method call might have several seconds waiting for the information to arrive.
The MusicClient methods allow use of the Windows RT async/await pattern. This can simplify your code significantly:
ListResponse<MusicItem> result = await client.SearchAsync("muse"); // Handle the response
Many of the methods in the API will give large numbers of results, so the methods are overloaded to allow pagination. You will see optional StartIndex and ItemsPerPage parameters on these methods. If these parameters are not supplied, we use defaults of StartIndex = 0 and ItemsPerPage = 10.
Your main API interaction will be through the MusicClient class, but we also expose various strongly-typed objects and response objects. The following table covers the classes that make up the Nokia MixRadio API.
|MusicClient||The main class used for interacting with Nokia MixRadio.|
|Response||Contains properties for getting details about the API response.|
|ListResponse||Extends the Response class with details for API responses that contain lists.|
|MusicItem||Base class for items from the MixRadio API that can be searched, such as Artists, Mixes and Products.|
|Artist||Represents a musical artist in the Nokia MixRadio Catalog.|
|Genre||Represents a musical genre in the Catalog such as "Rock".|
|MixGroup||Represents a collection of Mixes. An example MixGroup would be "New Releases" that has Mixes such as "Pop New Releases", "Rock New Releases", etc.|
|Mix||Represents a collection of tracks that can be played through the Nokia MixRadio Windows Phone app.|
|Product||Represents a purchasable music content such as albums, singles or individual tracks in the Catalog.|
|Price||Contains a currency code and numeric value for a Product.|
|Category Enumeration||Denotes the category of an item in the Catalog.|
|CountryResolver||Advanced class for validating a country has availability for the Nokia MixRadio API.|
Last updated 20 November 2013
We appreciate your feedback.