NAME

WWW::AllMusicGuide - A Perl module to search the All Music Guide (www.allmusic.com)

SYNOPSIS

 use WWW::AllMusicGuide;
 my $amg = new WWW::AllMusicGuide();
 my $result = $amg->search_artist(-name => "The Beatles");
 if (ref($result) eq "ARRAY") {
    # process search results
 } else {
    # process parsed artist information
 }
 $result = $amg->search_album(-name => "Abbey Road");
 $result = $amg->lookup_object($object_id);

DESCRIPTION

The WWW::AllMusicGuide module provides an object that you can use to search the All Music Guide (http://www.allmusic.com). Currently, you can search for artists and albums. Artist and album pages are parsed into hash references containing the information (e.g. name, year, group members, etc). This information is useful in writing tools to maintain large collections of MP3 files, their ID3 tags and metadata.

NOTE: (from the website)

``The All Music Guide is protected by a unique data fingerprinting process to insure that the data and its format can be identified. This data cannot be distributed in any form without the express written permission of the AEC One Stop Group, Inc.''

METHODS

new

 new %params

Creates a WWW::AllMusicGuide object. The following parameters are recognized:

  -progress => File handle on which to send progress messages
  -url      => URL of the All Music Guide (defaults to
               "http://www.allmusic.com";). Useful for testing 
               to redirect traffic to a local server so you can
               see what\'s going on.
  -agent    => User agent string to send in requests (defaults to
               "Mozilla/4.0 (compatible; MSIE 5.5; Windows NT 5.0)")

search_artist

 search_artist %params

Searches for an artist matching the specified parameters. Valid parameters:

  -name  => The name of the artist as typed into the AMG search box.
  -id    => Find the artist with the specified AMG id.
  -auto  => Automatically select a likely match (if possible) when
            multiple search results are returned.

You must specify one of -name or -id. AMG id\'s are obtained in the return values for many methods. The return value is either a hash reference containing artist info OR a list reference containing search results. See RETURN VALUES below for more info.

If -auto is specified, search results will be analyzed and if a reasonable guess can be made as to what was intended, the method will automatically navigate to that artist page. The algorithm is simple:

  * If there is only one artist that is highlighted in the search 
    results, that is the likely match.
  * If there is more than one highlighted artist in the search results 
    and one of them case-insensitively matches the passed-in -name use 
    the matching one.
  * Otherwise return search results.

search_album

 search_album %params

Searches for an album matching the specified parameters. Valid parameters:

  -name  => The name of the album as typed into the AMG search box.
  -id    => Find the album with the specified AMG id.

You must specify one of -name or -id. AMG id\'s are obtained in the return values for many methods. The return value is either a hash reference containing album info OR a list reference containing search results. See RETURN VALUES below for more info.

RETURN VALUES

In general data is returned in hash references with ALLCAPS keys. Search results are returned as list references containing a hash reference describing each search result. Most keys are optional and values are strings unless otherwise specified. The format for date strings varies.

Artist Info (hashref)

Contains the following keys:

  FORMED_DATE, FORMED_LOCATION, DISBANDED_DATE, DISBANDED_LOCATION 
  BORN_DATE, BORN_LOCATION, DIED_DATE, DIED_LOCATION, IMAGE_URL, BIO
  YEARS_ACTIVE  (listref, e.g. [ '70s', '80s', '90s' ])
  MEMBERS       (listref of hashrefs) example:
                [{'NAME' => 'Donald Fagen', 'ARTIST_ID' => 'Bjgjyeat04'},
                 {'NAME' => 'Walter Becker', 'ARTIST_ID' => 'B9pec97l7k'}]
  GENRES          (listref, e.g. [ 'ROCK' ])
  STYLES          (listref, e.g. [ 'Album Rock', 'Jazz-Rock' ])
  LABELS          (listref, e.g. [ 'MCA', 'Magnum', 'Giant' ])
  TONES           (listref, e.g. [ 'Irreverent', 'Humorous', 'Snide' ]
  INSTRUMENTS     (listref, e.g. [ 'Vocals','Keyboards', 'Synthesizer' ]
  DISCOGRAPHY     (listref of hashrefs)
  In the discography, each album/single/compilation is represented as a 
  hash reference with the following keys:
    YEAR
    ALBUM_ID
    AMG_RATING  (number of stars)
    AMG_PICK    (0/1)
    LABEL
    TYPE        (album/boxset/compilation/ep/single/bootleg/video)
    IN_PRINT    (0/1)
    TITLE       Name of the album/single/etc.

Album Info (hashref)

Each Album Info hashref may contain the following keys:

  ARTIST, ARTIST_ID, ALBUM_TITLE, INPRINT, RELEASE_DATE, AMG_RATING, 
  MARC_ID, TIME, COVER_URL, REVIEW, REVIEWER
  GENRE   (listref, e.g. [ 'Rock' ])
  STYLES  (listref, e.g. [ 'Jazz-Rock', 'Pop/Rock' ])
  TONES   (listref, e.g. [ 'Lush', 'Refined/Mannered' ])
  TRACKS  (listref of hashrefs)
    Each track hashref may contain the following keys:
    NAME      The track name
    NUMBER    The position of the track in the album
    AMG_PICK  (0/1)
    CREDIT    Songwriting credit
  CREDITS (listref of hashrefs)
    Each credit hashref may contain the following keys:
    ARTIST
    ARTIST_ID
    ROLES  (comma-separated list of roles, e.g.
            "Sax (Baritone), Sax (Tenor)")

Artist Search Results (list reference)

Documentation not written yet. Use Data::Dumper to see result structure.

Album Search Results (list reference)

Documentation not written yet. Use Data::Dumper to see result structure.

AUTHORS

Mohamed Hendawi (moe334578-amg AT yahoo DOT com)

Updated by David Gubitosi, 2003.

WARNING

The API and format of structures may change between subsequent versions.

COPYRIGHT

Copyright (c) 2004 Mohamed Hendawi. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

CHANGES

Version 0.06 - 1/24/2004

Incorporated changes and fixes from Dave Gubitosi: