Chapter 11. XML Response Block documentation

Album XML Block

XML Representation Summary

<Album>
    Content:
        Release*
</Album>

May be included in elements:

Track, Video

Artist XML Block

XML Representation Summary

	<Artist
        catzillaID = xs:int
        flags = xs:int
        hotzillaID = xs:int
        id = xs:string
        name = xs:string
        rating = xs:int
        salesGenreCode = xs:int
        sortName = xs:string
        trackCount = xs:int
        website = xs:string
        >

    Content: 
        Image*, Category*, Releases?, TopTracks?, TopSimilarArtists?, RadioStations?, Fans?, ItemInfo?, Video*
</Artist>

Attributes

Field	Value	Required	Description	Blocks each attribute is available from
catzillaID	xs:int	no	Yahoo! Catzilla ID (for Yahoo! Shopping)	Artist
flags	xs:int	no	Bitmask of artist flags. Can be a combination of the possible values: 1: biography 2: discography 4: downloads 8: fans 16: fan 32: fan 64: interviews 128: lyrics 256: message 512: news 1024: photos 2048: radio 4096: reviews 8192: similar 16384: videos 32768: images 65536: explicit TIP: To test for a flag in XPath, you can do [floor(@flags div FLAGVALUE) mod 2 = 1]. FLAGVALUE is the value of the flag you're looking for. Example: * /Artist[floor(@flags div 64) mod 2 = 1] gets all artists with interviews.	Artist
id	xs:string	no		All
rating	xs:int	no		All
hotzillaID	xs:int	no	Yahoo! Hotzilla ID	Artist
name	xs:string	no		All
salesGenreCode	xs:int	no		Artist
sortName	xs:string	no		Artist, Video, Release
trackCount	xs:int	no		Artist
website	xs:string	no		Artist, Video

May be included in elements (10):

Artists, Category, NewsArticle, Playlist, Release, SampleArtists, Station, TopSimilarArtists, Track, Video

BrandCode XML Block

XML Representation Summary

<BrandCode
    name = xs:string
/>

Attributes

Field	Value	Required	Description	Blocks each attribute is available from
name	xs:string	no

May be included in elements:

BrandCodes

BrandCodes XML Block

XML Representation Summary

<BrandCodes>
    Content:
        BrandCode?
</BrandCodes>

May be included in elements:

PremiumInfo

Bumper XML Block

XML Representation Summary

<Bumper
        spaceID = xs:int
/>

Attributes

Field	Value	Required	Description	Blocks each attribute is available from
spaceID	xs:int	no		Video

Category XML Block

XML Representation Summary

<Category
        artistCount = xs:int
        hasAudioStation = xs:boolean
        hasRadioStation = xs:boolean
        hasVideoStation = xs:boolean
        id = xs:string
        name = xs:string
        rating = xs:int
        releaseCount = xs:int
        trackCount = xs:int
        type = ("Genre"|"Theme"|"Era")
        videoCount = xs:int
        >

    Content: 
        ShortDescription?, LongDescription?, Artist*, Station*, Category*
</Category>

Attributes

Field	Value	Required	Description	Blocks each attribute is available from
artistCount	xs:int	no
hasAudioStation	xs:boolean	no
hasRadioStation	xs:boolean	no
hasVideoStation	xs:boolean	no
id	xs:string	no		All
rating	xs:int	no		All
name	xs:string	no		All
releaseCount	xs:int	no
trackCount	xs:int	no
type	xs:string	no	Restricted to one of: "Genre" "Theme" "Era"	All
videoCount	xs:int	no

May be included in elements (8):

Artist, Categories, Category, CategoryType, Mood, Release, Track, Video

CountryCode XML Block

XML Representation Summary

<CountryCode
        code = xs:string
/>

Attributes

Field	Value	Required	Description	Blocks each attribute is available from
code	xs:string	no

Error XML Block

XML Representation Error

<Error
	code 	= xs:string
	description 	= xs:string
	id 	= xs:string
      />

Fan XML Block

XML Representation Summary

<Fan
        yid = xs:string
        ymid = xs:int
/>

Attributes

Field	Value	Required	Description	Blocks each attribute is available from
yid	xs:string	no
ymid	xs:long	no

Fans XML Block

XML Representation Summary

<Fans>
    Content:
        Fan+
</Fans>

May be included in elements (1):

Artist

LongDescription XML Block

XML Representation Summary

<LongDescription>
    Content:
        { xs:string }
</LongDescription>

May be included in elements:

Category, Station

Mapping XML Block

XML Representation Summary

<Mapping>
        catalogID = xs:int
        catalogName = xs:string
        id = xs:int
        rights = xs:int
</Mapping>

Attributes

Field	Value	Required
catalogID	xs:int	no
catalogName	xs:string	no
id	xs:int	no
rights	xs:int	no

May be included in elements:

Mappings

Mappings XML Block

XML Representation Summary

<Mappings>
    Content:
        Mapping*
</Mappings>

May be included in elements:

Track

Media XML Block

XML Representation Summary

<Media
        aspectRatio = xs:float
        bitRate = xs:int
        codec = xs:string
        displayBitRate = xs:int
        duration = xs:int
        format = xs:string
        height = xs:int
        id = xs:int
        rights = xs:int
        streamID = xs:int
        typeID = xs:int
        width = xs:int
/>

Attributes

Field	Value	Required	Description	Blocks each attribute is available from
id	xs:string	no		Video
aspectRatio	xs:float	no	Frame aspect ratio, as a float (video only). Ex: 1.33	Video
bitRate	xs:int	no		Video
codec	xs:string	no		Video
displayBitRate	xs:int	no		Video
duration	xs:int	no		Video
format	xs:string	no		Video
height	xs:int	no		Video
rights	xs:int	no		Video
streamID	xs:int	no		Video
typeID	xs:int	no		Video
width	xs:int	no	Frame width, in pixels (video only)	Video

Mood XML Block

XML Representation Summary

<Mood
        description = xs:string
        discovery = xs:int
        id = xs:int
        name = xs:string

    Content: 
        Category*
</Mood>

Attributes

Field	Value	Required
description	xs:string	no
discovery	xs:int	no
id	xs:string	no
name	xs:string	no

May be included in elements:

Moods

Moods XML Block

XML Representation Summary

<Moods
        count = xs:int
        defaultSort = xs:string
        description = xs:string
        errorCount = xs:int
        id = xs:string
        name = xs:string
        start = xs:int
        total = xs:int
        url = xs:string
        >

    Content: 
        Mood*
</Moods>

Attributes

Field	Value	Required
count	xs:int	no
defaultSort	xs:string	no
description	xs:string	no
errorCount	xs:int	no
id	xs:string	no
name	xs:string	no
start	xs:int	no
total	xs:int	no
url	xs:string	no

May be included in elements:

Station

Order XML Block

XML Representation Summary

<Order
    id = xs:string
    name = xs:string
/>

Attributes

Field	Value	Required	Description	Blocks each attribute is available from
id	xs:string	no		All
name	xs:string	no		All

May be included in elements:

Sort

Package XML Block

XML Representation Summary

<Package>
    name = xs:string
/>

Attributes

Field	Value	Required	Description	Blocks each attribute is available from
name	xs:string	no

May be included in elements:

User

Packages XML Block

XML Representation Summary

<Packages>
    Content:
        Package?
</Packages>

May be included in elements:

PremiumInfo

PaymentLabel XML Block

XML Representation Summary

<PaymentLabel
        name = xs:string
        id = xs:int
/>

Attributes

Field	Value	Required	Description	Blocks each attribute is available from
name	xs:string	no		Video
id	xs:string	no		Video

PlaylistCounts XML Block

XML Representation Summary

<PlaylistCounts
        private = xs:int
        public = xs:int
/>

Attributes

Field	Value	Required	Description	Blocks each attribute is available from
private	xs:int	no
public	xs:int	no

PremiumInfo XML Block

XML Representation Summary

<PremiumInfo>
    Content:
        Packages?, BrandCodes?
</PremiumInfo>

May be included in elements:

User

Profile XML Block

XML Representation Summary

<Profile
        description = xs:string
        discovery = xs:int
        isCreated = xs:boolean
        popularity = xs:int
        privacy = xs:int
/>

Attributes

Field	Value	Required	Description
description	xs:string	no	User's profile description.
discovery	xs:int	no	User's profile discovery setting in range from 0 to 100. This is the percentage of unrated music the user will hear. For instance, 20 means 20% unrated music.
isCreated	xs:boolean	no	True if user is a music member. False if user is a guest or trial member.
popularity	xs:boolean	no
privacy	xs:int	no	0 for public, 2 for private.

RadioStations XML Block

XML Representation Summary

<RadioStations>
    Content:
        Station*
</RadioStations>

May be included in elements:

Artist

RatingCounts XML Block

XML Representation Summary

<RatingCounts
        artistCount = xs:int
        categoryCount = xs:int
        releaseCount = xs:int
        trackCount = xs:int
/>

Attributes

Field	Value	Required
artistCount	xs:int	no
categoryCount	xs:int	no
releaseCount	xs:int	no
trackCount	xs:int	no

Rating XML Block

XML Representation Summary

<Rating
        id = xs:int
        value = xs:int
/>

Attributes

Field	Value	Required	Description	Blocks each attribute is available from
id	xs:int	no	Source (i.e. client) from which rating was added. Required when adding ratings.
value	xs:int	no	Rating value. Any value from 0 to 100, or -1 (unrated).

Ratings XML Block

XML Representation Summary

<Ratings
        sourceID = xs:int
        type = ("artist" | "release" | "track" | "video" | "category" | "playlist")
        />
    Content:
        Rating*
</Ratings>

Attributes

Field	Value	Required	Description	Blocks each attribute is available from
sourceID	xs:int	no	Source (i.e. client) from which rating was added. Required when adding ratings.
type	xs:string	no	One of: artist release track video category playlist

Release XML Block

XML Representation Summary

<Release
        UPC = xs:string
        catzillaID = xs:int
        explicit = xs:boolean
        flags = xs:int
        id = xs:string
        label = xs:string
        rating = xs:int
        releaseDate = xs:dateTime
        releaseYear = xs:int
        rights = xs:int
        title = xs:string
        typeID = xs:int
        >

    Content: 
        Image*, Price*, Track*, Artist*, Category*, Fan*, Review*, ItemInfo?
</Release>

Attributes

Field	Value	Required	Description	Blocks each attribute is available from
UPC	xs:string	no		Release
catzillaID	xs:int	no	Yahoo! Catzilla ID (for Yahoo! Shopping)
explicit	xs:boolean	no	Whether or not the release contains explicit lyrics	Release
flags	xs:int	no	Bitmask of release flags. Can be a combination of the possible values: 1: This release contains explicit lyrics 2: This release contains an image (i.e. album art) 128: lyrics exist for this release TIP: To test for a right in XPath, you can do [floor(@rights div RIGHTVALUE) mod 2 = 1]. RIGHTVALUE is the value of the right you're looking for. Example: * /Release[floor(@rights div 128) mod 2 = 1] gets all releases with lyrics.
id	xs:string	no		All
rating	xs:int	no		All
label	xs:int	no		Release
releaseDate	xs:dateTime	no		Release
releaseYear	xs:int	no		Artist
rights	xs:string	no	Bitmask of release rights. Can be a combination of the possible values: 1: freePreprogrammed 2: freeCustomized 4: subscriptionPreprogrammed 8: subscriptionCustomized 16: tetheredTrackDownload 32: permanentTrackDownload 64: permanentAlbumDownload 128: freeOnDemand 256: subscriptionOnDemand 512: burnToCD 1024: transferToDevice 2048: sample	Artist, Release
title	xs:string	no		All
typeID	xs:int	no	1: Unknown 2: Album 3: EP 4: Single 6: Box 7: Promotional 8: Promotional 10: Compilation 11: Mix	Artist

May be included in elements (3):

Album, ReleaseReviews, Releases

Releases XML Block

XML Representation Summary

<ReleaseReviews>
   	Content: 
		Release+
</ReleaseReviews>

May be included in elements:

Release

Review XML Block

XML Representation Summary

<Review>
    Content:
        { xs:string }
</Review>

May be included in elements:

Release

ShortDescription XML Block

XML Representation Summary

<ShortDescription>
    Content:
        { xs:string }
</ShortDescription>

May be included in elements:

Category, Station

Sort XML Block

XML Representation Summary

<Sort
    name = xs:string >

    Content:
        Order*
</Sort>

Attributes

Field	Value	Required	Description	Blocks each attribute is available from
name	xs:string	no		All

May be included in elements:

Sorts

Sorts XML Block

XML Representation Summary

<Sorts>
    Content:
        Sort*
</Sorts>

May be included in elements:

SpellResult XML Block

XML Representation Summary

<SpellResult
        suggestion = xs:string
        token = xs:string />

Attributes

Field	Value	Required	Description	Blocks each attribute is available from
suggestion	xs:string	no		All
token	xs:string	no	Spelling token is passed to client when ever there are spelling suggestions. There could be multiple suggestions. When client search for keyword and get back SpellResult. Out of these results client request one of them back. Client needs to pass the “token” as “spelltoken” when firing query with spelling suggestions.	All

May be included in elements:

SpellResults

SpellResults XML Block

XML Representation Summary

<SpellResults
    count = xs:int
    start = xs:int
    total = xs:int >

    Content:
        SpellResult*
</SpellResults>

Attributes

Field	Value	Required	Blocks each attribute is available from
count	xs:int	no	All
start	xs:int	no	All
total	xs:int	no	All

May be included in elements:

Artists, Releases, Tracks, Videos

Station XML Block

XML Representation Summary

<Station
        id = xs:int
        itemType = ("radio"|"video")
        name = xs:string
        stationType = ("category" | "artist" | "user")
        >

    Content: 
        ShortDescription?, LongDescription?, Image*, Artist*, Moods?
</Station>

Attributes

Field	Value	Required	Description	Blocks each attribute is available from
id	xs:string	no		All
itemType	xs:string	no		All
name	xs:string	no	One of: "radio" "video"	All
stationType	xs:string	no	One of: "category" "artist" "user"	All

May be included in elements:

Category, RadioStations, Stations

TopSimilarArtists XML Block

XML Representation Summary

<TopSimilarArtists>
    Content:
        Artist+
</TopSimilarArtists>

May be included in elements:

Artist

TopTracks XML Block

XML Representation Summary

<TopTracks>
    Content:
        Track+
</TopTracks>

May be included in elements:

Artist

Track XML Block

XML Representation Summary

<Track
        discNumber = xs:int
        duration = xs:int
        explicit = xs:boolean
        flags = xs:int
        id = xs:string
        label = xs:string
        popularity = xs:int
        rating = xs:int
        releaseYear = xs:int
        rights = xs:int
        title = xs:string
        trackNumber = xs:int
        >

     Content: 
         Image*, Price*, Track*, Artist*, Category*, Fan*, Review*, ItemInfo?
</Track>

Attributes

Field	Value	Required	Description	Blocks each attribute is available from
discNumber	xs:int	no		Artist, Release, Track
duration	xs:int	no		Artist, Release, Track
explicit	xs:boolean	no	Whether or not the track contains explicit lyrics	Release, Track
flags	xs:int	no	Bitmask of track flags. Can be a combination of the possible values: 1: This track contains explicit lyrics 128: lyrics exist for this track TIP: To test for a flag in XPath, you can do [floor(@flags div FLAGVALUE) mod 2 = 1]. FLAGVALUE is the value of the flag you're looking for. Example: * /Track[floor(@flags div 128) mod 2 = 1] gets all tracks with lyrics.
id	xs:string	no		All
rating	xs:string	no
label	xs:int	no	Yahoo! Hotzilla ID
popularity	xs:string	no		Release
releaseYear	xs:int	no
rights	xs:string	no	Bitmask of track rights. Can be a combination of the possible values: 1: freePreprogrammed 2: freeCustomized 4: subscriptionPreprogrammed 8: subscriptionCustomized 16: tetheredTrackDownload 32: permanentTrackDownload 64: permanentAlbumDownload 128: freeOnDemand 256: subscriptionOnDemand 512: burnToCD 1024: transferToDevice 2048: sample	Artist, Release
title	xs:string	no		All
trackNumber	xs:int	no		Artist, Release

May be included in elements (1):

Artist

User XML Block

XML Representation Summary

<User
        countryCode = xs:string
        explicitLyrics = xs:boolean
        isMember = xs:boolean
        parentalLock = xs:boolean
        ratingWidget = xs:boolean
        yid = xs:string
        ymid = xs:long
        ymtTimestamp = xs:long
        >

    Content: 
        Profile?, RatingCounts?, PlaylistCounts?, PremiumInfo?, CountryCode?
</User>

Attributes

Field	Value	Required	Description
countryCode	xs:string	no	ISO alpha country code (base on reverse IP lookup), or "US" if the country could not be determined.
explicitLyrics	xs:string	no	Whether or not to filter out explicit lyrics for this user. True to enable filtering, false to disable filtering.
isMember	xs:boolean	no	True if user is a music member. False if user is a guest or trial member.
parentalLock	xs:boolean	no
ratingWidget	xs:boolean	no	User's rating widget setting. True for advanced, false for basic.
yid	xs:string	no	Yahoo Id.
ymid	xs:long	no
ymtTimestamp	xs:long	no	Unix timestamp of the time that the user's YMT cookie was created

Video XML Block

XML Representation Summary

<Video
        copyrightYear = xs:int
        duration = xs:int
        explicit = xs:boolean
        flags = xs:int
        id = xs:string
        label = xs:string
        localOnly = xs:boolean
        rating = xs:int
        rights = xs:int
        salesGenre = xs:int
        title = xs:string
        typeID = xs:int
        >

    Content: 
        Image*, Artist*, Client*, Category*, Album*, Media*, Bumper?, PaymentLabel?, FlaggedWith*, ItemInfo?, xspf:track?, RecentlyPlayed?
</Video>

Attributes

Field	Value	Required	Description
copyrightYear	xs:int	no
duration	xs:int	no	Duration of the video, in seconds.
explicit	xs:boolean	no	Whether or not the release contains explicit lyrics
flags	xs:int	no	Bitmask of video flags. Can be a combination of the possible values: 1: images (whether we have images in general) To test for a flag in XPath, you can do [floor(@flags div FLAGVALUE) mod 2 = 1]. FLAGVALUE is the value of the flag you're looking for. Example: * /Video[floor(@flags div 1) mod 2 = 1] gets all videos with images.
id	xs:string	no
rating	xs:int	no
label	xs:string	no	Record label name
localOnly	xs:boolean	no	Whether or not the video is restricted to local users
rights	xs:string	no	Bitmask of video rights. Can be a combination of the possible values: 1: embedded (avail for embedded, off-network playback) TIP: To test for a right in XPath, you can do [floor(@rights div RIGHTVALUE) mod 2 = 1]. RIGHTVALUE is the value of the right you're looking for. Example: * /Video[floor(@rights div 1) mod 2 = 1] gets all videos playable in an embedded, off-network player.
salesGenre	xs:int	no
title	xs:string	no
typeID	xs:string	no	Type of video. One of the following: 1: Music Video 2: Live Performance 3: Interview 4: PSA 5: EPK 6: Clip 7: Interstitial 8: Trailer 9: Promo/Ad 12: Unknown 13: Blue Today Host Segment 14: Blue Today Daily News 16: Composite Feature 18: Bumper/Graphic 19: Episode

May be included in elements:

Artist, Playlist, Track, Videos

Yahoo! Music API Guide