API#

class minim.discogs.API(*, consumer_key: str = None, consumer_secret: str = None, flow: str = None, browser: bool = False, web_framework: str = None, port: int | str = 8888, redirect_uri: str = None, access_token: str = None, access_token_secret: str = None, overwrite: bool = False, save: bool = True)[source]#

Bases: object

Discogs API client.

The Discogs API lets developers build their own Discogs-powered applications for the web, desktop, and mobile devices. It is a RESTful interface to Discogs data and enables accessing JSON- formatted information about artists, releases, and labels, managing user collections and wantlists, creating marketplace listings, and more.

See also

To get client credentials, see the Registration section of the Authentication page of the Discogs API website. To take advantage of Minim’s automatic access token retrieval functionality for the OAuth 1.0a flow, the redirect URI should be in the form http://localhost:{port}/callback, where {port} is an open port on localhost.

To view and make changes to account information and resources, users must either provide a personal access token to this class’s constructor as a keyword argument or undergo the OAuth 1.0a flow, which require valid client credentials, using Minim. If an existing OAuth access token/secret pair is available, it can be provided to this class’s constructor as keyword arguments to bypass the access token retrieval process.

Tip

The authorization flow and access token can be changed or updated at any time using set_flow() and set_access_token(), respectively.

Minim also stores and manages access tokens and their properties. When the OAuth 1.0a flow is used to acquire an access token/secret pair, it is automatically saved to the Minim configuration file to be loaded on the next instantiation of this class. This behavior can be disabled if there are any security concerns, like if the computer being used is a shared device.

Parameters:

consumer_keystr, keyword-only, optional

Consumer key. Required for the OAuth 1.0a flow, and can be used in the Discogs authorization flow alongside a consumer secret. If it is not stored as DISCOGS_CONSUMER_KEY in the operating system’s environment variables or found in the Minim configuration file, it can be provided here.

consumer_secretstr, keyword-only, optional

Consumer secret. Required for the OAuth 1.0a flow, and can be used in the Discogs authorization flow alongside a consumer key. If it is not stored as DISCOGS_CONSUMER_SECRET in the operating system’s environment variables or found in the Minim configuration file, it can be provided here.

flowstr, keyword-only, optional

Authorization flow. If None and no access token is provided, no user authentication will be performed and client credentials will not be attached to requests, even if found or provided.

Valid values:

None for no user authentication.
"discogs" for the Discogs authentication flow.
"oauth" for the OAuth 1.0a flow.

browserbool, keyword-only, default: False

Determines whether a web browser is automatically opened for the OAuth 1.0a flow. If False, users will have to manually open the authorization URL and provide the full callback URI via the terminal.

web_frameworkstr, keyword-only, optional

Determines which web framework to use for the OAuth 1.0a flow.

Valid values:

"http.server" for the built-in implementation of HTTP servers.
"flask" for the Flask framework.
"playwright" for the Playwright framework by Microsoft.

portint or str, keyword-only, default: 8888

Port on localhost to use for the OAuth 1.0a flow with the http.server and Flask frameworks. Only used if redirect_uri is not specified.

redirect_uristr, keyword-only, optional

Redirect URI for the OAuth 1.0a flow. If not on localhost, the automatic request access token retrieval functionality is not available.

access_tokenstr, keyword-only, optional

Personal or OAuth access token. If provided here or found in the Minim configuration file, the authentication process is bypassed.

access_token_secretstr, keyword-only, optional

OAuth access token secret accompanying access_token.

overwritebool, keyword-only, default: False

Determines whether to overwrite an existing access token in the Minim configuration file.

savebool, keyword-only, default: True

Determines whether newly obtained access tokens and their associated properties are stored to the Minim configuration file.

Attributes:

API_URLstr: Base URL for the Discogs API.
ACCESS_TOKEN_URLstr: URL for the OAuth 1.0a access token endpoint.
AUTH_URLstr: URL for the OAuth 1.0a authorization endpoint.
REQUEST_TOKEN_URLstr: URL for the OAuth 1.0a request token endpoint.
sessionrequests.Session: Session used to send requests to the Discogs API.

Methods

`add_collection_folder_release`	User Collection > Add To Collection Folder: Add a release to a folder in a user's collection.
`add_order_message`	Marketplace > List Order Messages > Add New Message: Adds a new message to the order's message log.
`create_collection_folder`	User Collection > Collection > Create Folder: Create a new folder in a user's collection.
`create_listing`	Marketplace > New Listing: Create a marketplace listing.
`delete_collection_folder`	User Collection > Collection Folder > Delete Folder: Delete a folder from a user's collection.
`delete_collection_folder_release`	User Collection > Delete Instance From Folder: Remove an instance of a release from a user's collection folder.
`delete_listing`	Marketplace > Listing > Delete Listing: Permanently remove a listing from the marketplace.
`delete_user_release_rating`	Database > Release Rating By User > Delete Release Rating By User: Deletes the release's rating for a given user.
`download_inventory_export`	Inventory Export > Download An Export: Download the results of an inventory export.
`edit_collection_folder_release`	User Collection > Change Rating Of Release: Change the rating on a release and/or move the instance to another folder.
`edit_collection_release_field`	User Collection > Edit Fields Instance: Change the value of a notes field on a particular instance.
`edit_listing`	Marketplace > Listing > Edit Listing: Edit the data associated with a listing.
`edit_order`	Marketplace > Order > Edit Order: Edit the data associated with an order.
`edit_profile`	User Identity > Profile > Edit Profile: Edit a user's profile data.
`export_inventory`	Inventory Export > Export Your Inventory: Request an export of your inventory as a CSV.
`get_artist`	Database > Artist: Get an artist.
`get_artist_releases`	Database > Artist Releases: Get an artist's releases and masters.
`get_collection_fields`	User Collection > Collection Fields: Retrieve a list of user-defined collection notes fields.
`get_collection_folder`	User Collection > Collection Folder > Get Folders: Retrieve metadata about a folder in a user's collection.
`get_collection_folder_releases`	User Collection > Collection Items By Folder: Returns the items in a folder in a user's collection.
`get_collection_folders`	User Collection > Collection > Get Collection Folders: Retrieve a list of folders in a user's collection.
`get_collection_folders_by_release`	User Collection > Collection Items By Release: View the user's collection folders which contain a specified release.
`get_collection_value`	User Collection > Collection Value: Returns the minimum, median, and maximum value of a user's collection.
`get_community_release_rating`	Database > Community Release Rating: Retrieves the community release rating average and count.
`get_fee`	Marketplace > Fee with currency: Calculates the fee for selling an item on the marketplace given a particular currency.
`get_identity`	User Identity > Identity: Retrieve basic information about the authenticated user.
`get_inventory`	Marketplace > Inventory: Get a seller's inventory.
`get_inventory_export`	Inventory Export > Get An Export: Get details about the status of an inventory export.
`get_inventory_exports`	Inventory Export > Get Recent Exports: Get all recent exports of your inventory.
`get_label`	Database > Label: Get a label, company, recording studio, locxation, or other entity involved with artists and releases.
`get_label_releases`	Database > Label Releases: Get a list of releases associated with the label.
`get_listing`	Marketplace > Listing: View marketplace listings.
`get_master_release`	Database > Master Release: Get a master release.
`get_master_release_versions`	Database > Master Release Versions: Retrieves a list of all releases that are versions of this master.
`get_order`	Marketplace > Order > Get Order: View the data associated with an order.
`get_order_messages`	Marketplace > List Order Messages > List Order Messages: Returns a list of the order's messages with the most recent first.
`get_price_suggestions`	Marketplace > Price Suggestions: Retrieve price suggestions in the user's selling currency for the provided release ID.
`get_profile`	User Identity > Profile > Get Profile: Retrieve a user by username.
`get_release`	Database > Release: Get a release (physical or digital object released by one or more artists).
`get_release_marketplace_stats`	Marketplace > Release Statistics: Retrieve marketplace statistics for the provided release ID.
`get_release_stats`	Database > Release Stats: Retrieves the release's "have" and "want" counts.
`get_user_contributions`	User Identity > User Contributions: Retrieve a user's contributions (releases, labels, artists) by username.
`get_user_orders`	Marketplace > List Orders: Returns a list of the authenticated user's orders.
`get_user_release_rating`	Database > Release Rating By User > Get Release Rating By User: Retrieves the release's rating for a given user.
`get_user_submissions`	User Identity > User Submissions: Retrieve a user's submissions (edits made to releases, labels, and artists) by username.
`rename_collection_folder`	User Collection > Collection Folder > Edit Folder: Rename a folder.
`search`	Database > Search: Issue a search query to the Discogs database.
`set_access_token`	Set the Discogs API personal or OAuth access token (and secret).
`set_flow`	Set the authorization flow.
`update_user_release_rating`	Database > Release Rating By User > Update Release Rating By User: Updates the release's rating for a given user.

add_collection_folder_release(folder_id: int, release_id: int, *, username: str = None) → dict[str, int | str][source]#

User Collection > Add To Collection Folder: Add a release to a folder in a user’s collection.

The folder_id must be non-zero. You can use 1 for “Uncategorized”.

User authentication

Requires user authentication with a personal access token or via the OAuth 1.0a flow.

Parameters:

folder_idint

The ID of the folder to modify.

Example: 3.

release_idint

The ID of the release you are adding.

Example: 130076.

usernamestr, keyword-only, optional

The username of the collection you are trying to modify. If not specified, the username of the authenticated user is used.

Example: "rodneyfool".

Returns:

folderdict

Information about the folder.

Sample

{
  "instance_id": <int>,
  "resource_url": <str>
}

add_order_message(order_id: str, message: str = None, status: str = None) → dict[str, Any][source]#

Marketplace > List Order Messages > Add New Message: Adds a new message to the order’s message log.

When posting a new message, you can simultaneously change the order status. IF you do, the message will automatically be prepended with:

Seller changed status from […] to […]

While message and status are each optional, one or both must be present.

User authentication

Requires user authentication with a personal access token or via the OAuth 1.0a flow.

Parameters:

order_idstr

The ID of the order you are fetching.

Example: 1-1.

messagestr, optional

The message you are posting.

Example: "hello world"

statusstr, optional

The status of the order you are updating.

Valid values: "New Order", "Buyer Contacted", "Invoice Sent", "Payment Pending", "Payment Received", "In Progress", "Shipped", "Refund Sent", "Cancelled (Non-Paying Buyer)", "Cancelled (Item Unavailable)", and "Cancelled (Per Buyer's Request)".

Returns:

messagedict

The order’s message.

Sample

{
  "from": {
    "username": <str>,
    "resource_url": <str>
  },
  "message": <str>,
  "order": {
    "resource_url": <str>,
    "id": <str>
  },
  "timestamp": <str>,
  "subject": <str>
}

create_collection_folder(name: str) → dict[str, int | str][source]#

User Collection > Collection > Create Folder: Create a new folder in a user’s collection.

User authentication

Requires user authentication with a personal access token or via the OAuth 1.0a flow.

Parameters:

namestr

The name of the newly-created folder.

Example: "My favorites".

Returns:

folderdict

Information about the newly-created folder.

Sample

{
  "id": <int>,
  "name": <str>,
  "count": <int>,
  "resource_url": <str>
}

create_listing(release_id: int | str, condition: str, price: float, status: str = 'For Sale', *, sleeve_condition: str = None, comments: str = None, allow_offers: bool = None, external_id: str = None, location: str = None, weight: float = None, format_quantity: int = None) → dict[str, Any][source]#

Marketplace > New Listing: Create a marketplace listing.

User authentication

Requires user authentication with a personal access token or via the OAuth 1.0a flow.

Parameters:

release_idint or str

The ID of the release you are posting.

Example: 249504.

conditionstr

The condition of the release you are posting.

Valid values: "Mint (M)", "Near Mint (NM or M-)", "Very Good Plus (VG+)", "Very Good (VG)", "Good Plus (G+)", "Good (G)", "Fair (F)", and "Poor (P)".

pricefloat

The price of the item (in the seller’s currency).

Example: 10.00.

statusstr, default: "For Sale"

The status of the listing.

Valid values: "For Sale" (the listing is ready to be shwon on the marketplace) and "Draft" (the listing is not ready for public display).

sleeve_conditionstr, optional

The condition of the sleeve of the item you are posting.

Valid values: "Mint (M)", "Near Mint (NM or M-)", "Very Good Plus (VG+)", "Very Good (VG)", "Good Plus (G+)", "Good (G)", "Fair (F)", and "Poor (P)".

commentsstr, optional

Any remarks about the item that will be displated to buyers.

allow_offersbool, optional

Whether or not to allow buyers to make offers on the item.

Default: False.

external_idstr, optional

A freeform field that can be used for the seller’s own reference. Information stored here will not be displayed to anyone other than the seller. This field is called “Private Comments” on the Discogs website.

locationstr, optional

A freeform field that is intended to help identify an item’s physical storage location. Information stored here will not be displayed to anyone other than the seller. This field will be visible on the inventory management page and will be available in inventory exports via the website.

weightfloat, optional

The weight, in grams, of this listing, for the purpose of calculating shipping. Set this field to "auto" to have the weight automatically estimated for you.

format_quantityint, optional

The number of items this listing counts as, for the purpose of calculating shipping. This field is called “Counts As” on the Discogs website. Set this field to "auto" to have the quantity automatically estimated for you.

delete_collection_folder(folder_id: int, *, username: str = None) → None[source]#

User Collection > Collection Folder > Delete Folder: Delete a folder from a user’s collection.

A folder must be empty before it can be deleted.

User authentication

Requires user authentication with a personal access token or via the OAuth 1.0a flow.

Parameters:

folder_idint

The ID of the folder to delete.

Example: 3.

usernamestr, keyword-only, optional

The username of the collection you are trying to delete. If not specified, the username of the authenticated user is used.

Example: "rodneyfool".

delete_collection_folder_release(folder_id: int, release_id: int, instance_id: int, *, username: str = None) → None[source]#

User Collection > Delete Instance From Folder: Remove an instance of a release from a user’s collection folder.

To move the release to the “Uncategorized” folder instead, use the edit_collection_folder_release() method.

User authentication

Requires user authentication with a personal access token or via the OAuth 1.0a flow.

Parameters:

folder_idint

The ID of the folder to modify.

Example: 3.

release_idint

The ID of the release you are modifying.

Example: 130076.

instance_idint

The ID of the instance.

Example: 1.

usernamestr, keyword-only, optional

The username of the collection you are trying to modify. If not specified, the username of the authenticated user is used.

Example: "rodneyfool".

delete_listing(listing_id: int | str) → None[source]#

Marketplace > Listing > Delete Listing: Permanently remove a listing from the marketplace.

User authentication

Requires user authentication with a personal access token or via the OAuth 1.0a flow.

Parameters:

listing_idint or str

The ID of the listing you are fetching.

Example: 172723812.

delete_user_release_rating(release_id: int | str, username: str = None) → None[source]#

Database > Release Rating By User > Delete Release Rating By User: Deletes the release’s rating for a given user.

User authentication

Requires user authentication with a personal access token or via the OAuth 1.0a flow.

Parameters:

release_idint or str

The release ID.

Example: 249504.

usernamestr, optional

The username of the user whose rating you are requesting. If not specified, the username of the authenticated user is used.

Example: "memory".

download_inventory_export(export_id: int, *, filename: str = None, path: str = None) → str[source]#

Inventory Export > Download An Export: Download the results of an inventory export.

User authentication

Requires user authentication with a personal access token or via the OAuth 1.0a flow.

Parameters:

export_idint: ID of the export.
filenamestr, optional: Filename of the exported CSV file. A .csv extension will be appended if not present. If not specified, the CSV file is saved as <username>-inventory-<date>-<number>.csv.
pathstr, optional: Path to save the exported CSV file. If not specified, the file is saved in the current working directory.

Returns:

pathstr: Full path to the exported CSV file.

edit_collection_folder_release(folder_id: int, release_id: int, instance_id: int, *, username: str = None, new_folder_id: int, rating: int = None) → None[source]#

User Collection > Change Rating Of Release: Change the rating on a release and/or move the instance to another folder.

This endpoint potentially takes two folder ID parameters: folder_id (which is the folder you are requesting, and is required), and new_folder_id (representing the folder you want to move the instance to, which is optional).

User authentication

Requires user authentication with a personal access token or via the OAuth 1.0a flow.

Parameters:

folder_idint

The ID of the folder to modify.

Example: 3.

release_idint

The ID of the release you are modifying.

Example: 130076.

instance_idint

The ID of the instance.

Example: 1.

usernamestr, keyword-only, optional

The username of the collection you are trying to modify. If not specified, the username of the authenticated user is used.

Example: "rodneyfool".

new_folder_idint

The ID of the folder to move the instance to.

Example: 4.

ratingint, keyword-only, optional

The rating of the instance you are supplying.

Example: 5.

edit_collection_release_field(folder_id: int, release_id: int, instance_id: int, field_id: int, value: str, *, username: str = None) → None[source]#

User Collection > Edit Fields Instance: Change the value of a notes field on a particular instance.

User authentication

Requires user authentication with a personal access token or via the OAuth 1.0a flow.

Parameters:

folder_idint

The ID of the folder to modify.

Example: 3.

release_idint

The ID of the release you are modifying.

Example: 130076.

instance_idint

The ID of the instance.

Example: 1.

field_idint

The ID of the field you are modifying.

Example: 1.

valuestr

The new value of the field. If the field’s type is "dropdown", value must match one of the values in the field’s list of options.

usernamestr, keyword-only, optional

The username of the collection you are trying to modify. If not specified, the username of the authenticated user is used.

Example: "rodneyfool".

edit_listing(listing_id: int | str, release_id: int | str, condition: str, price: float, status: str = 'For Sale', *, sleeve_condition: str = None, comments: str = None, allow_offers: bool = None, external_id: str = None, location: str = None, weight: float = None, format_quantity: int = None) → None[source]#

Marketplace > Listing > Edit Listing: Edit the data associated with a listing.

If the listing’s status is not "For Sale", "Draft", or "Expired", it cannot be modified—only deleted. To re-list a "Sold" listing, a new listing must be created.

User authentication

Requires user authentication with a personal access token or via the OAuth 1.0a flow.

Parameters:

listing_idint or str

The ID of the listing you are fetching.

Example: 172723812.

release_idint or str

The ID of the release you are posting.

Example: 249504.

conditionstr

The condition of the release you are posting.

Valid values: "Mint (M)", "Near Mint (NM or M-)", "Very Good Plus (VG+)", "Very Good (VG)", "Good Plus (G+)", "Good (G)", "Fair (F)", and "Poor (P)".

pricefloat

The price of the item (in the seller’s currency).

Example: 10.00.

statusstr, default: "For Sale"

The status of the listing.

Valid values: "For Sale" (the listing is ready to be shwon on the marketplace) and "Draft" (the listing is not ready for public display).

sleeve_conditionstr, optional

The condition of the sleeve of the item you are posting.

Valid values: "Mint (M)", "Near Mint (NM or M-)", "Very Good Plus (VG+)", "Very Good (VG)", "Good Plus (G+)", "Good (G)", "Fair (F)", and "Poor (P)".

commentsstr, optional

Any remarks about the item that will be displated to buyers.

allow_offersbool, optional

Whether or not to allow buyers to make offers on the item.

Default: False.

external_idstr, optional

locationstr, optional

weightfloat, optional

The weight, in grams, of this listing, for the purpose of calculating shipping. Set this field to "auto" to have the weight automatically estimated for you.

format_quantityint, optional

edit_order(order_id: str, status: str, *, shipping: float = None) → dict[str, Any][source]#

Marketplace > Order > Edit Order: Edit the data associated with an order.

The response contains a "next_status" key—an array of valid next statuses for this order.

Changing the order status using this resource will always message the buyer with

Seller changed status from […] to […]

and does not provide a facility for including a custom message along with the change. For more fine-grained control, use the add_order_message() method, which allows you to simultaneously add a message and change the order status. If the order status is not "Cancelled", "Payment Received", or "Shipped", you can change the shipping. Doing so will send an invoice to the buyer and set the order status to "Invoice Sent". (For that reason, you cannot set the shipping and the order status in the same request.)

User authentication

Requires user authentication with a personal access token or via the OAuth 1.0a flow.

Parameters:

order_idstr

The ID of the order you are fetching.

Example: 1-1.

statusstr

The status of the order you are updating. The new status must be present in the order’s "next_status" list.

shippingfloat, optional

The order shipping amount. As a side effect of setting this value, the buyer is invoiced and the order status is set to "Invoice Sent".

Example: 5.00.

Returns:

orderdict

The marketplace order.

Sample

{
  "id": <str>,
  "resource_url": <str>,
  "messages_url": <str>,
  "uri": <str>,
  "status": <str>,
  "next_status": [<str>],
  "fee": {
    "currency": <str>,
    "value": <float>
  },
  "created": <str>,
  "items": [
    {
      "release": {
        "id": <int>,
        "description": <str>,
      },
      "price": {
        "currency": <str>,
        "value": <int>
      },
      "media_condition": <str>,
      "sleeve_condition": <str>,
      "id": <int>
    }
  ],
  "shipping": {
    "currency": <str>,
    "method": <str>,
    "value": <int>
  },
  "shipping_address": <str>,
  "additional_instructions": <str>,
  "archived": <bool>,
  "seller": {
    "resource_url": <str>,
    "username": <str>,
    "id": <int>
  },
  "last_activity": <str>,
  "buyer": {
    "resource_url": <str>,
    "username": <str>,
    "id": <int>
  },
  "total": {
    "currency": <str>,
    "value": <int>
  }
}

edit_profile(*, name: str = None, home_page: str = None, location: str = None, profile: str = None, curr_abbr: str = None) → dict[str, Any][source]#

User Identity > Profile > Edit Profile: Edit a user’s profile data.

User authentication

Requires user authentication with a personal access token or via the OAuth 1.0a flow.

Parameters:

namestr, keyword-only, optional

The real name of the user.

Example: "Nicolas Cage".

home_pagestr, keyword-only, optional

The user’s website.

Example: "www.discogs.com".

locationstr, keyword-only, optional

The geographical location of the user.

Example: "Portland".

profilestr, keyword-only, optional

Biological information about the user.

Example: "I am a Discogs user!".

curr_abbrstr, keyword-only, optional

Currency abbreviation for marketplace data.

Valid values: "USD", "GBP", "EUR", "CAD", "AUD", "JPY", "CHF", "MXN", "BRL", "NZD", "SEK", and "ZAR".

Returns:

profiledict

Updated profile.

Sample

{
  "id": <int><int>,
  "username": <str>,
  "name": <str>,
  "email": <str>,
  "resource_url": <str>,
  "inventory_url": <str>,
  "collection_folders_url": <str>,
  "collection_fields_url": <str>,
  "wantlist_url": <str>,
  "uri": <str>,
  "profile": <str>,
  "home_page": <str>,
  "location": <str>,
  "registered": <str>,
  "num_lists": <int>,
  "num_for_sale": <int>,
  "num_collection": <int>,
  "num_wantlist": <int>,
  "num_pending": <int>,
  "releases_contributed": <int>,
  "rank": <int>,
  "releases_rated": <int>,
  "rating_avg": <float>
}

export_inventory(*, download: bool = True, filename: str = None, path: str = None) → str[source]#

Inventory Export > Export Your Inventory: Request an export of your inventory as a CSV.

User authentication

Requires user authentication with a personal access token or via the OAuth 1.0a flow.

Parameters:

downloadbool, keyword-only, default: True: Specifies whether to download the CSV file. If False, the export ID is returned.
filenamestr, optional: Filename of the exported CSV file. A .csv extension will be appended if not present. If not specified, the CSV file is saved as <username>-inventory-<date>-<number>.csv.
pathstr, optional: Path to save the exported CSV file. If not specified, the file is saved in the current working directory.

Returns:

path_or_idstr: Full path to the exported CSV file (download=True) or the export ID (download=False).

get_artist(artist_id: int | str) → dict[str, Any][source]#

Database > Artist: Get an artist.

Parameters:

artist_idint or str

The artist ID.

Example: 108713.

Returns:

artistdict

Discogs database information for a single artist.

Sample

{
  "namevariations": [<str>],
  "profile": <str>,
  "releases_url": <str>,
  "resource_url": <str>,
  "uri": <str>,
  "urls": [<str>],
  "data_quality": <str>,
  "id": <int>,
  "images": [
    {
      "height": <int>,
      "resource_url": <str>,
      "type": <str>,
      "uri": <str>,
      "uri150": <str>,
      "width": <int>
    }
  ],
  "members": [
    {
      "active": <bool>,
      "id": <int>,
      "name": <str>,
      "resource_url": <str>
    }
  ]
}

get_artist_releases(artist_id: int | str, *, page: int | str = None, per_page: int | str = None, sort: str = None, sort_order: str = None) → dict[str, Any][source]#

Database > Artist Releases: Get an artist’s releases and masters.

Parameters:

artist_idint or str

The artist ID.

Example: 108713.

pageint or str, keyword-only, optional

Page of results to fetch.

per_pageint or str, keyword-only, optional

Number of results per page.

sortstr, keyword-only, optional

Sort results by this field.

Valid values: "year", "title", and "format".

sort_orderstr, keyword-only, optional

Sort results in a particular order.

Valid values: "asc" and "desc".

Returns:

releasesdict

Discogs database information for all releases by the specified artist.

Sample

{
  "pagination": {
    "items": <int>,
    "page": <int>,
    "pages": <int>,
    "per_page": <int>,
    "urls": {
      "last": <str>,
      "next": <str>
    }
  },
  "releases": [
    {
      "artist": <str>,
      "id": <int>,
      "main_release": <int>,
      "resource_url": <str>,
      "role": <str>,
      "thumb": <str>,
      "title": <str>,
      "type": <str>,
      "year": <int>
    }
  ]
}

get_collection_fields(username: str = None) → list[dict[str, Any]][source]#

User Collection > Collection Fields: Retrieve a list of user-defined collection notes fields.

These fields are available on every release in the collection.

User authentication

If the collection has been made private by its owner, authentication as the collection owner is required.

If you are not authenticated as the collection owner, only fields with public set to true will be visible.

Parameters:

usernamestr, optional

The username of the collection you are trying to fetch. If not specified, the username of the authenticated user is used.

Example: "rodneyfool".

Returns:

fieldslist

A list of user-defined collection fields.

Sample

[
  {
    "id": <int>,
    "name": <str>,
    "options": [<str>],
    "public": <bool>,
    "position": <int>,
    "type": "dropdown"
  },
  {
    "id": <int>,
    "name": <str>,
    "lines": <int>,
    "public": <bool>,
    "position": <int>,
    "type": "textarea"
  }
]

get_collection_folder(folder_id: int, *, username: str = None) → dict[str, int | str][source]#

User Collection > Collection Folder > Get Folders: Retrieve metadata about a folder in a user’s collection.

User authentication

If folder_id is not 0, authentication as the collection owner is required.

Parameters:

folder_idint

The ID of the folder to request.

Example: 3.

usernamestr, keyword-only, optional

The username of the collection you are trying to request. If not specified, the username of the authenticated user is used.

Example: "rodneyfool".

Returns:

folderdict

Metadata about the folder.

Sample

{
  "id": <int>,
  "name": <str>,
  "count": <int>,
  "resource_url": <str>
}

get_collection_folder_releases(folder_id: int, *, username: str = None, page: int = None, per_page: int = None, sort: str = None, sort_order: str = None) → dict[str, Any][source]#

User Collection > Collection Items By Folder: Returns the items in a folder in a user’s collection.

Basic information about each release is provided, suitable for display in a list. For detailed information, make another call to fetch the corresponding release.

User authentication

If folder_id is not 0 or the collection has been made private by its owner, authentication as the collection owner is required.

If you are not authenticated as the collection owner, only the public notes fields will be visible.

Parameters:

folder_idint

The ID of the folder to request.

Example: 3.

usernamestr, keyword-only, optional

The username of the collection you are trying to request. If not specified, the username of the authenticated user is used.

Example: "rodneyfool".

pageint, keyword-only, optional

Page of results to fetch.

per_pageint, keyword-only, optional

Number of results per page.

sortstr, keyword-only, optional

Sort items by this field.

Valid values: "label", "artist", "title", "catno", "format", "rating", "year", and "added".

sort_orderstr, keyword-only, optional

Sort items in a particular order.

Valid values: "asc" and "desc".

Returns:

itemsdict

Items in the folder.

Sample

{
  "pagination": {
    "per_page": <int>,
    "items": <int>,
    "page": <int>,
    "urls": {
      "last": <str>,
      "next": <str>
    },
    "pages": <int>
  },
  "releases": [
    {
      "instance_id": <int>,
      "rating": <int>,
      "basic_information": {
        "labels": [
          {
            "name": <str>,
            "entity_type": <str>,
            "catno": <str>,
            "resource_url": <str>,
            "id": <int>,
            "entity_type_name": <str>
          }
        ],
        "formats": [
          {
            "descriptions": [<str>],
            "name": <str>,
            "qty": <str>
          }
        ],
        "thumb": <str>,
        "title": <str>,
        "artists": [
          {
            "join": <str>,
            "name": <str>,
            "anv": <str>,
            "tracks": <str>,
            "role": <str>,
            "resource_url": <str>,
            "id": <int>
          }
        ],
        "resource_url": <str>,
        "year": <int>,
        "id": <int>,
      },
      "folder_id": <int>,
      "date_added": <str>,
      "id": <int>
    }
  ]
}

get_collection_folders(username: str = None) → list[dict[str, Any]][source]#

User Collection > Collection > Get Collection Folders: Retrieve a list of folders in a user’s collection.

User authentication

If the collection has been made private by its owner, authentication as the collection owner is required. If you are not authenticated as the collection owner, only folder ID 0 (the “All” folder) will be visible (if the requested user’s collection is public).

Parameters:

usernamestr, optional

The username of the collection you are trying to fetch. If not specified, the username of the authenticated user is used.

Example: "rodneyfool".

Returns:

folderslist

A list of folders in the user’s collection.

Sample

[
  {
    "id": <int>,
    "name": <str>,
    "count": <int>,
    "resource_url": <str>
  }
]

get_collection_folders_by_release(release_id: int | str, *, username: str = None) → dict[str, Any][source]#

User Collection > Collection Items By Release: View the user’s collection folders which contain a specified release. This will also show information about each release instance.

Parameters:

release_idint or str

The ID of the release to request.

Example: 7781525.

usernamestr, keyword-only, optional

The username of the collection you are trying to view. If not specified, the username of the authenticated user is used.

Example: "susan.salkeld".

Returns:

releaseslist

A list of releases and their folders.

Sample

{
  "pagination": {
    "per_page": <int>,
    "items": <int>,
    "page": <int>,
    "urls": {
      "last": <str>,
      "next": <str>
    },
    "pages": <int>
  },
  "releases": [
    {
      "instance_id": <int>,
      "rating": <int>,
      "basic_information": {
        "labels": [
          {
            "name": <str>,
            "entity_type": <str>,
            "catno": <str>,
            "resource_url": <str>,
            "id": <int>,
            "entity_type_name": <str>
          }
        ],
        "formats": [
          {
            "descriptions": [<str>],
            "name": <str>,
            "qty": <str>
          }
        ],
        "thumb": <str>,
        "title": <str>,
        "artists": [
          {
            "join": <str>,
            "name": <str>,
            "anv": <str>,
            "tracks": <str>,
            "role": <str>,
            "resource_url": <str>,
            "id": <int>
          }
        ],
        "resource_url": <str>,
        "year": <int>,
        "id": <int>,
      },
      "folder_id": <int>,
      "date_added": <str>,
      "id": <int>
    }
  ]
}

get_collection_value(username: str = None) → dict[str, Any][source]#

User Collection > Collection Value: Returns the minimum, median, and maximum value of a user’s collection.

User authentication

Requires user authentication with a personal access token or via the OAuth 1.0a flow.

Parameters:

usernamestr, optional

The username of the collection you are trying to fetch. If not specified, the username of the authenticated user is used.

Example: "rodneyfool".

Returns:

valuedict

The total minimum value of the user’s collection.

Sample

{
  "maximum": <str>,
  "median": <str>,
  "minimum": <str>
}

get_community_release_rating(release_id: int | str) → dict[str, Any][source]#

Database > Community Release Rating: Retrieves the community release rating average and count.

Parameters:

release_idint or str

The release ID.

Example: 249504.

Returns:

ratingdict

Community release rating average and count.

Sample

{
  "rating": {
      "count": <int>,
      "average": <float>
  },
  "release_id": <int>
}

get_fee(price: float, *, currency: str = 'USD') → dict[str, Any][source]#

Marketplace > Fee with currency: Calculates the fee for selling an item on the marketplace given a particular currency.

Parameters:

pricefloat

The price of the item (in the seller’s currency).

Example: 10.00.

currencystr, keyword-only, default: "USD"

The currency abbreviation for the fee calculation.

Valid values: "USD", "GBP", "EUR", "CAD", "AUD", "JPY", "CHF", "MXN", "BRL", "NZD", "SEK", and "ZAR".

Returns:

feedict

The fee for selling an item on the marketplace.

Sample

{
  "value": <float>,
  "currency": <str>,
}

get_identity() → dict[str, Any][source]#

User Identity > Identity: Retrieve basic information about the authenticated user.

User authentication

Requires user authentication with a personal access token or via the OAuth 1.0a flow.

You can use this resource to find out who you’re authenticated as, and it also doubles as a good sanity check to ensure that you’re using OAuth correctly.

For more detailed information, make another request for the user’s profile using get_profile().

Returns:

identitydict

Basic information about the authenticated user.

Sample

{
  "id": <int>,
  "username": <str>,
  "resource_url": <str>,
  "consumer_name": <str>
}

get_inventory(username: str = None, *, status: str = None, page: int | str = None, per_page: int | str = None, sort: str = None, sort_order: str = None) → dict[str, Any][source]#

Marketplace > Inventory: Get a seller’s inventory.

User authentication

If you are authenticated as the inventory owner, additional fields will be returned in the response, such as "weight", "format_quantity", "external_id", "location", and "quantity".

Parameters:

usernamestr

The username of the inventory owner. If not specified, the username of the authenticated user is used.

Example: "360vinyl".

statusstr, keyword-only, optional

The status of the listings to return.

Valid values: "For Sale", "Draft", "Expired", "Sold", and "Deleted".

pageint or str, keyword-only, optional

The page you want to request.

Example: 3.

per_pageint or str, keyword-only, optional

The number of items per page.

Example: 25.

sortstr, keyword-only, optional

Sort items by this field.

Valid values: "listed", "price", "item", "artist", "label", "catno", "audio", "status", and "location".

sort_orderstr, keyword-only, optional

Sort items in a particular order.

Valid values: "asc" and "desc".

Returns:

inventorydict

The seller’s inventory.

Sample

{
  "pagination": {
    "page": <int>,
    "pages": <int>,
    "per_page": <int>,
    "items": <int>,
    "urls": {}
  },
  "listings": [
    {
      "status": <str>,
      "price": {
        "currency": <str>,
        "value": <float>
      },
      "allow_offers": <bool>,
      "sleeve_condition": <str>,
      "id": <int>,
      "condition": <str>,
      "posted": <str>,
      "ships_from": <str>,
      "uri": <str>,
      "comments": <str>,
      "seller": {
        "username": <str>,
        "resource_url": <str>,
        "id": <int>
      },
      "release": {
        "catalog_number": <str>,
        "resource_url": <str>,
        "year": <int>,
        "id": <int>,
        "description": <str>,
        "artist": <str>,
        "title": <str>,
        "format": <str>,
        "thumbnail": <str>
      },
      "resource_url": <str>,
      "audio": <bool>
    }
  ]
}

get_inventory_export(export_id: int) → dict[str, int | str][source]#

Inventory Export > Get An Export: Get details about the status of an inventory export.

User authentication

Requires user authentication with a personal access token or via the OAuth 1.0a flow.

Parameters:

export_idint: ID of the export.

Returns:

exportdict

Details about the status of the inventory export.

Sample

{
  "status": <str>,
  "created_ts": <str>,
  "url": <str>,
  "finished_ts": <str>,
  "download_url": <str>,
  "filename": <str>,
  "id": <int>
}

get_inventory_exports(*, page: int = None, per_page: int = None) → dict[str, Any][source]#

Inventory Export > Get Recent Exports: Get all recent exports of your inventory.

User authentication

Requires user authentication with a personal access token or via the OAuth 1.0a flow.

Parameters:

pageint, keyword-only, optional

The page you want to request.

Example: 3.

per_pageint, keyword-only, optional

The number of items per page.

Example: 25.

Returns:

exportsdict

The authenticated user’s inventory exports.

Sample

{
  "items": [
    {
      "status": <str>,
      "created_ts": <str>,
      "url": <str>,
      "finished_ts": <str>,
      "download_url": <str>,
      "filename": <str>,
      "id": <int>
    }
  ],
  "pagination": {
    "per_page": <int>,
    "items": <int>,
    "page": <int>,
    "urls": {
      "last": <str>,
      "next": <str>
    },
    "pages": <int>
  }
}

get_label(label_id: int | str) → dict[str, Any][source]#

Database > Label: Get a label, company, recording studio, locxation, or other entity involved with artists and releases.

Parameters:

label_idint or str

The label ID.

Example: 1.

Returns:

labeldict

Discogs database information for a single label.

Sample

{
  "profile": <str>,
  "releases_url": <str>,
  "name": <str>,
  "contact_info": <str>,
  "uri": <str>,
  "sublabels": [
    {
      "resource_url": <str>,
      "id": <int>,
      "name": <str>
    }
  ],
  "urls": [<str>],
  "images": [
    {
      "height": <int>,
      "resource_url": <str>,
      "type": <str>,
      "uri": <str>,
      "uri150": <str>,
      "width": <int>
    }
  ],
  "resource_url": <str>,
  "id": <int>,
  "data_quality": <str>
}

get_label_releases(label_id: int | str, *, page: int | str = None, per_page: int | str = None) → dict[str, Any][source]#

Database > Label Releases: Get a list of releases associated with the label.

Parameters:

label_idint or str

The label ID.

Example: 1.

pageint or str, keyword-only, optional

Page of results to fetch.

per_pageint or str, keyword-only, optional

Number of results per page.

Returns:

releasesdict

Discogs database information for all releases by the specified label.

Sample

{
  "pagination": {
    "items": <int>,
    "page": <int>,
    "pages": <int>,
    "per_page": <int>,
    "urls": {
      "last": <str>,
      "next": <str>
    }
  },
  "releases": [
    {
      "artist": <str>,
      "catno": <str>,
      "format": <str>,
      "id": <int>,
      "resource_url": <str>,
      "status": <str>,
      "thumb": <str>,
      "title": <str>,
      "year": <int>
    }
  ]
}

get_listing(listing_id: int | str, *, curr_abbr: str = None) → dict[str, Any][source]#

Marketplace > Listing: View marketplace listings.

Parameters:

listing_idint or str

The ID of the listing you are fetching.

Example: 172723812.

curr_abbrstr, keyword-only, optional

Currency abbreviation for marketplace listings. Defaults to the authenticated user’s currency.

Valid values: "USD", "GBP", "EUR", "CAD", "AUD", "JPY", "CHF", "MXN", "BRL", "NZD", "SEK", and "ZAR".

Returns:

listingdict

The marketplace listing.

Sample

{
  "status": <str>,
  "price": {
    "currency": <str>,
    "value": <int>
  },
  "original_price": {
    "curr_abbr": <str>,
    "curr_id": <int>,
    "formatted": <str>,
    "value": <float>
  },
  "allow_offers": <bool>,
  "sleeve_condition": <str>,
  "id": <int>,
  "condition": <str>,
  "posted": <str>,
  "ships_from": <str>,
  "uri": <str>,
  "comments": <str>,
  "seller": {
    "username": <str>,
    "avatar_url": <str>,
    "resource_url": <str>,
    "url": <str>,
    "id": <int>,
    "shipping": <str>,
    "payment": <str>,
    "stats": {
      "rating": <str>,
      "stars": <float>,
      "total": <int>
    }
  },
  "shipping_price": {
    "currency": <str>,
    "value": <float>
  },
  "original_shipping_price": {
    "curr_abbr": <str>,
    "curr_id": <int>,
    "formatted": <str>,
    "value": <float>
  },
  "release": {
    "catalog_number": <str>,
    "resource_url": <str>,
    "year": <int>,
    "id": <int>,
    "description": <str>,
    "thumbnail": <str>,
  },
  "resource_url": <str>,
  "audio": <bool>
}

get_master_release(master_id: int | str) → dict[str, Any][source]#

Database > Master Release: Get a master release.

Parameters:

master_idint or str

The master release ID.

Example: 1000.

Returns:

master_releasedict

Discogs database information for a single master release.

Sample

{
  "styles": [<str>],
  "genres": [<str>],
  "videos": [
    {
      "duration": <int>,
      "description": <str>,
      "embed": <bool>,
      "uri": <str>,
      "title": <str>
    }
  ],
  "title": <str>,
  "main_release": <int>,
  "main_release_url": <str>,
  "uri": <str>,
  "artists": [
    {
      "join": <str>,
      "name": <str>,
      "anv": <str>,
      "tracks": <str>,
      "role": <str>,
      "resource_url": <str>,
      "id": <int>
    }
  ],
  "versions_url": <str>,
  "year": <int>,
  "images": [
    {
      "height": <int>,
      "resource_url": <str>,
      "type": <str>,
      "uri": <str>,
      "uri150": <str>,
      "width": <int>
    }
  ],
  "resource_url": <str>,
  "tracklist": [
    {
      "duration": <str>,
      "position": <str>,
      "type_": <str>,
      "extraartists": [
        {
          "join": <str>,
          "name": <str>,
          "anv": <str>,
          "tracks": <str>,
          "role": <str>,
          "resource_url": <str>,
          "id": <int>
        }
      ],
      "title": <str>
    }
  ],
  "id": <int>,
  "num_for_sale": <int>,
  "lowest_price": <float>,
  "data_quality": <str>
}

get_master_release_versions(master_id: int | str, *, country: str = None, format: str = None, label: str = None, released: str = None, page: int | str = None, per_page: int | str = None, sort: str = None, sort_order: str = None) → dict[str, Any][source]#

Database > Master Release Versions: Retrieves a list of all releases that are versions of this master.

Parameters:

master_idint or str

The master release ID.

Example: 1000.

countrystr, keyword-only, optional

The country to filter for.

Example: "Belgium".

formatstr, keyword-only, optional

The format to filter for.

Example: "Vinyl".

labelstr, keyword-only, optional

The label to filter for.

Example: "Scorpio Music".

releasedstr, keyword-only, optional

The release year to filter for.

Example: "1992".

pageint or str, keyword-only, optional

The page you want to request.

Example: 3.

per_pageint or str, keyword-only, optional

The number of items per page.

Example: 25.

sortstr, keyword-only, optional

Sort items by this field.

Valid values: "released", "title", "format", "label", "catno", and "country".

sort_orderstr, keyword-only, optional

Sort items in a particular order.

Valid values: "asc" and "desc".

Returns:

versionsdict

Discogs database information for all releases that are versions of the specified master.

Sample

{
  "pagination": {
    "items": <int>,
    "page": <int>,
    "pages": <int>,
    "per_page": <int>,
    "urls": {
      "last": <str>,
      "next": <str>
    }
  },
  "versions": [
    {
      "status": <str>,
      "stats": {
        "user": {
          "in_collection": <int>,
          "in_wantlist": <int>
        },
        "community": {
          "in_collection": <int>,
          "in_wantlist": <int>
        }
      },
      "thumb": <str>,
      "format": <str>,
      "country": <str>,
      "title": <str>,
      "label": <str>,
      "released": <str>,
      "major_formats": [<str>],
      "catno": <str>,
      "resource_url": <str>,
      "id": <int>
    }
  ]
}

get_order(order_id: str) → dict[str, Any][source]#

Marketplace > Order > Get Order: View the data associated with an order.

User authentication

Requires user authentication with a personal access token or via the OAuth 1.0a flow.

Parameters:

order_idstr

The ID of the order you are fetching.

Example: 1-1.

Returns:

orderdict

The marketplace order.

Sample

{
  "id": <str>,
  "resource_url": <str>,
  "messages_url": <str>,
  "uri": <str>,
  "status": <str>,
  "next_status": [<str>],
  "fee": {
    "currency": <str>,
    "value": <float>
  },
  "created": <str>,
  "items": [
    {
      "release": {
        "id": <int>,
        "description": <str>,
      },
      "price": {
        "currency": <str>,
        "value": <int>
      },
      "media_condition": <str>,
      "sleeve_condition": <str>,
      "id": <int>
    }
  ],
  "shipping": {
    "currency": <str>,
    "method": <str>,
    "value": <int>
  },
  "shipping_address": <str>,
  "additional_instructions": <str>,
  "archived": <bool>,
  "seller": {
    "resource_url": <str>,
    "username": <str>,
    "id": <int>
  },
  "last_activity": <str>,
  "buyer": {
    "resource_url": <str>,
    "username": <str>,
    "id": <int>
  },
  "total": {
    "currency": <str>,
    "value": <int>
  }
}

get_order_messages(order_id: str, *, page: int | str = None, per_page: int | str = None) → dict[str, Any][source]#

Marketplace > List Order Messages > List Order Messages: Returns a list of the order’s messages with the most recent first.

User authentication

Requires user authentication with a personal access token or via the OAuth 1.0a flow.

Parameters:

order_idstr

The ID of the order you are fetching.

Example: 1-1.

pageint or str, keyword-only, optional

The page you want to request.

Example: 3.

per_pageint or str, keyword-only, optional

The number of items per page.

Example: 25.

Returns:

messagesdict

The order’s messages.

Sample

{
  "pagination": {
    "per_page": <int>,
    "items": <int>,
    "page": <int>,
    "urls": {
      "last": <str>,
      "next": <str>
    },
    "pages": <int>
  },
  "messages": [
    {
      "refund": {
        "amount": <int>,
        "order": {
          "resource_url": <str>,
          "id": <str>
        }
      },
      "timestamp": <str>,
      "message": <str>,
      "type": <str>,
      "order": {
        "resource_url": <str>,
        "id": <str>,
      },
      "subject": <str>
    }
  ]
}

get_price_suggestions(release_id: int | str) → dict[str, Any][source]#

Marketplace > Price Suggestions: Retrieve price suggestions in the user’s selling currency for the provided release ID.

If no suggestions are available, an empty object will be returned.

User authentication

Requires user authentication with a personal access token or via the OAuth 1.0a flow.

Parameters:

release_idint or str

The ID of the release you are fetching.

Example: 249504.

Returns:

pricesdict

The price suggestions for the release.

Sample

{
  "Very Good (VG)": {
    "currency": <str>,
    "value": <float>
  },
  "Good Plus (G+)": {
    "currency": <str>,
    "value": <float>
  },
  "Near Mint (NM or M-)": {
    "currency": <str>,
    "value": <float>
  },
  "Good (G)": {
    "currency": <str>,
    "value": <float>
  },
  "Very Good Plus (VG+)": {
    "currency": <str>,
    "value": <float>
  },
  "Mint (M)": {
    "currency": <str>,
    "value": <float>
  },
  "Fair (F)": {
    "currency": <str>,
    "value": <float>
  },
  "Poor (P)": {
    "currency": <str>,
    "value": <float>
  }
}

get_profile(username: str = None) → dict[str, Any][source]#

User Identity > Profile > Get Profile: Retrieve a user by username.

User authentication

If authenticated as the requested user, the "email" key will be visible, and the "num_lists" count will include the user’s private lists.

If authenticated as the requested user or the user’s collection/wantlist is public, the "num_collection"/"num_wantlist" keys will be visible.

Parameters:

usernamestr, optional

The username of whose profile you are requesting. If not specified, the username of the authenticated user is used.

Example: "rodneyfool".

Returns:

profiledict

Detailed information about the user.

Sample

{
  "profile": <str>,
  "wantlist_url": <str>,
  "rank": <int>,
  "num_pending": <int>,
  "id": <int>,
  "num_for_sale": <int>,
  "home_page": <str>,
  "location": <str>,
  "collection_folders_url": <str>,
  "username": <str>,
  "collection_fields_url": <str>,
  "releases_contributed": <int>,
  "registered": <str>,
  "rating_avg": <float>,
  "num_collection": <int>,
  "releases_rated": <int>,
  "num_lists": <int>,
  "name": <str>,
  "num_wantlist": <int>,
  "inventory_url": <str>,
  "avatar_url": <str>,
  "banner_url": <str>,
  "uri": <str>,
  "resource_url": <str>,
  "buyer_rating": <float>,
  "buyer_rating_stars": <int>,
  "buyer_num_ratings": <int>,
  "seller_rating": <float>,
  "seller_rating_stars": <int>,
  "seller_num_ratings": <int>,
  "curr_abbr": <str>,
}

get_release(release_id: int | str, *, curr_abbr: str = None) → dict[str, Any][source]#

Database > Release: Get a release (physical or digital object released by one or more artists).

Parameters:

release_idint or str

The release ID.

Example: 249504.

curr_abbrstr, keyword-only, optional

Currency abbreviation for marketplace data. Defaults to the authenticated user’s currency.

Valid values: "USD", "GBP", "EUR", "CAD", "AUD", "JPY", "CHF", "MXN", "BRL", "NZD", "SEK", and "ZAR".

Returns:

releasedict

Discogs database information for a single release.

Sample

{
  "title": <str>,
  "id": <int>,
  "artists": [
    {
      "anv": <str>,
      "id": <int>,
      "join": <str>,
      "name": <str>,
      "resource_url": <str>,
      "role": <str>,
      "tracks": <str>
    }
  ],
  "data_quality": <str>,
  "thumb": <str>,
  "community": {
    "contributors": [
      {
        "resource_url": <str>,
        "username": <str>
      }
    ],
    "data_quality": <str>,
    "have": <int>,
    "rating": {
      "average": <float>,
      "count": <int>
    },
    "status": <str>,
    "submitter": {
      "resource_url": <str>,
      "username": <str>
    },
    "want": <int>
  },
  "companies": [
    {
      "catno": <str>,
      "entity_type": <str>,
      "entity_type_name": <str>,
      "id": <int>,
      "name": <str>,
      "resource_url": <str>
    }
  ],
  "country": <str>,
  "date_added": <str>,
  "date_changed": <str>,
  "estimated_weight": <int>,
  "extraartists": [
    {
      "anv": <str>,
      "id": <int>,
      "join": <str>,
      "name": <str>,
      "resource_url": <str>,
      "role": <str>,
      "tracks": <str>
    }
  ],
  "format_quantity": <int>,
  "formats": [
    {
      "descriptions": [<str>],
      "name": <str>,
      "qty": <str>
    }
  ],
  "genres": [<str>],
  "identifiers": [
    {
      "type": <str>,
      "value": <str>
    },
  ],
  "images": [
    {
      "height": <int>,
      "resource_url": <str>,
      "type": <str>,
      "uri": <str>,
      "uri150": <str>,
      "width": <int>
    }
  ],
  "labels": [
    {
      "catno": <str>,
      "entity_type": <str>,
      "id": <int>,
      "name": <str>,
      "resource_url": <str>
    }
  ],
  "lowest_price": <float>,
  "master_id": <int>,
  "master_url": <str>,
  "notes": <str>,
  "num_for_sale": <int>,
  "released": <str>,
  "released_formatted": <str>,
  "resource_url": <str>,
  "series": [],
  "status": <str>,
  "styles": [<str>],
  "tracklist": [
    {
      "duration": <str>,
      "position": <str>,
      "title": <str>,
      "type_": <str>
    }
  ],
  "uri": <str>,
  "videos": [
    {
      "description": <str>,
      "duration": <int>,
      "embed": <bool>,
      "title": <str>,
      "uri": <str>
    },
  ],
  "year": <int>
}

get_release_marketplace_stats(release_id: int | str, *, curr_abbr: str = None) → dict[str, Any][source]#

Marketplace > Release Statistics: Retrieve marketplace statistics for the provided release ID.

These statistics reflect the state of the release in the marketplace currently, and include the number of items currently for sale, lowest listed price of any item for sale, and whether the item is blocked for sale in the marketplace.

Releases that have no items or are blocked for sale in the marketplace will return a body with null data in the "lowest_price" and "num_for_sale" keys.

User authentication

Authentication is optional. Authenticated users will by default have the lowest currency expressed in their own buyer currency, configurable in buyer settings, in the absence of the curr_abbr query parameter to specify the currency. Unauthenticated users will have the price expressed in US Dollars, if no curr_abbr is provided.

Parameters:

release_idint or str

The ID of the release you are fetching.

Example: 249504.

curr_abbrstr, keyword-only, optional

Currency abbreviation for marketplace data.

Valid values: "USD", "GBP", "EUR", "CAD", "AUD", "JPY", "CHF", "MXN", "BRL", "NZD", "SEK", and "ZAR".

Returns:

statsdict

The marketplace statistics for the release.

Sample

{
  "lowest_price": {
    "currency": <str>,
    "value": <float>
  },
  "num_for_sale": <int>,
  "blocked_from_sale": <bool>
}

get_release_stats(release_id: int | str) → dict[str, Any][source]#

Database > Release Stats: Retrieves the release’s “have” and “want” counts.

Attention

This endpoint does not appear to be working correctly. Currently, the response will be of the form

{
  "is_offense": <bool>
}

Parameters:

release_idint or str

The release ID.

Example: 249504.

Returns:

statsdict

Release “have” and “want” counts.

Sample

{
  "num_have": <int>,
  "num_want": <int>
}

get_user_contributions(username: str = None, *, page: int | str = None, per_page: int | str = None, sort: str = None, sort_order: str = None) → dict[str, Any][source]#

User Identity > User Contributions: Retrieve a user’s contributions (releases, labels, artists) by username.

Parameters:

usernamestr, optional

The username of the contributions you are trying to fetch. If not specified, the username of the authenticated user is used.

Example: "shooezgirl".

pageint or str, keyword-only, optional

Page of results to fetch.

per_pageint or str, keyword-only, optional

Number of results per page.

sortstr, keyword-only, optional

Sort items by this field.

Valid values: "label", "artist", "title", "catno", "format", "rating", "year", and "added".

sort_orderstr, keyword-only, optional

Sort items in a particular order.

Valid values: "asc" and "desc".

Returns:

contributionsdict

Contributions made by the user.

Sample

{
  "pagination": {
    "items": <int>,
    "page": <int>,
    "pages": <int>,
    "per_page": <int>,
    "urls": {
      "last": <str>,
      "next": <str>
    }
  },
  "contributions": [
    {
      "artists": [
        {
          "anv": <str>,
          "id": <int>,
          "join": <str>,
          "name": <str>,
          "resource_url": <str>,
          "role": <str>,
          "tracks": <str>
        }
      ],
      "community": {
        "contributors": [
          {
            "resource_url": <str>,
            "username": <str>
          }
        ],
        "data_quality": <str>,
        "have": <int>,
        "rating": {
          "average": <int>,
          "count": <int>
        },
        "status": <str>,
        "submitter": {
          "resource_url": <str>,
          "username": <str>
        },
        "want": <int>
      },
      "companies": [],
      "country": <str>,
      "data_quality": <str>,
      "date_added": <str>,
      "date_changed": <str>,
      "estimated_weight": <int>,
      "format_quantity": <int>,
      "formats": [
        {
          "descriptions": [<str>],
          "name": <str>,
          "qty": <str>
        }
      ],
      "genres": [<str>],
      "id": <int>,
      "images": [
        {
          "height": <int>,
          "resource_url": <str>,
          "type": <str>,
          "uri": <str>,
          "uri150": <str>,
          "width": <int>
        }
      ],
      "labels": [
        {
          "catno": <str>,
          "entity_type": <str>,
          "id": <int>,
          "name": <str>,
          "resource_url": <str>
        }
      ],
      "master_id": <int>,
      "master_url": <str>,
      "notes": <str>,
      "released": <str>,
      "released_formatted": <str>,
      "resource_url": <str>,
      "series": [],
      "status": <str>,
      "styles": [<str>],
      "thumb": <str>,
      "title": <str>,
      "uri": <str>,
      "videos": [
        {
          "description": <str>,
          "duration": <int>,
          "embed": <bool>,
          "title": <str>,
          "uri": <str>
        }
      ],
      "year": <int>
    }
  ]
}

get_user_orders(*, status: str = None, created_after: str = None, created_before: str = None, archived: bool = None, page: int | str = None, per_page: int | str = None, sort: str = None, sort_order: str = None) → dict[str, Any][source]#

Marketplace > List Orders: Returns a list of the authenticated user’s orders.

User authentication

Requires user authentication with a personal access token or via the OAuth 1.0a flow.

Parameters:

statusstr, keyword-only, optional

Only show orders with this status.

Valid values: "All", "New Order", "Buyer Contacted", "Invoice Sent", "Payment Pending", "Payment Received", "In Progress", "Shipped", "Merged", "Order Changed", "Refund Sent", "Cancelled", "Cancelled (Non-Paying Buyer)", "Cancelled (Item Unavailable)", "Cancelled (Per Buyer's Request)", and "Cancelled (Refund Received)".

created_afterstr, keyword-only, optional

Only show orders created after this ISO 8601 timestamp.

Example: "2019-06-24T20:58:58Z".

created_beforestr, keyword-only, optional

Only show orders created before this ISO 8601 timestamp.

Example: "2019-06-24T20:58:58Z".

archivedbool, keyword-only, optional

Only show orders with a specific archived status. If no key is provided, both statuses are returned.

pageint or str, keyword-only, optional

The page you want to request.

Example: 3.

per_pageint, keyword-only, optional

The number of items per page.

Example: 25.

sortstr, keyword-only, optional

Sort items by this field.

Valid values: "id", "buyer", "created", "status", and "last_activity".

sort_orderstr, keyword-only, optional

Sort items in a particular order.

Valid values: "asc" and "desc".

Returns:

ordersdict

The authenticated user’s orders.

Sample

{
  "pagination": {
    "page": <int>,
    "pages": <int>,
    "per_page": <int>,
    "items": <int>,
    "urls": {}
  },
  "orders": [
    {
      "id": <str>,
      "resource_url": <str>,
      "messages_url": <str>,
      "uri": <str>,
      "status": <str>,
      "next_status": [<str>],
      "fee": {
        "currency": <str>,
        "value": <float>
      },
      "created": <str>,
      "items": [
        {
          "release": {
            "id": <int>,
            "description": <str>,
          },
          "price": {
            "currency": <str>,
            "value": <int>
          },
          "media_condition": <str>,
          "sleeve_condition": <str>,
          "id": <int>
        }
      ],
      "shipping": {
        "currency": <str>,
        "method": <str>,
        "value": <int>
      },
      "shipping_address": <str>,
      "additional_instructions": <str>,
      "archived": <bool>,
      "seller": {
        "resource_url": <str>,
        "username": <str>,
        "id": <int>
      },
      "last_activity": <str>,
      "buyer": {
        "resource_url": <str>,
        "username": <str>,
        "id": <int>
      },
      "total": {
        "currency": <str>,
        "value": <int>
      }
    }
  ]
}

get_user_release_rating(release_id: int | str, username: str = None) → dict[str, Any][source]#

Database > Release Rating By User > Get Release Rating By User: Retrieves the release’s rating for a given user.

Parameters:

release_idint or str

The release ID.

Example: 249504.

usernamestr, optional

The username of the user whose rating you are requesting. If not specified, the username of the authenticated user is used.

Example: "memory".

Returns:

ratingdict

Rating for the release by the given user.

Sample

{
  "username": <str>,
  "release_id": <int>,
  "rating": <int>
}

get_user_submissions(username: str = None, *, page: int | str = None, per_page: int | str = None) → dict[str, Any][source]#

User Identity > User Submissions: Retrieve a user’s submissions (edits made to releases, labels, and artists) by username.

Parameters:

usernamestr, optional

The username of the submissions you are trying to fetch. If not specified, the username of the authenticated user is used.

Example: "shooezgirl".

pageint or str, keyword-only, optional

Page of results to fetch.

per_pageint or str, keyword-only, optional

Number of results per page.

Returns:

submissionsdict

Submissions made by the user.

Sample

{
  "pagination": {
    "items": <int>,
    "page": <int>,
    "pages": <int>,
    "per_page": <int>,
    "urls": {
      "last": <str>,
      "next": <str>
    }
  },
  "submissions": {
    "artists": [
      {
        "data_quality": <str>,
        "id": <int>,
        "name": <str>,
        "namevariations": [<str>],
        "releases_url": <str>,
        "resource_url": <str>,
        "uri": <str>
      }
    ],
    "labels": [],
    "releases": [
      {
        "artists": [
          {
            "anv": <str>,
            "id": <int>,
            "join": <str>,
            "name": <str>,
            "resource_url": <str>,
            "role": <str>,
            "tracks": <str>
          }
        ],
        "community": {
          "contributors": [
            {
              "resource_url": <str>,
              "username": <str>
            }
          ],
          "data_quality": <str>,
          "have": <int>,
          "rating": {
            "average": <int>,
            "count": <int>
          },
          "status": <str>,
          "submitter": {
            "resource_url": <str>,
            "username": <str>
          },
          "want": <int>
        },
        "companies": [],
        "country": <str>,
        "data_quality": <str>,
        "date_added": <str>,
        "date_changed": <str>,
        "estimated_weight": <int>,
        "format_quantity": <int>,
        "formats": [
          {
            "descriptions": [<str>],
            "name": <str>,
            "qty": <str>
          }
        ],
        "genres": [<str>],
        "id": <int>,
        "images": [
          {
            "height": <int>,
            "resource_url": <str>,
            "type": <str>,
            "uri": <str>,
            "uri150": <str>,
            "width": <int>
          }
        ],
        "labels": [
          {
            "catno": <str>,
            "entity_type": <str>,
            "id": <int>,
            "name": <str>,
            "resource_url": <str>
          }
        ],
        "master_id": <int>,
        "master_url": <str>,
        "notes": <str>,
        "released": <str>,
        "released_formatted": <str>,
        "resource_url": <str>,
        "series": [],
        "status": <str>,
        "styles": [<str>],
        "thumb": <str>,
        "title": <str>,
        "uri": <str>,
        "videos": [
          {
            "description": <str>,
            "duration": <int>,
            "embed": <bool>,
            "title": <str>,
            "uri": <str>
          }
        ],
        "year": <int>
      }
    ]
  }
}

rename_collection_folder(folder_id: int, name: str, *, username: str = None) → dict[str, int | str][source]#

User Collection > Collection Folder > Edit Folder: Rename a folder.

Folders 0 and 1 cannot be renamed.

User authentication

Requires user authentication with a personal access token or via the OAuth 1.0a flow.

Parameters:

folder_idint

The ID of the folder to modify.

Example: 3.

namestr

The new name of the folder.

Example: "My favorites".

usernamestr, keyword-only, optional

The username of the collection you are trying to modify. If not specified, the username of the authenticated user is used.

Example: "rodneyfool".

Returns:

folderdict

Information about the edited folder.

Sample

{
  "id": <int>,
  "name": <str>,
  "count": <int>,
  "resource_url": <str>
}

search(query: str = None, *, type: str = None, title: str = None, release_title: str = None, credit: str = None, artist: str = None, anv: str = None, label: str = None, genre: str = None, style: str = None, country: str = None, year: str = None, format: str = None, catno: str = None, barcode: str = None, track: str = None, submitter: str = None, contributor: str = None) → dict[str, Any][source]#

Database > Search: Issue a search query to the Discogs database.

Authentication

Requires authentication with consumer credentials, with a personal access token, or via the OAuth 1.0a flow.

Parameters:

querystr, optional

The search query.

Example: "Nirvana".

typestr, keyword-only, optional

The type of item to search for.

Valid values: "release", "master", "artist", and "label".

titlestr, keyword-only, optional

Search by combined "<artist name> - <release title>" title field.

Example: "Nirvana - Nevermind".

release_titlestr, keyword-only, optional

Search release titles.

Example: "Nevermind".

creditstr, keyword-only, optional

Search release credits.

Example: "Kurt".

artiststr, keyword-only, optional

Search artist names.

Example: "Nirvana".

anvstr, keyword-only, optional

Search artist name variations (ANV).

Example: "Nirvana".

labelstr, keyword-only, optional

Search labels.

Example: "DGC".

genrestr, keyword-only, optional

Search genres.

Example: "Rock".

stylestr, keyword-only, optional

Search styles.

Example: "Grunge".

countrystr, keyword-only, optional

Search release country.

Example: "Canada".

yearstr, keyword-only, optional

Search release year.

Example: "1991".

formatstr, keyword-only, optional

Search formats.

Example: "Album".

catnostr, keyword-only, optional

Search catalog number.

Example: "DGCD-24425".

barcodestr, keyword-only, optional

Search barcode.

Example: "720642442524".

trackstr, keyword-only, optional

Search track.

Example: "Smells Like Teen Spirit".

submitterstr, keyword-only, optional

Search submitter username.

Example: "milKt".

contributorstr, keyword-only, optional

Search contributor username.

Example: "jerome99".

Returns:

resultsdict

Search results.

Sample

{
  "pagination": {
    "items": <int>,
    "page": <int>,
    "pages": <int>,
    "per_page": <int>,
    "urls": {
      "last": <str>,
      "next": <str>
    }
  },
  "results": [
    {
      "style": [<str>],
      "thumb": <str>,
      "title": <str>,
      "country": <str>,
      "format": [<str>],
      "uri": <str>,
      "community": {
        "want": <int>,
        "have": <int>
      },
      "label": [<str>],
      "catno": <str>,
      "year": <str>,
      "genre": [<str>],
      "resource_url": <str>,
      "type": <str>,
      "id": <int>
    }
  ]
}

set_access_token(access_token: str = None, access_token_secret: str = None) → None[source]#

Set the Discogs API personal or OAuth access token (and secret).

Parameters:

access_tokenstr, optional: Personal or OAuth access token.
access_token_secretstr, optional: OAuth access token secret.

set_flow(flow: str, *, consumer_key: str = None, consumer_secret: str = None, browser: bool = False, web_framework: str = None, port: int | str = 8888, redirect_uri: str = None, save: bool = True) → None[source]#

Set the authorization flow.

Parameters:

flowstr

Authorization flow. If None, no user authentication will be performed and client credentials will not be attached to requests, even if found or provided.

Valid values:

None for no user authentication.
"discogs" for the Discogs authentication flow.
"oauth" for the OAuth 1.0a flow.

consumer_keystr, keyword-only, optional

consumer_secretstr, keyword-only, optional

browserbool, keyword-only, default: False

web_frameworkstr, keyword-only, optional

Determines which web framework to use for the OAuth 1.0a flow.

Valid values:

"http.server" for the built-in implementation of HTTP servers.
"flask" for the Flask framework.
"playwright" for the Playwright framework by Microsoft.

portint or str, keyword-only, default: 8888

Port on localhost to use for the OAuth 1.0a flow with the http.server and Flask frameworks. Only used if redirect_uri is not specified.

redirect_uristr, keyword-only, optional

Redirect URI for the OAuth 1.0a flow. If not on localhost, the automatic request access token retrieval functionality is not available.

savebool, keyword-only, default: True

Determines whether newly obtained access tokens and their associated properties are stored to the Minim configuration file.

update_user_release_rating(release_id: int | str, rating: int, username: str = None) → dict[str, Any][source]#

Database > Release Rating By User > Update Release Rating By User: Updates the release’s rating for a given user.

User authentication

Requires user authentication with a personal access token or via the OAuth 1.0a flow.

Parameters:

release_idint or str

The release ID.

Example: 249504.

ratingint

The new rating for a release between \(1\) and \(5\).

usernamestr, optional

The username of the user whose rating you are requesting. If not specified, the username of the authenticated user is used.

Example: "memory".

Returns:

ratingdict

Updated rating for the release by the given user.

Sample

{
  "username": <str>,
  "release_id": <int>,
  "rating": <int>
}