Skip to content


Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time



A Ruby wrapper of the API v2.0.

Discogs::Wrapper abstracts all of the boilerplate code needed to interact with the Discogs API. It gives you direct access to the information you need. All methods return a ruby Hash wrapped in a Hashie object with the same structure as documented on the Discogs API website.

The master branch aims to give full support for version 2.0 of the API. If you need support for everything in version 1.0, see the api-v1 branch.


  • Artists
  • Releases
  • Master Releases
  • Labels
  • Images
  • Searching (all of the above)
  • Marketplace
  • User Inventories
  • Orders
  • Fee Calculations
  • Price Suggestions
  • User Profiles
  • Collections
  • Wantlists
  • oAuth
  • Pagination / Sorting


You can read the documentation at this projects RDoc page

The Discogs API is documented here.


You can install the library via Rubygems:

$ gem install discogs-wrapper

Or, if you are using Bundler:

gem "discogs-wrapper"


To use this library, you must supply the name of your application. For example:

require "discogs"

wrapper ="My awesome web app")

Accessing information is easy:

artist          = wrapper.get_artist("329937")
artist_releases = wrapper.get_artist_releases("329937")
release         = wrapper.get_release("1529724")
label           = wrapper.get_label("29515")

# You must be authenticated in order to search. I provide a few ways to do this. See the AUTHENTICATION section below.
auth_wrapper ="My awesome web app", user_token: "my_user_token")
search       ="Necrovore", :per_page => 10, :type => :artist)                          # => "Manilla Road"
artist.members.count                 # => 4            # => "Mark Shelton"
artist.profile                       # => "Heavy Metal band from ..."

artist_releases.releases.count       # => 35
artist_releases.releases.first.title # => "Invasion"

release.title                        # => "Medieval"            # => "New Renaissance Records"
release.formats[0].descriptions[0]   # => "12\""
release.styles                       # => [ "Heavy Metal", "Doom Metal" ]
release.tracklist[1].title           # => "Death is Beauty"                           # => "Monitor (2)"
label.sublabels.count                # => 3

search.pagination.items              # => 2
search.results.first.title           # => "Necrovore"
search.results.first.type            # => "artist"              # => 691078

Many of the API endpoints return further URLs that will yield specific data. To cater for this, the library provides a "raw" method that accepts a valid API URL. For example:

sts_records       = wrapper.get_label(9800)
sts_releases      = wrapper.raw(sts_records.releases_url)
first_sts_release = wrapper.raw(sts_releases.releases[1].resource_url)

first_sts_release.title  # => "I'll Nostra Tempo De La Vita / Having The Time Of Your Life"

You can also add optional querystring overrides to raw calls:

sombre = wrapper.raw("", {"page" => 2})

You can see all implemented methods on this projects RDoc page.


The API uses the name "count" in several places, which is sanitized to "total" in this gem in order to prevent overriding the count attribute of Hash.

For example:

release.rating.count # => Returns number of keys in "rating" Hash. # => Returns total number of ratings as per Discogs API response.


Many of the API endpoints require the user to be authenticated via oAuth. The library provides support for this.

For non user-facing apps (when you only want to authenticate as yourself), you can simply pass your user token (generated from your API dashboard) to the constructor. For example:

wrapper ="Test OAuth", user_token: "my_user_token")
results ="Nick Cave")

For user-facing apps, I've provided a simple Rails application that demonstrates how to perform authenticated requests.

Make sure you've created an "app" in your developer settings on the Discogs website. You will need your consumer key and consumer secret.

Basically, you should preform the "oAuth dance" like so:

# Add an action to initiate the process.
def authenticate
  @discogs     ="Test OAuth")
  request_data = @discogs.get_request_token("YOUR_APP_KEY", "YOUR_APP_SECRET", "")

  session[:request_token] = request_data[:request_token]

  redirect_to request_data[:authorize_url]

# And an action that Discogs will redirect back to.
def callback
  @discogs      ="Test OAuth")
  request_token = session[:request_token]
  verifier      = params[:oauth_verifier]
  access_token  = @discogs.authenticate(request_token, verifier)

  session[:request_token] = nil
  session[:access_token]  = access_token

  @discogs.access_token = access_token

  # You can now perform authenticated requests.

# Once you have it, you can also pass your access_token into the constructor.
def another_action
  @discogs ="Test OAuth", access_token: session[:access_token])

  # You can now perform authenticated requests.


All API endpoints that accept pagination, sorting or other parameters are supported.

Page defaults to 1, page size defaults to 50.

wrapper.get_artist_releases(345211, :page => 2, :per_page => 10)

If other params are accepted, they can also be passed:

wrapper.get_user_inventory("username", :page => 3, :sort => "price", :sort_order => "asc")


See the LICENCE file. Copyright (c) Andrew Buntine


Thank you for the support