Method: Album Picks

Returns "editor's picks" for albums, for a given time frame (i.e., top 10 "editor's picks" albums this month by "number of downloads"). Results are sorted and filtered.

Request URL

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

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

Request Parameters

Following is a list of required and optional query string parameters for the Album Picks 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.
primarySort no albumDownloadsMonth The charts sort. Recommended values: albumDownloadsMonth, albumDownloadsWeek, albumDownloadsToday
primaryAscending no false The sort direction. Note that a "top 10" editor's picks 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 "editor's picks" for albums (all default values).
http://api.emusic.com/album/picks?apiKey=myKey

// Returns the third page of 10 "editor's picks" albums for the week.
http://api.emusic.com/album/picks?apiKey=myKey&primarySort=albumDownloadsWeek&perPage=10&page=3

Response Format

Following is a list of returned elements for the Albums Picks 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 "editor's picks" 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="editorsPicks" primaryAscending="false" primarySort="albumDownloadsMonth" secondarySort="artist" type="album"/>
    <view page="1" pages="642" perPage="20" total="12825"/>
    <albums list="true" size="20">
        <album added="2010-04-05" id="11867360" image="http://images.emusic-test.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-19" id="11908697" image="http://images.emusic-test.com/music/images/album/0/119/086/11908697/300x300.jpg" name="Swim" released="2010-04-20" url="http://www.emusic.com/album/Caribou-Swim-MP3-Download/11908697.html">
            <artist id="11654614" name="Caribou" url="http://www.emusic.com/artist/Caribou-MP3-Download/11654614.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.06"/>
            </ratings>
        </album>
        <album added="2010-04-06" id="11837473" image="http://images.emusic-test.com/music/images/album/0/118/374/11837473/300x300.jpg" name="Big Echo" released="2010-03-09" url="http://www.emusic.com/album/The-Morning-Benders-Big-Echo-MP3-Download/11837473.html">
            <artist id="11687059" name="The Morning Benders" url="http://www.emusic.com/artist/The-Morning-Benders-MP3-Download/11687059.html"/>
            <label id="191087" name="Rough Trade / Beggars Group" url="http://www.emusic.com/label/MP3-Download/191087.html"/>
            <genre id="284" name="Alternative/Punk" url="http://www.emusic.com/genre/284.html"/>
            <ratings>
                <communityRating average="4.02"/>
            </ratings>
        </album>
        <album added="2010-04-14" id="11902413" image="http://images.emusic-test.com/music/images/album/0/119/024/11902413/300x300.jpg" name="Led Zeppelin IV" released="1971-11-08" url="http://www.emusic.com/album/Led-Zeppelin-Led-Zeppelin-IV-MP3-Download/11902413.html">
            <artist id="11759074" name="Led Zeppelin" url="http://www.emusic.com/artist/Led-Zeppelin-MP3-Download/11759074.html"/>
            <label id="363545" name="Atlantic Records" url="http://www.emusic.com/label/MP3-Download/363545.html"/>
            <genre id="277" name="Rock/Pop" url="http://www.emusic.com/genre/277.html"/>
            <ratings>
                <communityRating average="4.66"/>
            </ratings>
        </album>
        <album added="2010-03-09" id="11821128" image="http://images.emusic-test.com/music/images/album/0/118/211/11821128/300x300.jpg" name="The Monitor" released="2010-03-09" url="http://www.emusic.com/album/Titus-Andronicus-The-Monitor-MP3-Download/11821128.html">
            <artist id="11984298" name="Titus Andronicus" url="http://www.emusic.com/artist/Titus-Andronicus-MP3-Download/11984298.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.14"/>
            </ratings>
        </album>
    </albums>
</response>

version 2 as of 3 months ago by Ben Kotch

0 Comments

Please sign in to post a comment.