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

`create_listing`
`delete_listing`
`delete_user_release_rating`	Database > Release Rating By User > Delete Release Rating By User: Deletes the release's rating for a given user.
`edit_listing`
`edit_order`
`edit_profile`	User Identity > Profile > Edit Profile: Edit a user's profile data.
`get_artist`	Database > Artist: Get an artist.
`get_artist_releases`	Database > Artist Releases: Get an artist's releases and masters.
`get_community_release_rating`	Database > Community Release Rating: Retrieves the community release rating average and count.
`get_identity`	User Identity > Identity: Retrieve basic information about the authenticated user.
`get_inventory`	Marketplace > Inventory: Get a seller's 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`
`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`
`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_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_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.
`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.

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.

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_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>
}

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>
}

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".

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_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_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 = None, per_page: int = 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, 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: "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_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 = None, per_page: int = 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, keyword-only, optional

Page of results to fetch.

per_pageint, 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_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 = None, per_page: int = 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, keyword-only, optional

Page of results to fetch.

per_pageint, 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>
    }
  ]
}

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>
    }
  ]
}

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

Marketplace > Inventory: Get a seller’s inventory.

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.

Example: "360vinyl".

statusstr, keyword-only, optional

The status of the listings to return.

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

pagestr, keyword-only, optional

The page you want to request.

Example: 3.

per_pagestr, 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

{

}

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_profile(username: str = None) → dict[str, Any][source]#

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

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>,
}

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>
}

get_user_submissions(username: str = None, *, page: int = None, per_page: int = 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, keyword-only, optional

Page of results to fetch.

per_pageint, 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>
      }
    ]
  }
}

get_user_contributions(username: str = None, *, page: int = None, per_page: int = 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, 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:

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>
    }
  ]
}