tidycrates reads the Discogs database through the Discogs API and returns tidy tibbles. Releases, master releases, artists and labels come back with one row each, and their tracklists, credits, formats, identifiers and companies can be unnested into one row per item.
Requests stay within the rate limit of the API, which is 25 requests a minute without a token and 60 with one. tidycrates counts them the way Discogs does, so small batches are sent at once and longer ones wait only as long as needed. A request that still hits the limit is retried. Long lists can be fetched in full with all = TRUE, and responses can be cached for the session.
Token
The database can be read without a token, but searching it needs one. A personal access token also raises the limit to 60 requests a minute. Generate one in the developer settings of your Discogs account and add it to .Renviron, so it stays out of your scripts:
usethis::edit_r_environ()DISCOGS_TOKEN=your-token
After restarting R, tidycrates uses the token for every request. dig_auth() sets a different token for the current session.
Example
The output below comes from made-up data: the band Juniper Static, the label Fernhollow Records and their releases do not exist. The package tests use the same data. The real API returns other records for these IDs.
dig_search() finds the IDs to start from. It searches releases, master releases, artists and labels by a query, by filters such as artist, label, format and year, or by both:
library(tidycrates)
dig_search("Juniper Static") |>
dplyr::select(id, type, title, year)
#> # A tibble: 3 × 4
#> id type title year
#> <int> <chr> <chr> <int>
#> 1 1001 release Juniper Static - Lantern Weather 1994
#> 2 2001 master Juniper Static - Lantern Weather 1994
#> 3 3001 artist Juniper Static NAdig_release() reads a release:
release <- dig_release(1001)
release |> dplyr::select(title, artist, year, country, label, format)
#> # A tibble: 1 × 6
#> title artist year country label format
#> <chr> <chr> <int> <chr> <chr> <chr>
#> 1 Lantern Weather Juniper Static 1994 UK Fernhollow Records VinylThe tracklist, credits, formats, identifiers and companies are list columns. dig_tracklist(), dig_credits(), dig_formats(), dig_identifiers() and dig_companies() turn them into one row per item, and seconds gives each duration in seconds:
dig_tracklist(release)
#> # A tibble: 2 × 7
#> release_id position type title artist duration seconds
#> <int> <chr> <chr> <chr> <chr> <chr> <int>
#> 1 1001 A track Lantern Weather <NA> 3:32 212
#> 2 1001 B track Lantern Weather (Dub) <NA> 3:30 210
dig_credits(release) |> dplyr::select(name, credited_as, role)
#> # A tibble: 6 × 3
#> name credited_as role
#> <chr> <chr> <chr>
#> 1 Paperweight Design Paperweight Design
#> 2 Ida Marsh <NA> Engineer
#> 3 Tomas Reed <NA> Engineer
#> 4 Noor Halden NH Lacquer Cut By
#> 5 Felix Arno Felix A. Mixed By
#> 6 Malin Ödegaard M. Ödegaard Producer, Written-Bydig_artist_releases() lists everything an artist appears on, with the number of users who have each item in their collection or wantlist:
dig_artist_releases(3001) |>
dplyr::select(id, type, title, year, have, want)
#> # A tibble: 3 × 6
#> id type title year have want
#> <int> <chr> <chr> <int> <int> <int>
#> 1 1004 release Moth Radio 1997 43 160
#> 2 2001 master Lantern Weather 1994 70 90
#> 3 2002 master Paper Moon Signal 1997 25 30dig_master_versions() lists the versions of a master release, which can be filtered by format, label, year and country:
dig_master_versions(2001) |>
dplyr::select(release_id, country, released, major_formats)
#> # A tibble: 3 × 4
#> release_id country released major_formats
#> <int> <chr> <chr> <chr>
#> 1 1001 UK 1994-07-00 Vinyl
#> 2 1005 UK & France 1997 CD
#> 3 1006 Poland 1997 Cassettedig_collection() and dig_wantlist() list the releases in the collection or wantlist of a user. Anyone can read a public collection, but a private one can only be read with the token of its owner. Without a username, they read the collection or wantlist of the token owner. The notes that users write are left out. Collections and wantlists are Restricted Data, see Terms of use.
dig_collection_folders() lists the folders of a collection, and their IDs can be passed to dig_collection(), which also gives the folder name of each copy:
dig_collection_folders()
#> # A tibble: 3 × 3
#> folder_id name count
#> <int> <chr> <int>
#> 1 0 All 3
#> 2 1 Uncategorized 2
#> 3 2 Compilations 1Each copy in a collection has a media_condition and a sleeve_condition if the user graded it. The grades are factors from best to worst, as in dig_price_suggestions(), so the two can be joined to price each copy in its own grade:
collection <- dig_collection(all = TRUE)
prices <- dig_price_suggestions(unique(collection$release_id))
collection |>
dplyr::left_join(prices, by = dplyr::join_by(release_id, media_condition == condition)) |>
dplyr::select(title, media_condition, price, currency)
#> # A tibble: 3 × 4
#> title media_condition price currency
#> <chr> <fct> <dbl> <chr>
#> 1 Lantern Weather Near Mint (NM or M-) 12.8 EUR
#> 2 Lantern Weather Very Good (VG) 6.78 EUR
#> 3 Tidewater Sessions <NA> NA <NA>dig_tally() counts a collection by genre, style, format, label, artist, year, decade or month added, without sending more requests. A copy with several genres counts once for each:
dig_tally(collection, "genre")
#> # A tibble: 2 × 3
#> genre n share
#> <chr> <int> <dbl>
#> 1 Electronic 3 1
#> 2 Pop 2 0.667dig_plot() draws the same counts with ggplot2. Both also work on the output of the database and list functions, for example to count the releases of a label by decade or the credits of an artist by role:
dig_plot(collection, "genre")
dig_plot(dig_label_releases(4001, all = TRUE), "decade")
dig_plot(dig_artist_releases(3001, all = TRUE), "role")
Every plot has a title, a subtitle that says what is shown, alt text for screen readers and the caption “Data provided by Discogs.”. Values are written next to their marks, and the colours have enough contrast to be read without relying on colour alone.
dig_price_stats() gets the lowest price and the number of copies for sale of releases. With a token, dig_price_suggestions() gets the price Discogs suggests for each condition and dig_collection_value() the value of your own collection. Prices are never cached, and they are Restricted Data, see Terms of use:
dig_price_stats(c(1001, 1002))
#> # A tibble: 2 × 5
#> release_id lowest_price currency for_sale blocked
#> <int> <dbl> <chr> <int> <lgl>
#> 1 1001 4.5 EUR 12 FALSE
#> 2 1002 NA <NA> 0 FALSE
dig_price_suggestions(1001)
#> # A tibble: 8 × 4
#> release_id condition price currency
#> <int> <fct> <dbl> <chr>
#> 1 1001 Mint (M) 14.3 EUR
#> 2 1001 Near Mint (NM or M-) 12.8 EUR
#> 3 1001 Very Good Plus (VG+) 9.8 EUR
#> # ℹ 5 more rows
dig_collection_value()
#> # A tibble: 1 × 5
#> username minimum median maximum currency
#> <chr> <dbl> <dbl> <dbl> <chr>
#> 1 example 75.5 480. 1250 €Terms of use
The API Terms of Use apply to all data returned by tidycrates, and using it means accepting them. In the United States, they require you to be at least 18 years old.
Only some fields 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 and can only be used under the Terms of Use.
Collections, wantlists, usernames and marketplace data, such as prices and collection values, are Restricted Data. Discogs grants each user a limited, personal licence to access and use them with their own token: they may not be passed on to anyone else or used commercially, and their use must respect the privacy of their owners. Keep them, and tallies and plots of them, for your own use, and do not publish them. The Terms of Use also forbid using the API to get around the Discogs marketplace.
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.
If you show data from Discogs, put “Data provided by Discogs.” next to it with a link to the page on Discogs, which is in the uri column. dig_plot() adds the text as a caption, and the link goes wherever you publish the plot. Data that are more than six hours older than the Discogs website may not be shown, and data may not be stored longer than needed, so cached responses are never kept longer than six hours.
This application uses Discogs’ API but is not affiliated with, sponsored or endorsed by Discogs. ‘Discogs’ is a trademark of Zink Media, LLC.
