ParkSquare.Gracenote 2.0.14

C# Gracenote Music Database Library

Background

This library provides access to the Gracenote music database, with support for track, album, artist and cover artwork searching.

Given the difficulty in obtaining new keys to access the Gracenote APIs, we will no longer be actively developing or supporting this Nuget package from 1 May 2021. Most of the original Gracenote Developer links are now dead. We recommend you use Discogs instead for your programmatic music metadata needs, using our Discogs Nuget Package.

Getting Started

The Gracenote Developer license is free for non-commercial use.

This C# library supports ALBUM_SEARCH and ALBUM_FETCH, with all options available that are exposed by the Gracenote API itself. For more information, visit the Gracenote Developer Zone.

To begin development, the first thing you need to do is get a Client ID - a Gracenote API key that authorizes you to make calls to the Gracenote service. See Gracenote Developer Zone for further information. Once you have a Client ID, calling the Web API using ParkSquare.Gracenote is really easy.

Create a GracenoteClient

First, instantiate a new GracenoteClient object, passing in your API key:

var client = new GracenoteClient("1111111-AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA");

You can now perform an album search, or an album fetch.

Search for an Album

This perform a search of the Gracenote database. It is possible to specify any combination of Album Title, Artist or Track Title. There are three search modes available:

• Default - Returns all matching albums
• BestMatch - Returns a single album that best matches your search criteria
• BestMatchWithCover - As per BestMatch but also return the URL to an album art image, if available.

There are various other options that can include additional information about the album in the search results. Multiple flags can be specified.

var x = client.Search(new SearchCriteria
    {
        AlbumTitle = "Use Your Illusion",
        Artist = "Guns 'n' Roses",
        SearchMode = SearchMode.BestMatchWithCoverArt,
        SearchOptions = SearchOptions.Mood | SearchOptions.Tempo
    });

A wider search for all albums by the specified artist, with an image of the artist instead of the album artwork (if available):

var y = client.Search(new SearchCriteria
    {
        Artist = "Pet Shop Boys",
        SearchMode = SearchMode.BestMatchWithCoverArt,
        SearchOptions = SearchOptions.Cover | SearchOptions.ArtistImage
    });

Get Album Metadata

This is used when you already have the GracenoteId for an album and just want to retrieve it.

// Fetch an album using a known Gracenote ID
var x = client.Search("99337157-E1ED6101A3666CFD7D799529ED707E0F");

Download Album Artwork

If you have specified that you want artwork returned, and artwork is available, then you will see a collection of Artwork objects available to you. These will generally contain URLs to a CDN containing the image.

You can call the Download() method on any Artwork object to retrieve the image and save it to your local file system.

var test = client.Search(new SearchCriteria
{
    Artist = "Guns 'n' Roses",
    TrackTitle = "November Rain",
    SearchMode = SearchMode.BestMatchWithCoverArt,
    SearchOptions = SearchOptions.ArtistImage
});

test.Albums.First().Artwork.First().Download("C:\temp\AlbumArt.jpg");

Paging

Where a search yields many results, or it is desirable to page through the results, you can specify a start item and end item in your request. For example, this will return only the 10th to 14th results in the response:

var k = client.Search(new SearchCriteria
{
    Artist = "Guns 'n' Roses",
    Range = new Range(10, 14)
});