.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "WebService::MusicBrainz 3pm"
.TH WebService::MusicBrainz 3pm 2024-02-27 "perl v5.38.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH NAME
WebService::MusicBrainz
.SH SYNOPSIS
.IX Header "SYNOPSIS"
.Vb 1
\&    use WebService::MusicBrainz;
\&
\&    my $mb = WebService::MusicBrainz\->new();
\&
\&    my $result = $mb\->search($resource => { $search_key => \*(Aqsearch value\*(Aq });
\&    my $result = $mb\->search($resource => { $search_key => \*(Aqsearch value\*(Aq, fmt => \*(Aqjson\*(Aq });  # fmt => \*(Aqjson\*(Aq is default
\&
\&    my $result_dom = $mb\->search($resource => { $search_key => \*(Aqsearch value\*(Aq, fmt => \*(Aqxml\*(Aq });
.Ve
.SH DESCRIPTION
.IX Header "DESCRIPTION"
API to search the musicbrainz.org database
.SH VERSION
.IX Header "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.
.SH METHODS
.IX Header "METHODS"
.SS new
.IX Subsection "new"
.Vb 1
\& my $mb = WebService::MusicBrainz\->new();
.Ve
.SS search
.IX Subsection "search"
.Vb 1
\& my $result_list = $mb\->search($resource => { param1 => \*(Aqvalue1\*(Aq });
\&
\& my $result = $mb\->search($resource => { mbid => \*(Aqmbid\*(Aq });
\&
\& my $result_more = $mb\->search($resource => { mbid => \*(Aqmbid\*(Aq, inc => \*(Aqextra stuff\*(Aq });
\&
\& 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 => \*(Aqxml\*(Aq to return the results as an instance of Mojo::DOM.
.Ve
.PP
\fISearch by MBID\fR
.IX Subsection "Search by MBID"
.PP
.Vb 1
\&  my $result = $mb\->search($resource => { mbid => \*(Aqxxxxxx\*(Aq });
.Ve
.PP
The "inc" search parameter is only allowed when searching for any particular "mbid".
.PP
\fISearch area\fR
.IX Subsection "Search area"
.PP
.Vb 5
\&  my $area_list_results = $mb_ws\->search(area => { iso => \*(AqUS\-OH\*(Aq });
\&  my $area_list_results = $mb_ws\->search(area => { area => \*(Aqcincinnati\*(Aq });
\&  my $area_list_results = $mb_ws\->search(area => { alias => \*(Aqnew york\*(Aq });
\&  my $area_list_results = $mb_ws\->search(area => { sortname => \*(Aqnew york\*(Aq });
\&  my $area_list_results = $mb_ws\->search(area => { area => \*(Aqnew york\*(Aq, type => \*(Aqcity\*(Aq });
\&
\&  my $area_result = $mb_ws\->search(area => { mbid => \*(Aq0573177b\-9ff9\-4643\-80bc\-ed2513419267\*(Aq });
\&  my $area_result = $mb_ws\->search(area => { mbid => \*(Aq0573177b\-9ff9\-4643\-80bc\-ed2513419267\*(Aq, inc => \*(Aqarea\-rels\*(Aq });
.Ve
.PP
\fISearch artist\fR
.IX Subsection "Search artist"
.PP
.Vb 3
\& # JSON example
\& my $artists = $mb\->search(artist => { artist => \*(AqRyan Adams\*(Aq });
\& my $artists = $mb\->search(artist => { artist => \*(AqRyan Adams\*(Aq, type => \*(Aqperson\*(Aq });
\&
\& my $artist_country = $artists\->{artists}\->[0]\->{country};
\&
\& # XML example
\& my $artists = $mb\->search(artist => { artist => \*(AqRyan Adams\*(Aq, type => \*(Aqperson\*(Aq, fmt => \*(Aqxml\*(Aq });
\&
\& my $artist_country = $artists\->at(\*(Aqcountry\*(Aq)\->text;
\&
\& # find this particular artist
\& my $artist = $mb\->search(artist => { mbid => \*(Aq5c2d2520\-950b\-4c78\-84fc\-78a9328172a3\*(Aq });
\&
\& # find this particular artist and include release and artist relations (members of the band)
\& my $artist = $mb\->search(artist => { mbid => \*(Aq5c2d2520\-950b\-4c78\-84fc\-78a9328172a3\*(Aq, inc => [\*(Aqreleases\*(Aq,\*(Aqartist\-rels\*(Aq] });
\&
\& # artists that started in Cincinnati
\& my $artists = $mb\->search(artist => { beginarea => \*(AqCincinnati\*(Aq });
.Ve
.PP
\fISearch label\fR
.IX Subsection "Search label"
.PP
.Vb 1
\& my $labels = $mb\->search(label => { label => \*(AqDeath\*(Aq });
.Ve
.PP
\fISearch recording\fR
.IX Subsection "Search recording"
.PP
.Vb 1
\& my $recordings = $mb\->search(recording => { artist => \*(AqTaylor Swift\*(Aq });
.Ve
.PP
\fISearch release\fR
.IX Subsection "Search release"
.PP
.Vb 2
\& my $releases = $mb\->search(release => { release => \*(AqLove Is Hell\*(Aq, status => \*(Aqofficial\*(Aq });
\& print "RELEASE COUNT: ", $releases\->{count}, "\en";
.Ve
.SH DEBUG
.IX Header "DEBUG"
Set environment variable MUSICBRAINZ_DEBUG=1
.IP \(bu 1
The URL that is generated for the search will output to STDOUT.
.IP \(bu 1
The formatted output (JSON or XML) will be output to STDOUT
.SH AUTHOR
.IX Header "AUTHOR"
.IP "Bob Faist <bob.faist@gmail.com>" 4
.IX Item "Bob Faist <bob.faist@gmail.com>"
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
Copyright 2006\-2017 by Bob Faist
.PP
This library is free software; you can redistribute it and/or modify
it under the same terms as Perl itself.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
https://musicbrainz.org/doc/MusicBrainz_API