Method: Album Charts

Returns album charts for a given time frame (i.e., top 10 album this month by "number of downloads"). Results are sorted and filtered.

Request URL

The object is album and the action is charts. The base request URL is:

http://api.emusic.com/album/charts?apiKey=myKey

Request Parameters

Following is a list of required and optional query string parameters for the Album Charts method. For more information about individual request parameters, see request parameters.

Name Required Default Description
apiKey YES none The developer API key. This is required for all methods.
filter no downloadedThisMonth The charts filter. Recommended values: downloadedThisMonth, downloadedThisWeek, downloadedToday
primarySort no albumDownloadsMonth The charts sort. Recommended values: albumDownloadsMonth, albumDownloadsWeek, albumDownloadsToday
primaryAscending no false The charts sort direction. Note that a "top 10" chart would use a primaryAscending value of "false" (largest to least number of downloads...).
page no 1 The starting page index of returned albums. (Used for paginating through longer result lists.)
perPage no 20 The number of albums to return per page.
format no XML The format of the response (XML, JSON, JSONP).
callback depends none The name of the JavaScript callback method for the JSONP format. (Required for JSONP responses only.)
fref no none The eMusic partner tag. If provided, the FREF value is automatically added to all appropriate eMusic links.

Example Requests

// Returns album charts (all default values).
http://api.emusic.com/artist/charts?apiKey=myKey

// Returns top albums for the week.
http://api.emusic.com/album/charts?apiKey=myKey&primaryFilter=downloadedThisWeek&primarySort=albumDownloadsWeek

Response Format

Following is a list of returned elements for the Artist Charts method. For more information about individual response elements, see Response Elements.

Name Type Returned Description
status status always Contains a result code.
messages list on error Contains one or more messages.
options options on ok Contains a list of method options.
browse browse on ok Contains the <browse> filters and sorts.
view view on ok Contains the paginate result counts.
albums list on ok Contains a paged list of charted albums, filtered and sorted by the given criteria. See the example response below for typical album elements.

Example Response

(Only five elements are displayed in each list...)

<?xml version="1.0" encoding="UTF-8"?>
<response xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <status code="200">ok</status>
    <options format="xml"/>
    <browse country="US" filter="downloadedThisMonth" primaryAscending="false" primarySort="albumDownloadsMonth" secondarySort="artist" type="album"/>
    <view page="1" pages="9715" perPage="20" total="194286"/>
    <albums list="true" size="20">
        <album added="2010-04-05" id="11859783" image="http://images.emusic.com/music/images/album/0/118/597/11859783/300x300.jpg" name="Broken Bells" released="2010-03-09" url="http://www.emusic.com/album/Broken-Bells-Broken-Bells-MP3-Download/11859783.html">
            <artist id="12640123" name="Broken Bells" url="http://www.emusic.com/artist/Broken-Bells-MP3-Download/12640123.html"/>
            <label id="267000" name="Columbia" url="http://www.emusic.com/label/MP3-Download/267000.html"/>
            <genre id="284" name="Alternative/Punk" url="http://www.emusic.com/genre/284.html"/>
            <ratings>
                <communityRating average="4.26"/>
            </ratings>
        </album>
        <album added="2010-03-22" id="11872403" image="http://images.emusic.com/music/images/album/0/118/724/11872403/300x300.jpg" name="Volume Two" released="2010-03-23" url="http://www.emusic.com/album/She-Him-Volume-Two-MP3-Download/11872403.html">
            <artist id="11956549" name="She &amp; Him" url="http://www.emusic.com/artist/She-Him-MP3-Download/11956549.html"/>
            <label id="109173" name="Merge Records" url="http://www.emusic.com/label/MP3-Download/109173.html"/>
            <genre id="284" name="Alternative/Punk" url="http://www.emusic.com/genre/284.html"/>
            <ratings>
                <communityRating average="4.11"/>
            </ratings>
        </album>
        <album added="2010-04-05" id="11867360" image="http://images.emusic.com/music/images/album/0/118/673/11867360/300x300.jpg" name="I Learned the Hard Way (Bonus Version)" released="2010-04-06" url="http://www.emusic.com/album/Sharon-Jones-and-the-Dap-Kings-I-Learned-the-Hard-Way-Bonus-Version-MP3-Download/11867360.html">
            <artist id="11599806" name="Sharon Jones and the Dap-Kings" url="http://www.emusic.com/artist/Sharon-Jones-and-the-Dap-Kings-MP3-Download/11599806.html"/>
            <label id="130470" name="Daptone Records / The Orchard" url="http://www.emusic.com/label/MP3-Download/130470.html"/>
            <genre id="282" name="Hip-Hop/R&amp;amp;B" url="http://www.emusic.com/genre/282.html"/>
            <ratings>
                <communityRating average="4.35"/>
            </ratings>
        </album>
        <album added="2010-04-12" id="11885125" image="http://images.emusic.com/music/images/album/0/118/851/11885125/300x300.jpg" name="Congratulations" released="2010-04-13" url="http://www.emusic.com/album/MGMT-Congratulations-MP3-Download/11885125.html">
            <artist id="11925947" name="MGMT" url="http://www.emusic.com/artist/MGMT-MP3-Download/11925947.html"/>
            <label id="267000" name="Columbia" url="http://www.emusic.com/label/MP3-Download/267000.html"/>
            <genre id="284" name="Alternative/Punk" url="http://www.emusic.com/genre/284.html"/>
            <ratings>
                <communityRating average="3.53"/>
            </ratings>
        </album>
        <album added="2010-04-06" id="11873844" image="http://images.emusic.com/music/images/album/0/118/738/11873844/300x300.jpg" name="Go" released="2010-04-06" url="http://www.emusic.com/album/J%C3%B3nsi-Go-MP3-Download/11873844.html">
            <artist id="12408804" name="Jónsi" url="http://www.emusic.com/artist/J%C3%B3nsi-MP3-Download/12408804.html"/>
            <label id="94313" name="XL Recordings" url="http://www.emusic.com/label/MP3-Download/94313.html"/>
            <genre id="284" name="Alternative/Punk" url="http://www.emusic.com/genre/284.html"/>
            <ratings>
                <communityRating average="4.43"/>
            </ratings>
        </album>
    </albums>
</response>            

version 3 as of 3 months ago by Ben Kotch

0 Comments

Please sign in to post a comment.