documentation/manual/en/module_specs/Zend_Service_Audioscrobbler.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!-- Reviewed: no -->
   3 <sect1 id="zend.service.audioscrobbler">
   4     <title>Zend_Service_Audioscrobbler</title>
   5
   6     <sect2 id="zend.service.audioscrobbler.introduction">
   7         <title>Introduction</title>
   8
   9         <para>
  10             <classname>Zend_Service_Audioscrobbler</classname> is a simple <acronym>API</acronym>
  11             for using the Audioscrobbler REST Web Service. The Audioscrobbler Web Service provides
  12             access to its database of Users, Artists, Albums, Tracks, Tags, Groups, and Forums. The
  13             methods of the <classname>Zend_Service_Audioscrobbler</classname> class begin with one
  14             of these terms. The syntax and namespaces of the Audioscrobbler Web Service are mirrored
  15             in <classname>Zend_Service_Audioscrobbler</classname>. For more information about the
  16             Audioscrobbler REST Web Service, please visit the <ulink
  17                 url="http://www.audioscrobbler.net/data/webservices/">Audioscrobbler Web Service
  18                 site</ulink>.
  19         </para>
  20     </sect2>
  21
  22     <sect2 id="zend.service.audioscrobbler.users">
  23         <title>Users</title>
  24
  25         <para>
  26             In order to retrieve information for a specific user, the
  27             <methodname>setUser()</methodname> method is first used to select the user for which
  28             data are to be retrieved. <classname>Zend_Service_Audioscrobbler</classname> provides
  29             several methods for retrieving data specific to a single user:
  30
  31             <itemizedlist>
  32                 <listitem>
  33                     <para>
  34                         <methodname>userGetProfileInformation()</methodname>: Returns a SimpleXML
  35                         object containing the current user's profile information.
  36                     </para>
  37                 </listitem>
  38
  39                 <listitem>
  40                     <para>
  41                         <methodname>userGetTopArtists()</methodname>: Returns a SimpleXML object
  42                         containing a list of the current user's most listened to artists.
  43                     </para>
  44                 </listitem>
  45
  46                 <listitem>
  47                     <para>
  48                         <methodname>userGetTopAlbums()</methodname>: Returns a SimpleXML object
  49                         containing a list of the current user's most listened to albums.
  50                     </para>
  51                 </listitem>
  52
  53                 <listitem>
  54                     <para>
  55                         <methodname>userGetTopTracks()</methodname>: Returns a SimpleXML object
  56                         containing a list of the current user's most listened to tracks.
  57                     </para>
  58                 </listitem>
  59
  60                 <listitem>
  61                     <para>
  62                         <methodname>userGetTopTags()</methodname>: Returns a SimpleXML object
  63                         containing a list of tags most applied by the current user.
  64                     </para>
  65                 </listitem>
  66
  67                 <listitem>
  68                     <para>
  69                         <methodname>userGetTopTagsForArtist()</methodname>: Requires that an artist
  70                         be set via <methodname>setArtist()</methodname>. Returns a SimpleXML object
  71                         containing the tags most applied to the current artist by the current user.
  72                     </para>
  73                 </listitem>
  74
  75                 <listitem>
  76                     <para>
  77                         <methodname>userGetTopTagsForAlbum()</methodname>: Requires that an album be
  78                         set via <methodname>setAlbum()</methodname>. Returns a SimpleXML object
  79                         containing the tags most applied to the current album by the current user.
  80                     </para>
  81                 </listitem>
  82
  83                 <listitem>
  84                     <para>
  85                         <methodname>userGetTopTagsForTrack()</methodname>: Requires that a track be
  86                         set via <methodname>setTrack()</methodname>. Returns a SimpleXML object
  87                         containing the tags most applied to the current track by the current user.
  88                     </para>
  89                 </listitem>
  90
  91                 <listitem>
  92                     <para>
  93                         <methodname>userGetFriends()</methodname>: Returns a SimpleXML object
  94                         containing the user names of the current user's friends.
  95                     </para>
  96                 </listitem>
  97
  98                 <listitem>
  99                     <para>
 100                         <methodname>userGetNeighbours()</methodname>: Returns a SimpleXML object
 101                         containing the user names of people with similar listening habits to the
 102                         current user.
 103                     </para>
 104                 </listitem>
 105
 106                 <listitem>
 107                     <para>
 108                         <methodname>userGetRecentTracks()</methodname>: Returns a SimpleXML object
 109                         containing the 10 tracks most recently played by the current user.
 110                     </para>
 111                 </listitem>
 112
 113                 <listitem>
 114                     <para>
 115                         <methodname>userGetRecentBannedTracks()</methodname>: Returns a SimpleXML
 116                         object containing a list of the 10 tracks most recently banned by the
 117                         current user.
 118                     </para>
 119                 </listitem>
 120
 121                 <listitem>
 122                     <para>
 123                         <methodname>userGetRecentLovedTracks()</methodname>: Returns a SimpleXML
 124                         object containing a list of the 10 tracks most recently loved by the current
 125                         user.
 126                     </para>
 127                 </listitem>
 128
 129                 <listitem>
 130                     <para>
 131                         <methodname>userGetRecentJournals()</methodname>: Returns a SimpleXML object
 132                         containing a list of the current user's most recent journal entries.
 133                     </para>
 134                 </listitem>
 135
 136                 <listitem>
 137                     <para>
 138                         <methodname>userGetWeeklyChartList()</methodname>: Returns a SimpleXML
 139                         object containing a list of weeks for which there exist Weekly Charts for
 140                         the current user.
 141                     </para>
 142                 </listitem>
 143
 144                 <listitem>
 145                     <para>
 146                         <methodname>userGetRecentWeeklyArtistChart()</methodname>: Returns a
 147                         SimpleXML object containing the most recent Weekly Artist Chart for the
 148                         current user.
 149                     </para>
 150                 </listitem>
 151
 152                 <listitem>
 153                     <para>
 154                         <methodname>userGetRecentWeeklyAlbumChart()</methodname>: Returns a
 155                         SimpleXML object containing the most recent Weekly Album Chart for the
 156                         current user.
 157                     </para>
 158                 </listitem>
 159
 160                 <listitem>
 161                     <para>
 162                         <methodname>userGetRecentWeeklyTrackChart()</methodname>: Returns a
 163                         SimpleXML object containing the most recent Weekly Track Chart for the
 164                         current user.
 165                     </para>
 166                 </listitem>
 167
 168                 <listitem>
 169                     <para>
 170                         <methodname>userGetPreviousWeeklyArtistChart($fromDate,
 171                             $toDate)</methodname>: Returns a SimpleXML object containing the Weekly
 172                         Artist Chart from <varname>$fromDate</varname> to <varname>$toDate</varname>
 173                         for the current user.
 174                     </para>
 175                 </listitem>
 176
 177                 <listitem>
 178                     <para>
 179                         <methodname>userGetPreviousWeeklyAlbumChart($fromDate,
 180                             $toDate)</methodname>: Returns a SimpleXML object containing the Weekly
 181                         Album Chart from <varname>$fromDate</varname> to <varname>$toDate</varname>
 182                         for the current user.
 183                     </para>
 184                 </listitem>
 185
 186                 <listitem>
 187                     <para>
 188                         <methodname>userGetPreviousWeeklyTrackChart($fromDate,
 189                             $toDate)</methodname>: Returns a SimpleXML object containing the Weekly
 190                         Track Chart from <varname>$fromDate</varname> to <varname>$toDate</varname>
 191                         for the current user.
 192                     </para>
 193                 </listitem>
 194             </itemizedlist>
 195         </para>
 196
 197         <example id="zend.service.audioscrobbler.users.example.profile_information">
 198             <title>Retrieving User Profile Information</title>
 199
 200             <para>
 201                 In this example, we use the <methodname>setUser()</methodname> and
 202                 <methodname>userGetProfileInformation()</methodname> methods to retrieve a specific
 203                 user's profile information:
 204             </para>
 205
 206             <programlisting language="php"><![CDATA[
 207 $as = new Zend_Service_Audioscrobbler();
 208 // Set the user whose profile information we want to retrieve
 209 $as->setUser('BigDaddy71');
 210 // Retrieve BigDaddy71's profile information
 211 $profileInfo = $as->userGetProfileInformation();
 212 // Display some of it
 213 print "Information for $profileInfo->realname "
 214     . "can be found at $profileInfo->url";
 215 ]]></programlisting>
 216         </example>
 217
 218         <example id="zend.service.audioscrobbler.users.example.weekly_artist_chart">
 219             <title>Retrieving a User's Weekly Artist Chart</title>
 220
 221             <programlisting language="php"><![CDATA[
 222 $as = new Zend_Service_Audioscrobbler();
 223 // Set the user whose profile weekly artist chart we want to retrieve
 224 $as->setUser('lo_fye');
 225 // Retrieves a list of previous weeks for which there are chart data
 226 $weeks = $as->userGetWeeklyChartList();
 227 if (count($weeks) < 1) {
 228     echo 'No data available';
 229 }
 230 sort($weeks); // Order the list of weeks
 231
 232 $as->setFromDate($weeks[0]); // Set the starting date
 233 $as->setToDate($weeks[0]); // Set the ending date
 234
 235 $previousWeeklyArtists = $as->userGetPreviousWeeklyArtistChart();
 236
 237 echo 'Artist Chart For Week Of '
 238    . date('Y-m-d h:i:s', $as->from_date)
 239    . '<br />';
 240
 241 foreach ($previousWeeklyArtists as $artist) {
 242     // Display the artists' names with links to their profiles
 243     print '<a href="' . $artist->url . '">' . $artist->name . '</a><br />';
 244 }
 245 ]]></programlisting>
 246         </example>
 247     </sect2>
 248
 249     <sect2 id="zend.service.audioscrobbler.artists">
 250         <title>Artists</title>
 251
 252         <para>
 253             <classname>Zend_Service_Audioscrobbler</classname> provides several methods for
 254             retrieving data about a specific artist, specified via the
 255             <methodname>setArtist()</methodname> method:
 256
 257             <itemizedlist>
 258                 <listitem>
 259                     <para>
 260                         <methodname>artistGetRelatedArtists()</methodname>: Returns a SimpleXML
 261                         object containing a list of Artists similar to the current Artist.
 262                     </para>
 263                 </listitem>
 264
 265                 <listitem>
 266                     <para>
 267                         <methodname>artistGetTopFans()</methodname>: Returns a SimpleXML object
 268                         containing a list of Users who listen most to the current Artist.
 269                     </para>
 270                 </listitem>
 271
 272                 <listitem>
 273                     <para>
 274                         <methodname>artistGetTopTracks()</methodname>: Returns a SimpleXML object
 275                         containing a list of the current Artist's top-rated Tracks.
 276                     </para>
 277                 </listitem>
 278
 279                 <listitem>
 280                     <para>
 281                         <methodname>artistGetTopAlbums()</methodname>: Returns a SimpleXML object
 282                         containing a list of the current Artist's top-rated Albums.
 283                     </para>
 284                 </listitem>
 285
 286                 <listitem>
 287                     <para>
 288                         <methodname>artistGetTopTags()</methodname>: Returns a SimpleXML object
 289                         containing a list of the Tags most frequently applied to current Artist.
 290                     </para>
 291                 </listitem>
 292             </itemizedlist>
 293         </para>
 294
 295         <example id="zend.service.audioscrobbler.artists.example.related_artists">
 296             <title>Retrieving Related Artists</title>
 297
 298             <programlisting language="php"><![CDATA[
 299 $as = new Zend_Service_Audioscrobbler();
 300 // Set the artist for whom you would like to retrieve related artists
 301 $as->setArtist('LCD Soundsystem');
 302 // Retrieve the related artists
 303 $relatedArtists = $as->artistGetRelatedArtists();
 304 foreach ($relatedArtists as $artist) {
 305     // Display the related artists
 306     print '<a href="' . $artist->url . '">' . $artist->name . '</a><br />';
 307 }
 308 ]]></programlisting>
 309         </example>
 310     </sect2>
 311
 312     <sect2 id="zend.service.audioscrobbler.tracks">
 313         <title>Tracks</title>
 314
 315         <para>
 316             <classname>Zend_Service_Audioscrobbler</classname> provides two methods for retrieving
 317             data specific to a single track, specified via the <methodname>setTrack()</methodname>
 318             method:
 319
 320             <itemizedlist>
 321                 <listitem>
 322                     <para>
 323                         <methodname>trackGetTopFans()</methodname>: Returns a SimpleXML object
 324                         containing a list of Users who listen most to the current Track.
 325                     </para>
 326                 </listitem>
 327
 328                 <listitem>
 329                     <para>
 330                         <methodname>trackGetTopTags()</methodname>: Returns a SimpleXML object
 331                         containing a list of the Tags most frequently applied to the current Track.
 332                     </para>
 333                 </listitem>
 334             </itemizedlist>
 335         </para>
 336     </sect2>
 337
 338     <sect2 id="zend.service.audioscrobbler.tags">
 339         <title>Tags</title>
 340
 341         <para>
 342             <classname>Zend_Service_Audioscrobbler</classname> provides several methods for
 343             retrieving data specific to a single tag, specified via the
 344             <methodname>setTag()</methodname> method:
 345
 346             <itemizedlist>
 347                 <listitem>
 348                     <para>
 349                         <methodname>tagGetOverallTopTags()</methodname>: Returns a SimpleXML object
 350                         containing a list of Tags most frequently used on Audioscrobbler.
 351                     </para>
 352                 </listitem>
 353
 354                 <listitem>
 355                     <para>
 356                         <methodname>tagGetTopArtists()</methodname>: Returns a SimpleXML object
 357                         containing a list of Artists to whom the current Tag was most frequently
 358                         applied.
 359                     </para>
 360                 </listitem>
 361
 362                 <listitem>
 363                     <para>
 364                         <methodname>tagGetTopAlbums()</methodname>: Returns a SimpleXML object
 365                         containing a list of Albums to which the current Tag was most frequently
 366                         applied.
 367                     </para>
 368                 </listitem>
 369
 370                 <listitem>
 371                     <para>
 372                         <methodname>tagGetTopTracks()</methodname>: Returns a SimpleXML object
 373                         containing a list of Tracks to which the current Tag was most frequently
 374                         applied.
 375                     </para>
 376                 </listitem>
 377             </itemizedlist>
 378         </para>
 379     </sect2>
 380
 381     <sect2 id="zend.service.audioscrobbler.groups">
 382         <title>Groups</title>
 383
 384         <para>
 385             <classname>Zend_Service_Audioscrobbler</classname> provides several methods for
 386             retrieving data specific to a single group, specified via the
 387             <methodname>setGroup()</methodname> method:
 388
 389             <itemizedlist>
 390                 <listitem>
 391                     <para>
 392                         <methodname>groupGetRecentJournals()</methodname>: Returns a SimpleXML
 393                         object containing a list of recent journal posts by Users in the current
 394                         Group.
 395                     </para>
 396                 </listitem>
 397
 398                 <listitem>
 399                     <para>
 400                         <methodname>groupGetWeeklyChart()</methodname>: Returns a SimpleXML object
 401                         containing a list of weeks for which there exist Weekly Charts for the
 402                         current Group.
 403                     </para>
 404                 </listitem>
 405
 406                 <listitem>
 407                     <para>
 408                         <methodname>groupGetRecentWeeklyArtistChart()</methodname>: Returns a
 409                         SimpleXML object containing the most recent Weekly Artist Chart for the
 410                         current Group.
 411                     </para>
 412                 </listitem>
 413
 414                 <listitem>
 415                     <para>
 416                         <methodname>groupGetRecentWeeklyAlbumChart()</methodname>: Returns a
 417                         SimpleXML object containing the most recent Weekly Album Chart for the
 418                         current Group.
 419                     </para>
 420                 </listitem>
 421
 422                 <listitem>
 423                     <para>
 424                         <methodname>groupGetRecentWeeklyTrackChart()</methodname>: Returns a
 425                         SimpleXML object containing the most recent Weekly Track Chart for the
 426                         current Group.
 427                     </para>
 428                 </listitem>
 429
 430                 <listitem>
 431                     <para>
 432                         <methodname>groupGetPreviousWeeklyArtistChart($fromDate,
 433                             $toDate)</methodname>: Requires <methodname>setFromDate()</methodname>
 434                         and <methodname>setToDate()</methodname>. Returns a SimpleXML object
 435                         containing the Weekly Artist Chart from the current fromDate to the current
 436                         toDate for the current Group.
 437                     </para>
 438                 </listitem>
 439
 440                 <listitem>
 441                     <para>
 442                         <methodname>groupGetPreviousWeeklyAlbumChart($fromDate,
 443                             $toDate)</methodname>: Requires <methodname>setFromDate()</methodname>
 444                         and <methodname>setToDate()</methodname>. Returns a SimpleXML object
 445                         containing the Weekly Album Chart from the current fromDate to the current
 446                         toDate for the current Group.
 447                     </para>
 448                 </listitem>
 449
 450                 <listitem>
 451                     <para>
 452                         <methodname>groupGetPreviousWeeklyTrackChart($fromDate,
 453                             $toDate)</methodname>: Returns a SimpleXML object containing the Weekly
 454                         Track Chart from the current fromDate to the current toDate for the current
 455                         Group.
 456                     </para>
 457                 </listitem>
 458             </itemizedlist>
 459         </para>
 460     </sect2>
 461
 462     <sect2 id="zend.service.audioscrobbler.forums">
 463         <title>Forums</title>
 464
 465         <para>
 466             <classname>Zend_Service_Audioscrobbler</classname> provides a method for retrieving data
 467             specific to a single forum, specified via the <methodname>setForum()</methodname>
 468             method:
 469
 470             <itemizedlist>
 471                 <listitem>
 472                     <para>
 473                         <methodname>forumGetRecentPosts()</methodname>: Returns a SimpleXML object
 474                         containing a list of recent posts in the current forum.
 475                     </para>
 476                 </listitem>
 477             </itemizedlist>
 478         </para>
 479     </sect2>
 480 </sect1>
 481 <!--
 482 vim:se ts=4 sw=4 et:
 483 -->