Skip to contents

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.

Installation

tidycrates is not on CRAN yet. Install it from GitHub:

pak::pak("mcanzi/tidycrates")

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                      NA

dig_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 Vinyl

The 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-By

dig_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    30

dig_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       Cassette

dig_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      1

Each 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.667

dig_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")

Lollipop chart of copies by genre in a made-up collection of 240 copies. Electronic is the most common, with 68 copies (28%), followed by Rock and Funk / Soul.

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.