---
name: "WebService::MusicBrainz"
section: "3pm"
platform: "linux"
package: "libwebservice-musicbrainz-perl"
version: "1.0.7-1"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/WebService::MusicBrainz"
---

# WebService::MusicBrainz(3pm)

## NAME

WebService::MusicBrainz

## SYNOPSIS

```
    use WebService::MusicBrainz;
    my $mb = WebService::MusicBrainz->new();
    my $result = $mb->search($resource => { $search_key => 'search value' });
    my $result = $mb->search($resource => { $search_key => 'search value', fmt => 'json' });  # fmt => 'json' is default
    my $result_dom = $mb->search($resource => { $search_key => 'search value', fmt => 'xml' });
```

## DESCRIPTION

API to search the musicbrainz.org database

## VERSION

Version 1.0 and future releases are not backward compatible with pre-1.0 releases.  This is a complete re-write using version 2.0 of the MusicBrainz API and Mojolicious.

## METHODS

### new

```
 my $mb = WebService::MusicBrainz->new();
```

### search

```
 my $result_list = $mb->search($resource => { param1 => 'value1' });
 my $result = $mb->search($resource => { mbid => 'mbid' });
 my $result_more = $mb->search($resource => { mbid => 'mbid', inc => 'extra stuff' });
 Valid values for $resource are:  area, artist, event, instrument, label, recording, release, release-group, series, work, url
The default is to return decoded JSON as a perl data structure.  Specify format => 'xml' to return the results as an instance of Mojo::DOM.
```

*Search by MBID*

```
  my $result = $mb->search($resource => { mbid => 'xxxxxx' });
```

The "inc" search parameter is only allowed when searching for any particular "mbid".

*Search area*

```
  my $area_list_results = $mb_ws->search(area => { iso => 'US-OH' });
  my $area_list_results = $mb_ws->search(area => { area => 'cincinnati' });
  my $area_list_results = $mb_ws->search(area => { alias => 'new york' });
  my $area_list_results = $mb_ws->search(area => { sortname => 'new york' });
  my $area_list_results = $mb_ws->search(area => { area => 'new york', type => 'city' });
  my $area_result = $mb_ws->search(area => { mbid => '0573177b-9ff9-4643-80bc-ed2513419267' });
  my $area_result = $mb_ws->search(area => { mbid => '0573177b-9ff9-4643-80bc-ed2513419267', inc => 'area-rels' });
```

*Search artist*

```
 # JSON example
 my $artists = $mb->search(artist => { artist => 'Ryan Adams' });
 my $artists = $mb->search(artist => { artist => 'Ryan Adams', type => 'person' });
 my $artist_country = $artists->{artists}->[0]->{country};
 # XML example
 my $artists = $mb->search(artist => { artist => 'Ryan Adams', type => 'person', fmt => 'xml' });
 my $artist_country = $artists->at('country')->text;
 # find this particular artist
 my $artist = $mb->search(artist => { mbid => '5c2d2520-950b-4c78-84fc-78a9328172a3' });
 # find this particular artist and include release and artist relations (members of the band)
 my $artist = $mb->search(artist => { mbid => '5c2d2520-950b-4c78-84fc-78a9328172a3', inc => ['releases','artist-rels'] });
 # artists that started in Cincinnati
 my $artists = $mb->search(artist => { beginarea => 'Cincinnati' });
```

*Search label*

```
 my $labels = $mb->search(label => { label => 'Death' });
```

*Search recording*

```
 my $recordings = $mb->search(recording => { artist => 'Taylor Swift' });
```

*Search release*

```
 my $releases = $mb->search(release => { release => 'Love Is Hell', status => 'official' });
 print "RELEASE COUNT: ", $releases->{count}, "\n";
```

## DEBUG

Set environment variable MUSICBRAINZ\_DEBUG=1

- •

  The URL that is generated for the search will output to STDOUT.

- •

  The formatted output (JSON or XML) will be output to STDOUT

## AUTHOR

- Bob Faist \<bob.faist@gmail.com\>

  ## COPYRIGHT AND LICENSE

Copyright 2006-2017 by Bob Faist

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

## SEE ALSO

https://musicbrainz.org/doc/MusicBrainz\_API