The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.
 / 
WWW-Discogs-0.13
River stage zero No dependents
2 ++
/ WWW::Discogs

NAME

WWW::Discogs - get music related information and images

DESCRIPTION

Interface with www.discogs.com API to get music related information and images. Discogs is a user-built database containing information on artists, labels, and their recordings.

SYNOPSIS

  use WWW::Discogs;
  
  my $client = WWW::Discogs->new;
  
  # --
  # print all vinyl (12") releases from label 'Drumcode'
  # --
  my $label = $client->label(name => 'Drumcode', releases => 1);
  my @vinyls = grep { $_->{format} =~ /12\"/ } $label->releases;
  
  for my $rel (@vinyls) {
      print join("\t",
                 $rel->{catno},
                 $rel->{artist},
                 $rel->{title},
                 $rel->{format},
          );
      print "\n";
  }
  
  # --
  # print all covers for records by Nima Khak
  # --
  my @all_rels = $client->artist(name => 'Nima Khak', releases => 1)->releases;
  my @main_rels = grep { $_->{role} eq 'Main' } @all_rels;
  
  RELEASE:
  for my $r (@main_rels) {
      my $release;
  
      if ($r->{type} eq 'master') {
          my $master = $client->master(id => $r->{id});
          $release = $client->release(id => $master->main_release);
      }
      elsif ($r->{type} eq 'release') {
          $release = $client->release(id => $r->{id});
      }
  
      my @images = $release->images(type => 'primary');
      next RELEASE unless scalar(@images);
      print join("\t", $release->title, $images[0]->{uri}), "\n";
  }

METHODS

search( q => $search_string )

search( q => $search_string, type => $search_type )

search( q => $search_string, type => $search_type, page => $page )

Returns a WWW::Discogs::Search object. If you want to narrow down search results then provide $search_type which can be one of 'all' (the default), 'releases' (also returns masters), 'artists' or 'labels'. Search results are paginated (20 results per page) and default is page => 1. You can check how many search results pages are there by calling pages method on WWW::Discogs::Search object.

release( id => $release_id )

Returns a WWW::Discogs::Release object. You can get a $release_id from a search, artist, or label.

master( id => $master_id )

Returns a WWW::Discogs::Master object. You can get a $master_id from a search or release.

artist( name => $artist_name )

artist( name => $artist_name, releases => 1 )

Returns a WWW::Discogs::Artist object. You can get the exact name of an artist from a search result's title.

label( name => $label_name )

label( name => $label_name, releases => 1 )

Returns a WWW::Discogs::Label object. You can get the exact name of a label from a search result's title.

OBJECTS CREATED AND THEIR METHODS

WWW::Discogs::Search

$search->exactresults

Returns list of hash references containing results exactly matching search query. See example below:

  use WWW::Discogs;
  
  my $client = WWW::Discogs->new;
  my $search = $client->search(q => 'adam beyer');
  
  for my $result ($search->exactresults) {
      print join(" - ", $result->{type}, $result->{title}, $result->{uri});
      print "\n";
  }
$search->searchresults

Returns list of hash references containing search results.

$search->numresults

Returns a number of search results (counted without exact results).

$search->pages

Returns number of search results' pages. Each page contains max 20 search results.

WWW::Discogs::Release

$release->id

Returns release ID.

$release->title

Returns title of the release.

$release->images
$release->images( type => $image_type )

Returns a list of hash references containing information about images for a release. $image_type can be one of 'primary' or 'secondary'. See example below:

  use WWW::Discogs;
  
  my $client = WWW::Discogs->new;
  my $release = $client->release(id => 797674);
  
  for my $img ( $release->images(type => 'primary') ) {
      print join(" - ",
                 $img->{width}, $img->{height}, $img->{uri},
                 $img->{uri150}, $img->{type},
          );
      print "\n";
  }
$release->released

Returns release date in ISO 8601 format (YYYY-MM-DD).

$release->released_formatted

Returns formatted release date ('06 Oct 2006', 'Mar 2006' etc.)

$release->labels

Returns a list of hash references containing labels information. See example below:

  use WWW::Discogs;
  
  my $client = WWW::Discogs->new;
  my $release = $client->release(id => 797674);
  
  for my $label ($release->labels) {
      print join(" - ", $label->{name}, $label->{catno});
  }
$release->country

Returns country.

$release->formats

Returns a list of hash references containing formats information. See example below:

  use WWW::Discogs;
  
  my $client = WWW::Discogs->new;
  my $release = $client->release(id => 797674);
  
  for my $format ($release->formats) {
      printf("%d x %s, %s\n",
             $format->{qty},
             $format->{name},
             join(", ", @{ $format->{descriptions } }),
          );
  }

Prints:

 1 x CD, Album, Partially Mixed
 1 x CD, Compilation, Limited Edition
$release->status

Returns status.

$release->master_id

Returns master release ID associated with a release.

$release->year

Returns release year.

$release->notes

Returns release notes.

$release->styles

Returns a list of styles.

$release->genres

Returns a list of genres.

$release->artists

Returns a list of hash references containing artists information.

  use WWW::Discogs;
  
  my $client = WWW::Discogs->new;
  my $release = $client->release(id => 18618);
  
  for my $artist ($release->artists) {
      print join(" - ", $artist->{name}, $artist->{anv}, $artist->{role});
      print "\n";
  }
$release->extraartists

Returns a list of hash references containing extra artists information.

  use WWW::Discogs;
  
  my $client = WWW::Discogs->new;
  my $release = $client->release(id => 18618);
  
  for my $exart ($release->extraartists) {
      print join(" - ", $exart->{name}, $exart->{anv}, $exart->{role});
      print "\n";
  }
$release->tracklist

Returns tracklist as a list containing hash references. See example below:

  use WWW::Discogs;
  
  my $client = WWW::Discogs->new;
  my $release = $client->release(id => 830189);
  
  my @tracklist = $release->tracklist;
  for my $track (sort { $a->{position} <=> $b->{position} } @tracklist) {
      printf("%d. %s (%s)\n",
             $track->{position}, $track->{title}, $track->{duration},
          );
  }

WWW::Discogs::Master

$master->id

Returns master ID.

$master->main_release

Returns main release ID.

$master->versions

Returns a list of hash references containing versions information. See example below:

  use WWW::Discogs;
  
  my $client = WWW::Discogs->new;
  my $master = $client->master(id => 104330);
  
  for my $version ( $master->versions ) {
      printf("%9d %7s %15s %18s %7s %15s\n",
             $version->{id}, $version->{country}, $version->{title},
             $version->{format}, $version->{catno}, $version->{label});
  }

Prints:

   116934  Sweden   Chaos & Order          CD, Album  HPCD20 H. Productions
    11168  Sweden   Chaos & Order        2xLP, Album  HPLP20 H. Productions
  2307050  Sweden   Chaos & Order 2xLP, Album, W/Lbl  HPLP20 H. Productions

Other available keys in $version besides the ones in example above are $version->{status} and $version->{released}.

$master->images
$master->images( type => $image_type )

Returns a list of hash references containing information about images for a release. $image_type can be one of 'primary' or 'secondary'. See example below:

  use WWW::Discogs;
  
  my $client = WWW::Discogs->new;
  my $master = $client->master(id => 23992);
  
  for my $img ( $master->images(type => 'secondary') ) {
      print join(" - ",
               $img->{width}, $img->{height}, $img->{uri},
               $img->{uri150}, $img->{type},
          );
      print "\n";
  }
$master->year

Returns release year.

$master->notes

Returns release notes.

$master->styles

Returns a list of styles.

$master->genres

Returns a list of genres.

$master->artists

Returns a list of hash references containing artists information. See $release->artists for an example.

$master->extraartists

Returns a list of hash references containing extra artists information. See $release->extraartists for an example.

$master->tracklist

Returns tracklist. See $release->tracklist for an example.

WWW::Discogs::Artist

$artist->name

Returns artist name.

$artist->realname

Returns artist's real name

$artist->aliases

Returns a list of aliases used by the artist.

$artist->namevariations

Returns a list of name variations for the artist.

$artist->profile

Returns artist's profile information.

$artist->urls

Returns a list of site's URLs linked to the artist.

$artist->images
$artist->images( type => $image_type )

Returns a list of hash references containing images information. See $release->images for an example.

$artist->releases

If $client->artist method creating a new WWW::Discogs::Artist object was called with releases => 1 parameter you can get the list of artist's releases by calling this method. The result will be a list of hash references containing releases/master releases information. See example below:

  use WWW::Discogs;
  
  my $client = WWW::Discogs->new;
  my $artist = $client->artist(name => "Adam Beyer", releases => 1);
  
  foreach my $r ($artist->releases) {
    printf("%8d %7s %17s %s\n", $r->{id}, $r->{type}, $r->{role}, $r->{title});
  }

  • $r->{id} will contain release/master release ID

  • $r->{type} will contain release type ('release' or 'master')

  • $r->{role} will contain artist's role in release ('Main', 'Remix', 'Producer', 'Appearance', 'TrackAppearance' etc.)

  • $r->{title} will contain release/master release title

For releases with 'master' type you can get main release ID by checking the value of $r->{main_release}. Use Data::Dumper to find out more about this structure as results differ depending on artist's role and release type.

WWW::Discogs::Label

$label->name

Returns label's name.

$label->releases

If $client->label method creating a new WWW::Discogs::Label object was called with releases => 1 parameter you can get the list of label's releases by calling this method. The result will be a list of hash references containing releases information. See example below:

  use WWW::Discogs;
  
  my $client = WWW::Discogs->new;
  my $label = $client->label(name => 'Southsoul Appendix', releases => 1);
  
  for my $r ($label->releases) {
      print join("\t", $r->{id}, $r->{catno}, $r->{artist},
                 $r->{title}, $r->{format}
          );
      print "\n";
  }
$label->contactinfo

Returns contact info to the label.

$label->sublabels

Returns a list containing names of sublabels.

$label->parentlabel

Returns the name of parent label.

$label->images
$label->images( type => $images_type)

Returns a list of hash references containing images information. See $release->images for an example.

AUTHOR

0.11+: Michal Gasek <michal@gasek.eu>

0.01-0.10: Lee Aylward <lee@laylward.com>

LICENSE

This library is free software, you can redistribute it and/or modify it under the same terms as Perl itself.