ParkSquare.Discogs 1.0.16

There is a newer version of this package available.
See the version list below for details.
dotnet add package ParkSquare.Discogs --version 1.0.16
NuGet\Install-Package ParkSquare.Discogs -Version 1.0.16
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="ParkSquare.Discogs" Version="1.0.16" />
For projects that support PackageReference, copy this XML node into the project file to reference the package.
paket add ParkSquare.Discogs --version 1.0.16
#r "nuget: ParkSquare.Discogs, 1.0.16"
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
// Install ParkSquare.Discogs as a Cake Addin
#addin nuget:?package=ParkSquare.Discogs&version=1.0.16

// Install ParkSquare.Discogs as a Cake Tool
#tool nuget:?package=ParkSquare.Discogs&version=1.0.16

C# Discogs Library

Build Status


Discogs is a fully cross-referenced music database of recordings, releases, artists, labels and album artwork. Discogs provides a RESTful API to access this data, and this C# library is the easiest way to consume it so you can build your own Discogs-powered applications for the web, desktop, and mobile devices.

Discogs Masters & Releases

The Discogs database is organized into 'masters' and 'releases'. The 'master' is the main database record for a particular recording (such as an album). A 'master' can have multiple 'releases', which are variations of the 'master' record. For example, an album may have been released on CD, cassette and vinyl, with different versions in the US Europe. This would give that particular master six different releases. The tracklists may, or may not, differ between releases.

Example Master 2Pac - All Eyez On Me

Example Releases 4 x Vinyl Double CD

Getting Started

Sign up to get a Discogs account and go to Developer Settings to create a new auth token. Not all endpoints require authentication, however, the rate limit is higher for authenticated users so it will always be passed if you have configured one.

Rate Limits

The rate limit is generally around 60 requests per minute if authenticated, or 25 requests per minute if not. Once this limit has been reached, further calls will respond with 429 Too Many Requests. You should therefore make sure your code handles this, either with some sort of wait/retry or a circuit breaker.

Paged Results

Some of the API calls return paged data, with a maximum of 100 items per page. As such, you will need to either handle these scenarios yourself, or use the built-in convenience methods that automatically handle getting the paged results and presenting them back as one combined dataset.


You must create an implementation of IClientConfig and pass this into the constructor of the ApiQueryBuilder class. The recommended way is to use the .Net Core built-in dependency injection framework, and to bind the properties to your appsettings.json file:

In Startup.cs:

services.AddSingleton<IClientConfig, ClientConfig>();

In your application, create a config class:

public class ClientConfig : IClientConfig
    public ClientConfig(IConfiguration configuration)
        configuration.Bind("DiscogsClient", this);

    public string AuthToken { get; set; }

    public string BaseUrl { get; set; }

In appsettings.json:

  "DiscogsClient": {
    "AuthToken": "your-auth-token-here",
    "BaseUrl": ""

This method is not mandatory, you can pass in any implementation of the configuration interface, for example the values could just as easily be hardcoded:

public class HardCodedClientConfig : IClientConfig
    public string AuthToken => "your-auth-token";

    public string BaseUrl => "";

Usage Examples

Discogs Client

All calls are made via the DiscogsClient object, which can be instantiated manually or using Dependency Injection (recommended).

Manual construction

var client = new DiscogsClient(
    new HttpClient(new HttpClientHandler()),
    new ApiQueryBuilder(new ClientConfig()));

Dependency injection

Add these lines to your Startup.cs:

services.AddSingleton<IApiQueryBuilder, ApiQueryBuilder>();

services.AddSingleton<IClientConfig, ClientConfig>();

services.AddHttpClient<IDiscogsClient, DiscogsClient>()
    .ConfigurePrimaryHttpMessageHandler(_ =>
        new HttpClientHandler
            AutomaticDecompression = DecompressionMethods.GZip | DecompressionMethods.Deflate

The last line registers a typed HttpClient for the DiscogsClient to use, and requires the following package:


There is a detailed discussion on using dependency injection with HttpClient here.

There are three methods for searching the database, each one will return matching releases from the Discogs database. Each of these releases will have a ReleaseId and also the MasterId of the master record that it is linked to.

Task<SearchResults> SearchAsync(SearchCriteria criteria);
Task<SearchResults> SearchAsync(SearchCriteria criteria, PageOptions pageOptions);  
Task<SearchResults> SearchAllAsync(SearchCriteria criteria);

The SearchAsync() methods allow specifying search criteria and optional pagination options. If no pagination options are passed, then the defaults will be used which returns the first page up to a maximum of 100 items.

Calling SearchAllAsync() automatically handles making multiple calls if necessary to retrieve all items, and the combining of the paged results into one dataset.

var searchResult = await _client.SearchAllAsync(new SearchCriteria
    Artist = "2Pac",
    ReleaseTitle = "All Eyez On Me",

The available search fields in full are as follows, with examples:

  • Artist Pet Shop Boys
  • ReleaseTitle Use Your Illusion II
  • Title Queen - Greatest Hits
  • Query cornershop
  • Year 1998
  • Track Coma
  • Barcode 111234
  • CatalogNumber XASIOIJH
  • Country UK
  • Format CD

Note that using 'Query' is akin to performing a free text search and 'Title' is generally in the format 'Artist - Title'.

Master Release

The master release can be retrieved using the MasterId returned by a search. This will contain the ReleaseId of whichever release is considered to be the 'main' one, usually the one that is chronologically the earliest. It will also provide the ReleaseId of the most recent (i.e. chronologically latest) release that has been linked to that master.

var master = await _client.GetMasterReleaseAsync(firstFoundMasterId);


Master Release Versions are a set of all Releases that are a version of the Master Release. Similar to Search, this method has optional pagination properties:

Task<VersionResults> GetVersionsAsync(VersionsCriteria criteria);

Task<VersionResults> GetVersionsAsync(VersionsCriteria criteria, PageOptions pageOptions);

Task<VersionResults> GetAllVersionsAsync(VersionsCriteria criteria);

Also similar to Search, you can omit the pagination properties, or call GetAllVersionsAsync() to automatically handle retrieving and combining paged results.

var versions = await _client.GetAllVersionsAsync(new VersionsCriteria(firstFoundMasterId));

The result of the Versions methods contains information on the available filters, and how many items of each filter type are present in the dataset. The criteria object allow you to add filters for: format, label, release year and country.


Release represents a particular physical or digital object released by one or more artists, and is where the bulk of the information about a recording is held.

var release = await _client.GetReleaseAsync(master.MainReleaseId);

Advanced Configuration

Handling Rate Limiting

You can use the excellent Polly library to automatically add retries and a circuit breaker pattern to your Discogs calls. This example exponentially backs off making calls and then gives up after three attempts. It will also break the circuit and stop making calls altogether if 3 failures are returned within a 15 second period.

services.AddHttpClient<IDiscogsClient, DiscogsClient>()
        .OrResult(msg => msg.StatusCode == HttpStatusCode.TooManyRequests)
        .WaitAndRetryAsync(3, retryAttempt => TimeSpan.FromSeconds(Math.Pow(2,
        .OrResult(msg => msg.StatusCode == HttpStatusCode.TooManyRequests)
        .CircuitBreakerAsync(3, TimeSpan.FromSeconds(15)
    .ConfigurePrimaryHttpMessageHandler(_ =>
        new HttpClientHandler
            AutomaticDecompression = DecompressionMethods.GZip | DecompressionMethods.Deflate
Product Compatible and additional computed target framework versions.
.NET net5.0 was computed.  net5.0-windows was computed.  net6.0 was computed.  net6.0-android was computed.  net6.0-ios was computed.  net6.0-maccatalyst was computed.  net6.0-macos was computed.  net6.0-tvos was computed.  net6.0-windows was computed.  net7.0 was computed.  net7.0-android was computed.  net7.0-ios was computed.  net7.0-maccatalyst was computed.  net7.0-macos was computed.  net7.0-tvos was computed.  net7.0-windows was computed.  net8.0 was computed.  net8.0-android was computed.  net8.0-browser was computed.  net8.0-ios was computed.  net8.0-maccatalyst was computed.  net8.0-macos was computed.  net8.0-tvos was computed.  net8.0-windows was computed. 
.NET Core netcoreapp3.0 was computed.  netcoreapp3.1 was computed. 
.NET Standard netstandard2.1 is compatible. 
MonoAndroid monoandroid was computed. 
MonoMac monomac was computed. 
MonoTouch monotouch was computed. 
Tizen tizen60 was computed. 
Xamarin.iOS xamarinios was computed. 
Xamarin.Mac xamarinmac was computed. 
Xamarin.TVOS xamarintvos was computed. 
Xamarin.WatchOS xamarinwatchos was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages

This package is not used by any NuGet packages.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last updated
1.0.35 186 10/8/2023
1.0.34 1,460 8/22/2022
1.0.33 374 8/22/2022
1.0.31 358 8/19/2022
1.0.30 616 4/14/2022
1.0.28 462 2/19/2022
1.0.26 431 1/27/2022
1.0.24 413 1/12/2022
1.0.22 6,062 11/24/2021
1.0.20 4,922 11/23/2021
1.0.18 4,711 11/23/2021
1.0.16 6,433 11/23/2021
1.0.15 274 11/22/2021
1.0.14 679 11/21/2021
1.0.13 1,052 11/21/2021
1.0.12 1,308 11/21/2021
1.0.9 1,354 11/20/2021