DatabaseAPI

class minim.api.discogs.DatabaseAPI(client: APIClient, /)[source]

Bases: DiscogsResourceAPI

Database API endpoints for the Discogs API.

Important

This class is managed by DiscogsAPIClient and should not be instantiated directly.

Parameters:
clientminim.api._shared.APIClient

API client instance used to make HTTP requests.

Methods

delete_release_user_rating

Database > Release Rating By User > Delete Release Rating By User: Delete a user's rating for a release.

get_artist

Database > Artist: Get Discogs catalog information for an artist.

get_artist_releases

Database > Artist Releases: Get Discogs catalog information for releases by an artist.

get_label

Database > Label: Get Discogs catalog information for a label.

get_label_releases

Database > All Label Releases: Get Discogs catalog information for releases by a label.

get_master

Database > Master Release: Get Discogs catalog information for a master release.

get_master_versions

Database > Master Release Versions: Get Discogs catalog information for a master's release versions.

get_release

Database > Release: Get Discogs catalog information for a release.

get_release_community_rating

Database > Community Release Rating: Get the community rating for a release on Deezer.

get_release_community_stats

Database > Release Stats: Get community statistics for a release on Deezer.

get_release_user_rating

Database > Release Rating By User > Get Release Rating By User: Get a user's rating for a release on Discogs.

search

Database > Search: Search for artists, releases, labels, and masters in the Discogs catalog.

set_release_user_rating

Database > Release Rating By User > Update Release Rating By User: Set a user's rating for a release on Deezer.
delete_release_user_rating(release_id: int | str, /, *, username: str | None = None) → None[source]

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

User authentication

User authentication

Access protected endpoints.

Parameters:
release_idint or str; positional-only

Discogs ID of the release.

Examples: 249504 or "8649337".

usernamestr; keyword-only; optional

Username of the user. If not specified, the username of the current user is used.

Example: "memory".

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

Database > Artist: Get Discogs catalog information for an artist.

Parameters:
artist_idint or str; positional-only

Discogs ID of the artist.

Examples: 108713, "3042550".

Returns:
artistdict[str, Any]

Discogs metadata for the artist.

Sample response

{
  "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>,
      "thumbnail_url": <str>
    }
  ],
  "name": <str>,
  "profile": <str>,
  "releases_url": <str>,
  "resource_url": <str>,
  "uri": <str>,
  "urls": <list[str]>
}
get_artist_releases(artist_id: int | str, /, *, limit: int | None = None, page: int | None = None, sort_by: str | None = None, descending: bool | None = None) → dict[str, Any][source]

Database > Artist Releases: Get Discogs catalog information for releases by an artist.

Parameters:
artist_idint or str; positional-only

Discogs ID of the artist.

Examples: 108713, "3042550".

limitint; keyword-only; optional

Maximum number of releases to return.

Valid range: 1 to 100.

API default: 50.

pageint; keyword-only; optional

Page number. Use with limit to get the next page of releases.

Minimum value: 1.

API default: 1.

sort_bystr; keyword-only; optional

Field to sort releases by.

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

descendingbool; keyword-only; optional

Whether to sort in descending order.

Returns:
releasesdict[str, Any]

Discogs metadata for the artist’s releases.

Sample response

{
  "pagination": {
    "items": <int>,
    "page": <int>,
    "pages": <int>,
    "per_page": <int>,
    "urls": {
      "first": <str>,
      "last": <str>,
      "next": <str>,
      "prev": <str>
    }
  },
  "releases": [
    {
      "artist": <str>,
      "id": <int>,
      "main_release": <int>,
      "resource_url": <str>,
      "role": <str>,
      "stats": {
        "community": {
          "in_collection": <int>,
          "in_wantlist": <int>
        },
        "user": {
          "in_collection": <int>,
          "in_wantlist": <int>
        }
      },
      "thumb": <str>,
      "title": <str>,
      "type": <str>,
      "year": <int>
    }
  ]
}
get_label(label_id: int | str, /) → dict[str, Any][source]

Database > Label: Get Discogs catalog information for a label.

Parameters:
label_idint or str; positional-only

Discogs ID of the label.

Examples: 1, "681".

Returns:
labeldict[str, Any]

Discogs metadata for the label.

Sample response

{
  "contact_info": <str>,
  "data_quality": <str>,
  "id": <int>,
  "images": [
    {
      "height": <int>,
      "resource_url": <str>,
      "type": <str>,
      "uri": <str>,
      "uri150": <str>,
      "width": <int>
    }
  ],
  "name": <str>,
  "parent_label": {
    "id": <int>,
    "name": <str>,
    "resource_url": <str>
  },
  "profile": <str>,
  "releases_url": <str>,
  "resource_url": <str>,
  "sublabels": [
    {
      "id": <int>,
      "name": <str>,
      "resource_url": <str>
    }
  ],
  "uri": <str>,
  "urls": <list[str]>
}
get_label_releases(label_id: int | str, /, *, limit: int | None = None, page: int | None = None) → dict[str, Any][source]

Database > All Label Releases: Get Discogs catalog information for releases by a label.

Parameters:
label_idint or str; positional-only

Discogs ID of the label.

Examples: 1, "681".

limitint; keyword-only; optional

Maximum number of releases to return.

Valid range: 1 to 100.

API default: 50.

pageint; keyword-only; optional

Page number. Use with limit to get the next page of releases.

Minimum value: 1.

API default: 1.

Returns:
releasesdict[str, Any]

Page of Discogs metadata for the label’s releases.

Sample response

{
  "pagination": {
    "items": <int>,
    "page": <int>,
    "pages": <int>,
    "per_page": <int>,
    "urls": {
      "first": <str>,
      "last": <str>,
      "next": <str>,
      "prev": <str>
    }
  },
  "releases": [
    {
      "artist": <str>,
      "catno": <str>,
      "format": <str>,
      "id": <int>,
      "resource_url": <str>,
      "stats": {
        "community": {
          "in_collection": <int>,
          "in_wantlist": <int>
        },
        "user": {
          "in_collection": <int>,
          "in_wantlist": <int>
        }
      },
      "status": <str>,
      "thumb": <str>,
      "title": <str>,
      "year": <int>
    }
  ]
get_master(master_id: int | str, /) → dict[str, Any][source]

Database > Master Release: Get Discogs catalog information for a master release.

Parameters:
master_idint or str; positional-only

Discogs ID of the master release.

Examples: 1000, "846354".

Returns:
masterdict[str, Any]

Discogs metadata for the master release.

Sample response

{
  "artists": [
    {
      "anv": <str>,
      "id": <int>,
      "join": <str>,
      "name": <str>,
      "resource_url": <str>,
      "role": <str>,
      "thumbnail_url": <str>,
      "tracks": <str>
    }
  ],
  "data_quality": <str>,
  "genres": <list[str]>,
  "id": <int>,
  "images": [
    {
      "height": <int>,
      "resource_url": <str>,
      "type": <str>,
      "uri": <str>,
      "uri150": <str>,
      "width": <int>
    }
  ],
  "lowest_price": <float>,
  "main_release": <int>,
  "main_release_url": <str>,
  "most_recent_release": <int>,
  "most_recent_release_url": <str>,
  "num_for_sale": <int>,
  "resource_url": <str>,
  "styles": <list[str]>,
  "title": <str>,
  "tracklist": [
    {
      "duration": <str>,
      "position": <str>,
      "title": <str>,
      "type_": "track"
    }
  ],
  "uri": <str>,
  "versions_url": <str>,
  "videos": [
    {
      "description": <str>,
      "duration": <int>,
      "embed": <bool>,
      "title": <str>,
      "uri": <str>
    }
  ],
  "year": <int>
}
get_master_versions(master_id: int | str, /, *, label: str | None = None, release_country: str | None = None, release_format: str | None = None, release_year: int | str | None = None, limit: int | None = None, page: int | None = None, sort_by: str | None = None, descending: bool | None = None) → dict[str, Any][source]

Database > Master Release Versions: Get Discogs catalog information for a master’s release versions.

Parameters:
master_idint or str; positional-only

Discogs ID of the master release.

Examples: 1000, "846354".

labelstr; keyword-only; optional

Label to filter releases by.

Example: "Scorpio Music".

release_countrystr; keyword-only; optional

Release country to filter releases by.

Example: "Belgium".

release_formatstr; keyword-only; optional

Release format to filter releases by.

Example: "Vinyl".

release_yearint or str; keyword-only; optional

Release year to filter releases by.

Examples: 1992, "1998".

limitint; keyword-only; optional

Maximum number of releases to return.

Valid range: 1 to 100.

API default: 50.

pageint; keyword-only; optional

Page number. Use with limit to get the next page of releases.

Minimum value: 1.

API default: 1.

sort_bystr; keyword-only; optional

Field to sort releases by.

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

descendingbool; keyword-only; optional

Whether to sort in descending order.

Returns:
versionsdict[str, Any]

Discogs metadata for the master’s release versions.

Sample response

{
  "filter_facets": [
    {
      "allows_multiple_values": <bool>,
      "id": <str>,
      "title": <str>,
      "values": [
        {
          "count": <int>,
          "title": <str>,
          "value": <str>
        }
      ]
    }
  ],
  "filters": {
    "applied": {},
    "available": {
      "country": <dict[str, int]>,
      "format": <dict[str, int]>,
      "label": <dict[str, int]>,
      "released": <dict[str, int]>
    }
  },
  "pagination": {
    "items": <int>,
    "page": <int>,
    "pages": <int>,
    "per_page": <int>,
    "urls": {
      "first": <str>,
      "last": <str>,
      "next": <str>,
      "prev": <str>
    }
  },
  "versions": [
    {
      "catno": <str>,
      "country": <str>,
      "format": <str>,
      "id": <int>,
      "label": <str>,
      "major_formats": <list[str]>,
      "released": <str>,
      "resource_url": <str>,
      "stats": {
        "community": {
          "in_collection": <int>,
          "in_wantlist": <int>
        },
        "user": {
          "in_collection": <int>,
          "in_wantlist": <int>
        }
      },
      "status": <str>,
      "thumb": <str>,
      "title": <str>
    }
  ]
}
get_release(release_id: int | str, /, *, currency: str | None = None) → dict[str, Any][source]

Database > Release: Get Discogs catalog information for a release.

Parameters:
release_idint or str; positional-only

Discogs ID of the release.

Examples: 249504 or "8649337".

currencystr; keyword-only; optional

Currency for marketplace data.

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

Returns:
releasedict[str, Any]

Discogs metadata for the release.

Sample response

{
  "artists": [
    {
      "anv": <str>,
      "id": <int>,
      "join": <str>,
      "name": <str>,
      "resource_url": <str>,
      "role": <str>,
      "thumbnail_url": <str>,
      "tracks": <str>
    }
  ],
  "artists_sort": <str>,
  "blocked_from_sale": <bool>,
  "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>,
  "data_quality": <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": <list[str]>,
      "name": <str>,
      "qty": <str>
    }
  ],
  "genres": <list[str]>,
  "id": <int>,
  "identifiers": [
    {
      "description": <str>,
      "type": <str>,
      "value": <str>
    }
  ],
  "images": [
    {
      "height": <int>,
      "resource_url": <str>,
      "type": <str>,
      "uri": <str>,
      "uri150": <str>,
      "width": <int>
    }
  ],
  "is_offensive": <bool>,
  "labels": [
    {
      "catno": <str>,
      "entity_type": <str>,
      "entity_type_name": <str>,
      "id": <int>,
      "name": <str>,
      "resource_url": <str>,
      "thumbnail_url": <str>
    }
  ],
  "lowest_price": None,
  "master_id": <int>,
  "master_url": <str>,
  "notes": <str>,
  "num_for_sale": <int>,
  "released": <str>,
  "released_formatted": <str>,
  "resource_url": <str>,
  "series": [],
  "status": <str>,
  "styles": <list[str]>,
  "thumb": <str>,
  "title": <str>,
  "tracklist": [
    {
      "duration": <str>,
      "extraartists": [
        {
          "anv": <str>,
          "id": <int>,
          "join": <str>,
          "name": <str>,
          "resource_url": <str>,
          "role": <str>,
          "tracks": <str>
        }
      ],
      "position": <str>,
      "title": <str>,
      "type_": "track"
    }
  ],
  "uri": <str>,
  "videos": [
    {
      "description": <str>,
      "duration": <int>,
      "embed": <bool>,
      "title": <str>,
      "uri": <str>
    }
  ],
  "year": <int>
}
get_release_community_rating(release_id: int | str, /) → dict[str, Any][source]

Database > Community Release Rating: Get the community rating for a release on Deezer.

Parameters:
release_idint or str; positional-only

Discogs ID of the release.

Examples: 249504 or "8649337".

Returns:
ratingdict[str, Any]

Community rating for the release.

Sample response

{
  "rating": {
    "average": <float>,
    "count": <int>
  },
  "release_id": <int>
}
get_release_community_stats(release_id: int | str, /) → dict[str, Any][source]

Database > Release Stats: Get community statistics for a release on Deezer.

Parameters:
release_idint or str; positional-only

Discogs ID of the release.

Examples: 249504 or "8649337".

Returns:
commununity_statsdict[str, Any]

Community statistics for the release.

Sample response: {"num_have": <int>, "num_want": <int>}.

get_release_user_rating(release_id: int | str, /, username: str | None = None) → dict[str, int | str][source]

Database > Release Rating By User > Get Release Rating By User: Get a user’s rating for a release on Discogs.

Parameters:
release_idint or str; positional-only

Discogs ID of the release.

Examples: 249504 or "8649337".

usernamestr; optional

Username of the user. If not specified, the username of the current user is used. Only optional when authenticated.

Example: "memory".

Returns:
ratingdict[str, int | str]

User’s rating for the release.

Sample response

{
  "rating": <int>,
  "release_id": <int>,
  "username": <str>
}
search(query: str | None = None, /, *, resource_type: str | None = None, title: str | None = None, release: str | None = None, artist: str | None = None, artist_variation: str | None = None, track: str | None = None, credit: str | None = None, label: str | None = None, genre: str | None = None, style: str | None = None, release_country: str | None = None, release_format: str | None = None, release_year: int | str | None = None, catalog_number: str | None = None, barcode: str | None = None, submitter: str | None = None, contributor: str | None = None, limit: int | None = None, page: int | None = None) → dict[str, Any][source]

Database > Search: Search for artists, releases, labels, and masters in the Discogs catalog.

User authentication

User authentication

Access protected endpoints.

Parameters:
querystr; positional-only; optional

Search query.

Example: "Nirvana".

resource_typestr; keyword-only; optional

Resource type to filter search results by.

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

titlestr; keyword-only; optional

Combined artist and title search field to filter search results by.

Example: "Nirvana - Nevermind".

releasestr; keyword-only; optional

Release title to filter search results by.

Example: "Nevermind".

artiststr; keyword-only; optional

Artist name to filter search results by.

Example: "Nirvana".

artist_variationstr; keyword-only; optional

Artist name variation to filter search results by.

Example: "Nirvana (US)".

trackstr; keyword-only; optional

Track title to filter search results by.

Example: "Smells Like Teen Spirit".

creditstr; keyword-only; optional

Release credit to filter search results by.

Example: "Kurt Cobain".

labelstr; keyword-only; optional

Label name to filter search results by.

Example: "DGC".

genrestr; keyword-only; optional

Genre to filter search results by.

Example: "Rock".

stylestr; keyword-only; optional

Style to filter search results by.

Example: "Grunge".

release_countrystr; keyword-only; optional

Release country to filter search results by.

Example: "Canada".

release_formatstr; keyword-only; optional

Release format to filter search results by.

Example: "Album".

release_yearint or str; keyword-only; optional

Release year to filter search results by.

Examples: 1991, "1991".

catalog_numberstr; keyword-only; optional

Catalog number to filter search results by.

Example: "DGC-24425".

barcodestr; keyword-only; optional

Release barcode to filter search results by.

Example: "7 2064-24425-2 4".

submitterstr; keyword-only; optional

Username of the Discogs user who submitted the release to filter search results by.

Example: "milKt".

contributorstr; keyword-only; optional

Username of the Discogs user who contributed to the release’s metadata to filter search results by.

Example: "jerome99".

limitint; keyword-only; optional

Maximum number of items to return.

Valid range: 1 to 100.

API default: 50.

pageint; keyword-only; optional

Page number. Use with limit to get the next page of items.

Minimum value: 1.

API default: 1.

Returns:
resultsdict[str, Any]

Page of Discogs metadata for the matching catalog items.

Sample response

{
  "pagination": {
    "items": <int>,
    "page": <int>,
    "pages": <int>,
    "per_page": <int>,
    "urls": {
      "first": <str>,
      "last": <str>,
      "next": <str>,
      "prev": <str>
    }
  },
  "results": [
    {
      "cover_image": <str>,
      "id": <int>,
      "master_id": <int>,
      "master_url": <str>,
      "resource_url": <str>,
      "thumb": <str>,
      "title": <str>,
      "type": <str>,
      "uri": <str>,
      "user_data": {
        "in_collection": <bool>,
        "in_wantlist": <bool>
      }
    }
  ]
}
set_release_user_rating(release_id: int | str, /, rating: int, *, username: str | None = None) → dict[str, int | str] | None[source]

Database > Release Rating By User > Update Release Rating By User: Set a user’s rating for a release on Deezer.

User authentication

User authentication

Access protected endpoints.

Parameters:
release_idint or str; positional-only

Discogs ID of the release.

Examples: 249504 or "8649337".

ratingint; keyword-only; optional

Star rating for the release. Use 0 to reset the rating.

Valid range: 0 to 5.

usernamestr; keyword-only; optional

Username of the user. If not specified, the username of the current user is used.

Example: "memory".

Returns:
ratingdict[str, int | str]

User’s new rating for the release. Returns None if rating is 0.

Sample response

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