repo_zf1/documentation/manual/en/module_specs/Zend_Service_Audioscrobbler.xml

<?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:
-->