Welcome to the C# SDK

About

The Quantone C# SDK makes it simple to query the Quantone API and deal with the results returned.

Calls to the Quantone API are made through query objects, which take care of all the logic involved in running a REST query, including deserializing the results to handy result objects. These can then be used to easily integrate Quantone data into your own application

Versions 0.2 and below of the Quantone C# SDK are only compatible with Quantone API 2.0, which was discontinued on 30th November 2014. If you haven't already, please upgrade to version 0.3 or above of the SDK.

Download

Please note: The C# SDK is currently in beta release. Content and functionality are likely to change significantly and without warning.

Download

The latest version of Quantone C# SDK is avalible from NuGet. Click here to download it or run the following command in the Package Manager Console in Visual Studio:

PM> Install-Package QuantoneSDK

Installation

  • In Visual Studio, right click the References section of your project in the Solution Explorer and select Add Reference
  • Click Browse, navigate to the location you have saved the DLL to and confirm the addition by clicking OK
  • Add the following line to the top of any file that will use the Quantone C# SDK

using QuantoneSDK;

Querying the API

Before you can query the Quantone API, you first need to create a new Quantone object. This will be used to run all your queries. The Quantone class has a constructor that takes two arguments, your app ID and app Key. These are provided on registration.

var myQuantone = new Quantone("YOUR_APP_ID", "YOUR_APP_KEY");

Each query topic has its own Query class. A full list of topics can be found in our API Reference. Lookup query classes, eg AlbumsByIdQuery, return one result and are used to find items by Quantone ID. Query classes, eg QueryAlbums, return many results and are used to search the API by parameters such as title, main artists, release date etc.

Querying works the same for all topics. First, a new instance of the class must be created. The parameters should then be filled in with the values you require. The Quantone C# SDK is IntelliSense compatible. A full list of parameters can also be found online in our API Reference. Please note: not all parameters are currently supported by the SDK

Single Query

The following code demonstrates how to create a new AlbumsByIdQuery query to find the album with a given Quantone ID.

var qo = new AlbumsByIdQuery
{ 
    depth = new [] {AlbumRetrievalDepth.Recordings, AlbumRetrievalDepth.Identifiers},
    id = "156dda6c-358f-e311-be87-ac220b82800d",
};

Search Query

The following code demonstrates how to create a new QueryAlbums query, searching for albums with the title 'Rumours' that were released in 1977.

var qo = new AlbumsQuery
{ 
    title = "Rumours",
    dateReleased = "1977",
};

Running The Query

Once the parameters you wish to search on have been set, use the Quantone.Execute(qo) method to run the query. The result object returned will correspond to the query type

var qr = myQuantone.Execute(qo);

Dealing With Results

The result of the query is saved to the Result object in your Query object. The structure of this differs slightly for single and search queries.

Checking for Errors

Any errors that occur are thrown as a QuantoneException. It is therefore recommend to implement some form of error handling to catch these exceptions

try
{
    var qr = myQuantone.Execute(qo);
}
catch (QuantoneException e) 
{
    Console.WriteLine(e.Message);
}

Single Query Result

Lookup query topics return a 'by id' query result object, e.g. a AlbumsByIdQuery would return an AlbumsByIdQueryResult. This query result object contains a single result entity. The type of this entity corresponds to the query topic, so a AlbumsByIdQuery would return an Album. The properties of this entity can then be accessed and used within your own application.

var qr = myQuantone.Execute(qo);
var album = qr.Result;
// Display the details of the album
Console.WriteLine("Id: " + album.id);
Console.WriteLine("Title: " + album.title);
Console.WriteLine("ArtistsLiteral: " + album.artistsLiteral);
Console.WriteLine("Artists: " + album.artists);
Console.WriteLine("OriginalReleaseDate: " + album.originalReleaseDate);
Console.WriteLine("Format: " + album.format);
Console.WriteLine("IsLive: " + album.isLive);
Console.WriteLine("IsUnofficial: " + album.isUnofficial);
Console.WriteLine("Genres: " + album.genres);
Console.WriteLine("ImageId: " + album.imageId);
Console.WriteLine("Participations: " + album.participations);
Console.WriteLine("Identifiers: " + album.identifiers);
Console.WriteLine("Recordings: " + album.recordings);
Console.WriteLine("Releases: " + album.releases);

Search Query Result

Search queries return a query result object, e.g. a AlbumsQuery would return an AlbumsQueryResult. This query object contains an array of result entities. The type of this again corresponds to the topic, so a AlbumsQuery would return a Album[].

var qr = myQuantone.Execute(qo);
var albums = qr.Result;
foreach (var album in albums)
{ 
    // Display the details of the album
    Console.WriteLine("Id: " + album.id);
    Console.WriteLine("Title: " + album.title);
    Console.WriteLine("ArtistsLiteral: " + album.artistsLiteral);
    Console.WriteLine("Artists: " + album.artists);
    Console.WriteLine("OriginalReleaseDate: " + album.originalReleaseDate);
    Console.WriteLine("Format: " + album.format);
    Console.WriteLine("IsLive: " + album.isLive);
    Console.WriteLine("IsUnofficial: " + album.isUnofficial);
    Console.WriteLine("Genres: " + album.genres);
    Console.WriteLine("ImageId: " + album.imageId);
    Console.WriteLine("Participations: " + album.participations);
    Console.WriteLine("Identifiers: " + album.identifiers);
    Console.WriteLine("Recordings: " + album.recordings);
    Console.WriteLine("Releases: " + album.releases);
}

Version History

Version 0.5.1 (current)

  • Bug fixes

Version 0.5.0

  • Support for label and genre queries

Version 0.4.0

  • Support for Location queries

Version 0.3.1

  • Minor bug fixes

Version 0.3.0

  • Overhaul of the authentication and querying process. Authentication now happens when a Quantone class is created, and this Quantone class is used to execute queries. See the examples above for more details
  • Support for Quantone API v3. This includes the renaming and removal of several classes and properties. For a list of items affected, click here
  • Errors are now thrown as a QuantoneException, as opposed to being attached to the result object

Version 0.2.0

  • Revision of the underlying data model to improve the handling of results and make it more compatible with the data model used by the API. For a list of items affected, click here

Version 0.1.3

  • Minor changes to the underlying data model. A full revision will be coming in version 0.2
  • Added the ability to search recordings by artist Id

Version 0.1.2

  • Bug fix: Dependancies have been fixed

Version 0.1.1

  • Bug fix: All classes are now in the QuantoneSDK namespace

Version 0.1.0

  • Supports query building and result handling for Album, Artist and Recording topics

For a full version history, click here

Planned Changes

Below is a list of planned changes for future releases that will likely effect the way you use the Quantone C# SDK. This list is not comprehensive and is subject to change at any time whilst the SDK is in beta release.

  • The underlying object model is currently being re-written, which may result in changes to some Query and Result objects. Expected v0.2 and upwards

Upcoming Features

Below is a list of features planned for future releases of the SDK. This list is not comprehensive. Features and estimated release versions are subject to change at any time.

  • Error codes will be added to the Error object that will be thrown to make identifying errors easier and more reliable. Estimated v0.7
  • Utilties for dealing with paged results. Will include functions for navigating between pages, to a specific page and returning all pages in a single object. Estimated v0.6
  • Support for Image queriesEstimated v0.7

Terms of Use

©Quantone Limited, 2015. May be used freely in unaltered form.

Use of the Quantone API is subject to the following end user license agreement & terms and conditions