Method: Album Search

Conducts an album search using a search term (or artist ID, label ID, etc.) and provides paginated results.

Request URL

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

http://api.emusic.com/album/search?apiKey=myKey&term=search+term

Request Parameters

Following is a list of required and optional query string parameters for the Album Search 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.
term depends none A URL-encoded search term with which to search albums. One of term, albumId, artistId, genreId, labelId or styleId must be provided.
albumId
artistId
genreId
labelId
styleId		 depends none A related search ID. One of term, albumId, artistId, genreId, labelId or styleId must be provided.
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.)
imageSize no medium The size of the album images referred to by image URLs (thumbnail, small, medium, large, huge).
fref no none The eMusic partner tag. If provided, the FREF value is automatically added to all appropriate eMusic links.

Example Requests

// Returns the first 20 albums that contain the string "love songs".
http://api.emusic.com/album/search?apiKey=myKey&term=love+songs

// Returns the third page of 10 albums.
http://api.emusic.com/album/search?apiKey=myKey&term=love+songs&page=3&perPage=10

// Returns the first 20 albums with artist ID 11002212.
http://api.emusic.com/album/search?apiKey=myKey&artistId=11002212

// Returns the first 20 albums in JSON using large images.
http://api.emusic.com/album/search?apiKey=myKey&term=love+songs&
format=JSON&imageSize=large

// Returns the third page of 10 albums in JSONP using a callback of
// someMethod() and an FREF value of 400060.
http://api.emusic.com/album/search?apiKey=myKey&term=love+songs&page=3&perPage=10&
format=JSONP&callback=someMethod&fref=400060

Response Format

Following is a list of returned elements for the Album Search 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.
search search on ok Contains the search term.
view view on ok Contains the paginate result counts.
albums list on ok Contains a paged list of albums that meet the search criteria. See the example response below for typical album elements.

Example Response

<?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"/>
    <search term="love songs"/>
    <view page="1" pages="308" perPage="3" total="922"/>
    <albums list="true" size="3">
        <album added="2009-06-30" id="11497459" image="http://images.emusic.com/music/images/album/0/114/974/11497459/300x300.jpg" name="Love Songs" released="2000-01-18" url="http://www.emusic.com/album/Louis-Armstrong-Love-Songs-MP3-Download/11497459.html">
            <artist id="10560091" name="Louis Armstrong" url="http://www.emusic.com/artist/Louis-Armstrong-MP3-Download/10560091.html"/>
            <label id="266966" name="Columbia/Legacy" url="http://www.emusic.com/label/MP3-Download/266966.html"/>
            <genre id="291" name="Jazz" url="http://www.emusic.com/genre/291.html"/>
        </album>
        <album added="2007-10-17" id="11103807" image="http://images.emusic.com/music/images/album/0/111/038/11103807/300x300.jpg" name="Love Songs" released="2007-01-01" url="http://www.emusic.com/album/Love-Potion-Love-Songs-MP3-Download/11103807.html">
            <artist id="11875738" name="Love Potion" url="http://www.emusic.com/artist/Love-Potion-MP3-Download/11875738.html"/>
            <label id="160692" name="Download Party Music / The Orchard" url="http://www.emusic.com/label/MP3-Download/160692.html"/>
            <genre id="277" name="Rock/Pop" url="http://www.emusic.com/genre/277.html"/>
            <ratings>
                <communityRating average="3"/>
            </ratings>
        </album>
        <album added="2009-06-30" id="11497454" image="http://images.emusic.com/music/images/album/0/114/974/11497454/300x300.jpg" name="Love Songs" released="2003-01-14" url="http://www.emusic.com/album/Paul-Young-Love-Songs-MP3-Download/11497454.html">
            <artist id="11711323" name="Paul Young" url="http://www.emusic.com/artist/Paul-Young-MP3-Download/11711323.html"/>
            <label id="266966" name="Columbia/Legacy" url="http://www.emusic.com/label/MP3-Download/266966.html"/>
            <genre id="277" name="Rock/Pop" url="http://www.emusic.com/genre/277.html"/>
            <ratings>
                <communityRating average="5"/>
            </ratings>
        </album>
    </albums>
</response>

version 12 as of 3 months ago by Ben Kotch

0 Comments

Please sign in to post a comment.