Skip to contents

Sends requests to the 'Discogs' application programming interface (API) https://www.discogs.com/developers and returns the results as tidy tibbles. The 'Discogs' database can be searched, and releases, master releases, artists and labels can be read from it, along with the releases of an artist or label and the versions of a master release. The collection folders, collection and wantlist of a user can be listed, tallied and plotted, and marketplace statistics, price suggestions and collection values can be read. Tracklists, credits, formats, identifiers and companies of releases can be unnested into one row per item. Requests can be made with a personal access token or without one. They stay within the rate limit of the API and are retried when the limit is exceeded. Responses can be cached for the session, and paginated results can be fetched in full.

Details

Requests are sent to the 'Discogs' API at https://api.discogs.com. Without a token, 'Discogs' allows 25 requests a minute. With a personal access token set by dig_auth(), the limit is 60 requests a minute, the database can be searched, your own private collection and wantlist can be read, and price suggestions and the value of your collection are available. tidycrates counts requests as 'Discogs' does, so small batches are sent at once and later requests wait only until 'Discogs' has room for them. dig_rate_limit() explains the count and why the throttle of httr2 is not used. Requests are retried after HTTP 429 and 503 responses. A message, or the progress bar when several items are fetched, says how long each wait takes.

When the API cannot be reached, because there is no internet connection, the server returns an error or the rate limit is still exceeded after several tries, functions give a message and return NULL invisibly. Errors caused by the request, such as an unknown release, stop with the message returned by 'Discogs'.

Options

If the option tidycrates.cache is set to TRUE, responses from the database are kept in memory for the session, so repeated requests do not count towards the rate limit. Caching needs the memoise and cachem packages and is off by default. Cached responses are kept for 3600 seconds unless tidycrates.cache_age gives another number of seconds. Changing tidycrates.cache_age starts a new, empty cache, and dig_cache_clear() empties it. Collections, wantlists and marketplace data are never cached. The API Terms of Use do not allow showing data that are more than six hours old, so responses are never kept longer than 21600 seconds.

Terms of use

The 'Discogs' API Terms of Use apply to all data returned by the package, and using the package means accepting them. In the United States, they require you to be at least 18 years old.

The Terms of Use list the fields that are available under the CC0 licence: titles, notes, dates, formats, tracklists, identifiers, credits, versions and links of releases, and the names, notes and releases of artists and labels. Other fields, such as genres, styles, community counts and ratings, are not listed as CC0, so they can only be used under the Terms of Use.

Collections, wantlists, usernames and marketplace data are Restricted Data: keep them for your own use, see dig_collection(). Images are left out, because the people who upload them can hold their own copyright. Functions for selling, such as listings and orders, are left out too.

Data from 'Discogs' may not be shown if they are more than six hours older than the 'Discogs' website, or stored longer than needed. Applications that show data from 'Discogs' have to display "Data provided by Discogs." next to the data, with a link to the page on 'Discogs'. The uri column gives that link, and dig_plot() adds the text as a caption.

This application uses Discogs' API but is not affiliated with, sponsored or endorsed by Discogs. 'Discogs' is a trademark of Zink Media, LLC.

Author

Maintainer: Massimiliano Canzi massimiliano.canzi@uni-konstanz.de (ORCID) [copyright holder]

Authors: