<?xml version="1.0" encoding="UTF-8"?>
<!-- Reviewed: no -->
<sect1 id="zend.service.audioscrobbler">

    <title>Zend_Service_Audioscrobbler</title>

    <sect2 id="zend.service.audioscrobbler.introduction">

        <title>Introduction</title>

        <para>
            <classname>Zend_Service_Audioscrobbler</classname> is a simple <acronym>API</acronym> for using the Audioscrobbler REST Web Service. The
            Audioscrobbler Web Service provides access to its database of Users, Artists, Albums, Tracks, Tags, Groups,
            and Forums. The methods of the <classname>Zend_Service_Audioscrobbler</classname> class begin with one of these terms.
            The syntax and namespaces of the Audioscrobbler Web Service are mirrored in
            <classname>Zend_Service_Audioscrobbler</classname>. For more information about the Audioscrobbler REST Web Service,
            please visit the <ulink url="http://www.audioscrobbler.net/data/webservices/">Audioscrobbler Web Service
            site</ulink>.
        </para>

    </sect2>

    <sect2 id="zend.service.audioscrobbler.users">

        <title>Users</title>

        <para>
            In order to retrieve information for a specific user, the <methodname>setUser()</methodname> method is first used to
            select the user for which data are to be retrieved. <classname>Zend_Service_Audioscrobbler</classname> provides
            several methods for retrieving data specific to a single user:
            <itemizedlist>
                <listitem>
                    <para>
                        <methodname>userGetProfileInformation()</methodname>: Returns a SimpleXML object containing the current
                        user's profile information.
                    </para>
                </listitem>
                <listitem>
                    <para>
                        <methodname>userGetTopArtists()</methodname>: Returns a SimpleXML object containing a list of the current
                        user's most listened to artists.
                    </para>
                </listitem>
                <listitem>
                    <para>
                        <methodname>userGetTopAlbums()</methodname>: Returns a SimpleXML object containing a list of the current
                        user's most listened to albums.
                    </para>
                </listitem>
                <listitem>
                    <para>
                        <methodname>userGetTopTracks()</methodname>: Returns a SimpleXML object containing a list of the current
                        user's most listened to tracks.
                    </para>
                </listitem>
                <listitem>
                    <para>
                        <methodname>userGetTopTags()</methodname>: Returns a SimpleXML object containing a list of tags most applied
                        by the current user.
                    </para>
                </listitem>
                <listitem>
                    <para>
                        <methodname>userGetTopTagsForArtist()</methodname>: Requires that an artist be set via
                        <methodname>setArtist()</methodname>. Returns a SimpleXML object containing the tags most applied to the
                        current artist by the current user.
                    </para>
                </listitem>
                <listitem>
                    <para>
                        <methodname>userGetTopTagsForAlbum()</methodname>: Requires that an album be set via
                        <methodname>setAlbum()</methodname>. Returns a SimpleXML object containing the tags most applied to the
                        current album by the current user.
                    </para>
                </listitem>
                <listitem>
                    <para>
                        <methodname>userGetTopTagsForTrack()</methodname>: Requires that a track be set via
                        <methodname>setTrack()</methodname>. Returns a SimpleXML object containing the tags most applied to the
                        current track by the current user.
                    </para>
                </listitem>
                <listitem>
                    <para>
                        <methodname>userGetFriends()</methodname>: Returns a SimpleXML object containing the user names of the
                        current user's friends.
                    </para>
                </listitem>
                <listitem>
                    <para>
                        <methodname>userGetNeighbours()</methodname>: Returns a SimpleXML object containing the user names of
                        people with similar listening habits to the current user.
                    </para>
                </listitem>
                <listitem>
                    <para>
                        <methodname>userGetRecentTracks()</methodname>: Returns a SimpleXML object containing the 10 tracks most
                        recently played by the current user.
                    </para>
                </listitem>
                <listitem>
                    <para>
                        <methodname>userGetRecentBannedTracks()</methodname>: Returns a SimpleXML object containing a list of the 10
                        tracks most recently banned by the current user.
                    </para>
                </listitem>
                <listitem>
                    <para>
                        <methodname>userGetRecentLovedTracks()</methodname>: Returns a SimpleXML object containing a list of the 10
                        tracks most recently loved by the current user.
                    </para>
                </listitem>
                <listitem>
                    <para>
                        <methodname>userGetRecentJournals()</methodname>: Returns a SimpleXML object containing a list of the
                        current user's most recent journal entries.
                    </para>
                </listitem>
                <listitem>
                    <para>
                        <methodname>userGetWeeklyChartList()</methodname>: Returns a SimpleXML object containing a list of weeks for
                        which there exist Weekly Charts for the current user.
                    </para>
                </listitem>
                <listitem>
                    <para>
                        <methodname>userGetRecentWeeklyArtistChart()</methodname>: Returns a SimpleXML object containing the most
                        recent Weekly Artist Chart for the current user.
                    </para>
                </listitem>
                <listitem>
                    <para>
                        <methodname>userGetRecentWeeklyAlbumChart()</methodname>: Returns a SimpleXML object containing the most
                        recent Weekly Album Chart for the current user.
                    </para>
                </listitem>
                <listitem>
                    <para>
                        <methodname>userGetRecentWeeklyTrackChart()</methodname>: Returns a SimpleXML object containing the most
                        recent Weekly Track Chart for the current user.
                    </para>
                </listitem>
                <listitem>
                    <para>
                        <methodname>userGetPreviousWeeklyArtistChart($fromDate, $toDate)</methodname>: Returns a SimpleXML object
                        containing the Weekly Artist Chart from <varname>$fromDate</varname> to <varname>$toDate</varname> for the
                        current user.
                    </para>
                </listitem>
                <listitem>
                    <para>
                        <methodname>userGetPreviousWeeklyAlbumChart($fromDate, $toDate)</methodname>: Returns a SimpleXML object
                        containing the Weekly Album Chart from <varname>$fromDate</varname> to <varname>$toDate</varname> for the
                        current user.
                    </para>
                </listitem>
                <listitem>
                    <para>
                        <methodname>userGetPreviousWeeklyTrackChart($fromDate, $toDate)</methodname>: Returns a SimpleXML object
                        containing the Weekly Track Chart from <varname>$fromDate</varname> to <varname>$toDate</varname> for the
                        current user.
                    </para>
                </listitem>
            </itemizedlist>
        </para>

        <example id="zend.service.audioscrobbler.users.example.profile_information">

            <title>Retrieving User Profile Information</title>

            <para>
                In this example, we use the <methodname>setUser()</methodname> and <methodname>userGetProfileInformation()</methodname> methods
                to retrieve a specific user's profile information:
            </para>

            <programlisting language="php"><![CDATA[
$as = new Zend_Service_Audioscrobbler();
// Set the user whose profile information we want to retrieve
$as->setUser('BigDaddy71');
// Retrieve BigDaddy71's profile information
$profileInfo = $as->userGetProfileInformation();
// Display some of it
print "Information for $profileInfo->realname "
    . "can be found at $profileInfo->url";
]]></programlisting>

        </example>

        <example id="zend.service.audioscrobbler.users.example.weekly_artist_chart">

            <title>Retrieving a User's Weekly Artist Chart</title>

            <programlisting language="php"><![CDATA[
$as = new Zend_Service_Audioscrobbler();
// Set the user whose profile weekly artist chart we want to retrieve
$as->setUser('lo_fye');
// Retrieves a list of previous weeks for which there are chart data
$weeks = $as->userGetWeeklyChartList();
if (count($weeks) < 1) {
    echo 'No data available';
}
sort($weeks); // Order the list of weeks

$as->setFromDate($weeks[0]); // Set the starting date
$as->setToDate($weeks[0]); // Set the ending date

$previousWeeklyArtists = $as->userGetPreviousWeeklyArtistChart();

echo 'Artist Chart For Week Of '
   . date('Y-m-d h:i:s', $as->from_date)
   . '<br />';

foreach ($previousWeeklyArtists as $artist) {
    // Display the artists' names with links to their profiles
    print '<a href="' . $artist->url . '">' . $artist->name . '</a><br />';
}
]]></programlisting>

        </example>

    </sect2>

    <sect2 id="zend.service.audioscrobbler.artists">

        <title>Artists</title>

        <para>
            <classname>Zend_Service_Audioscrobbler</classname> provides several methods for retrieving data about a specific
            artist, specified via the <methodname>setArtist()</methodname> method:
            <itemizedlist>
                <listitem>
                    <para>
                        <methodname>artistGetRelatedArtists()</methodname>: Returns a SimpleXML object containing a list of
                        Artists similar to the current Artist.
                    </para>
                </listitem>
                <listitem>
                    <para>
                        <methodname>artistGetTopFans()</methodname>: Returns a SimpleXML object containing a list of Users who
                        listen most to the current Artist.
                    </para>
                </listitem>
                <listitem>
                    <para>
                        <methodname>artistGetTopTracks()</methodname>: Returns a SimpleXML object containing a list of the current
                        Artist's top-rated Tracks.
                    </para>
                </listitem>
                <listitem>
                    <para>
                        <methodname>artistGetTopAlbums()</methodname>: Returns a SimpleXML object containing a list of the current
                        Artist's top-rated Albums.
                    </para>
                </listitem>
                <listitem>
                    <para>
                        <methodname>artistGetTopTags()</methodname>: Returns a SimpleXML object containing a list of the Tags most
                        frequently applied to current Artist.
                    </para>
                </listitem>
            </itemizedlist>
        </para>

        <example id="zend.service.audioscrobbler.artists.example.related_artists">

            <title>Retrieving Related Artists</title>

            <programlisting language="php"><![CDATA[
$as = new Zend_Service_Audioscrobbler();
// Set the artist for whom you would like to retrieve related artists
$as->setArtist('LCD Soundsystem');
// Retrieve the related artists
$relatedArtists = $as->artistGetRelatedArtists();
foreach ($relatedArtists as $artist) {
    // Display the related artists
    print '<a href="' . $artist->url . '">' . $artist->name . '</a><br />';
}
]]></programlisting>

        </example>

    </sect2>

    <sect2 id="zend.service.audioscrobbler.tracks">

        <title>Tracks</title>

        <para>
            <classname>Zend_Service_Audioscrobbler</classname> provides two methods for retrieving data specific to a single
            track, specified via the <methodname>setTrack()</methodname> method:
            <itemizedlist>
                <listitem>
                    <para>
                        <methodname>trackGetTopFans()</methodname>: Returns a SimpleXML object containing a list of Users who
                        listen most to the current Track.
                    </para>
                </listitem>
                <listitem>
                    <para>
                        <methodname>trackGetTopTags()</methodname>: Returns a SimpleXML object containing a list of the Tags most
                        frequently applied to the current Track.
                    </para>
                </listitem>
            </itemizedlist>
        </para>

    </sect2>

    <sect2 id="zend.service.audioscrobbler.tags">

        <title>Tags</title>

        <para>
            <classname>Zend_Service_Audioscrobbler</classname> provides several methods for retrieving data specific to a single
            tag, specified via the <methodname>setTag()</methodname> method:
            <itemizedlist>
                <listitem>
                    <para>
                        <methodname>tagGetOverallTopTags()</methodname>: Returns a SimpleXML object containing a list of Tags most
                        frequently used on Audioscrobbler.
                    </para>
                </listitem>
                <listitem>
                    <para>
                        <methodname>tagGetTopArtists()</methodname>: Returns a SimpleXML object containing a list of Artists to whom
                        the current Tag was most frequently applied.
                    </para>
                </listitem>
                <listitem>
                    <para>
                        <methodname>tagGetTopAlbums()</methodname>: Returns a SimpleXML object containing a list of Albums to which
                        the current Tag was most frequently applied.
                    </para>
                </listitem>
                <listitem>
                    <para>
                        <methodname>tagGetTopTracks()</methodname>: Returns a SimpleXML object containing a list of Tracks to which
                        the current Tag was most frequently applied.
                    </para>
                </listitem>
            </itemizedlist>
        </para>

    </sect2>

    <sect2 id="zend.service.audioscrobbler.groups">

        <title>Groups</title>

        <para>
            <classname>Zend_Service_Audioscrobbler</classname> provides several methods for retrieving data specific to a single
            group, specified via the <methodname>setGroup()</methodname> method:
            <itemizedlist>
                <listitem>
                    <para>
                        <methodname>groupGetRecentJournals()</methodname>: Returns a SimpleXML object containing a list of recent
                        journal posts by Users in the current Group.
                    </para>
                </listitem>
                <listitem>
                    <para>
                        <methodname>groupGetWeeklyChart()</methodname>: Returns a SimpleXML object containing a list of weeks for
                        which there exist Weekly Charts for the current Group.
                    </para>
                </listitem>
                <listitem>
                    <para>
                        <methodname>groupGetRecentWeeklyArtistChart()</methodname>: Returns a SimpleXML object containing the most
                        recent Weekly Artist Chart for the current Group.
                    </para>
                </listitem>
                <listitem>
                    <para>
                        <methodname>groupGetRecentWeeklyAlbumChart()</methodname>: Returns a SimpleXML object containing the most
                        recent Weekly Album Chart for the current Group.
                    </para>
                </listitem>
                <listitem>
                    <para>
                        <methodname>groupGetRecentWeeklyTrackChart()</methodname>: Returns a SimpleXML object containing the most
                        recent Weekly Track Chart for the current Group.
                    </para>
                </listitem>
                <listitem>
                    <para>
                        <methodname>groupGetPreviousWeeklyArtistChart($fromDate, $toDate)</methodname>: Requires
                        <methodname>setFromDate()</methodname> and <methodname>setToDate()</methodname>. Returns a SimpleXML object containing
                        the Weekly Artist Chart from the current fromDate to the current toDate for the current Group.
                    </para>
                </listitem>
                <listitem>
                    <para>
                        <methodname>groupGetPreviousWeeklyAlbumChart($fromDate, $toDate)</methodname>: Requires
                        <methodname>setFromDate()</methodname> and <methodname>setToDate()</methodname>. Returns a SimpleXML object containing
                        the Weekly Album Chart from the current fromDate to the current toDate for the current Group.
                    </para>
                </listitem>
                <listitem>
                    <para>
                        <methodname>groupGetPreviousWeeklyTrackChart($fromDate, $toDate)</methodname>: Returns a SimpleXML object
                        containing the Weekly Track Chart from the current fromDate to the current toDate for the
                        current Group.
                    </para>
                </listitem>
            </itemizedlist>
        </para>

    </sect2>

    <sect2 id="zend.service.audioscrobbler.forums">

        <title>Forums</title>

        <para>
            <classname>Zend_Service_Audioscrobbler</classname> provides a method for retrieving data specific to a single forum,
            specified via the <methodname>setForum()</methodname> method:
            <itemizedlist>
                <listitem>
                    <para>
                        <methodname>forumGetRecentPosts()</methodname>: Returns a SimpleXML object containing a list of recent posts
                        in the current forum.
                    </para>
                </listitem>
            </itemizedlist>
        </para>

    </sect2>

</sect1>
<!--
vim:se ts=4 sw=4 et:
-->