Search

SearchTracks returns tracks found using a combination of search terms:

 

POST /cloudsearch/{serviceToken}

Parameter Type Status
ServiceToken String Mandatory
Request Body XML Mandatory

 

Initial Search

Request body

<requestcloudsearch>
     <searchfilters>
          <searchtype>normal</searchtype>                                                                                                
          <memberaccount>3a6000000000498b</memberaccount>
          <region>3a62f6000000098b</region>
          <includeinactive>false</includeinactive>                                                                      
          <mainonly>true</mainonly>
          <playlist>true</playlist>
          <searchtermbundle>
                <st_keyword_aggregated exactphrase="false" oroperation="false" wildcard="true">pop</st_keyword_aggregated>
                <st_keyword fields="AlbumCode,AlbumDisplayTitle,CategoryAttributeName,TrackComment,TrackComposer,TrackKeywords,TrackDisplayTitle,TrackGenre,TrackAuthor,LibraryName,TrackArtist" exactphrase="false" oroperation="false" wildcard="true">pop</st_keyword>
                <st_duration start="30" end="160" />
                <st_bpm start="100" end="600" />
                <st_releasedate start="2000-01-01" end="2014-10-31" />                                                               <st_library>cc150000000b1,7c50000000017</st_library>                                                               <st_album>068d000000a71f,b00000000002aef</st_album>
                <st_category>068d000000000a71f,b0000000042aef</st_category>
                <st_style oroperation="true">bd679000000392e,b4b0900000000009,5400000000ee472</st_style>                                  <st_membercomment exactphrase="true" oroperation="false">pop</st_membercomment>                                                
                 <st_membertag oroperation="false">p068d6500000a71f,b00fed000000aefp</st_membertag>
          </searchtermbundle>
          <resultview>
                <view>track</view>
                <sort_predefined>DateTimeStamp_Desc</sort_predefined>
                <skip>0</skip>
                <limit>2</limit>
                <randomsortkey>2</randomsortkey>
                <library>cc15df00000001</library>
                <album>06800000000a71f</album>
                <returntrackcategoryid>true</returntrackcategoryid>
          </resultview>
     </searchfilters>
     <savesearchhistory>true</savesearchhistory>
</requestcloudsearch>

 

 

General  

All “true” / “false” value needs to be lower case. 


Search Filters

These parameters will be shared between “first search” and “search within results”.

POST request elements
searchtype

Required, case insensitive, value choose from

1. “Normal”: normal search

2. “MemberFavouriteTracks”: search contents within member favourite tracks

3. “PlaylistTracks” : search contents within playlist tracks (work for both featured / member playlists)

memberaccount

 

Optional, encrypted memberaccountid, but this one is required when searchtype is “MemberFavouriteTracks”, for saving the search history this value need to be present
region Optional, pass encrypted region id to it will filter the search results by region

includeinactive Optional, choose from “true” / “false”, case sensitive, default value is “false”, pass “true” to include inactive contents in the results.

mainonly Optional, choose from “true” / “false”, case sensitive, default value is “false”, pass “true” to search on main tracks only.

playlist Optional, encrypted playlist id, search within a playlist, but this is required when “searchtype” is “PlaylistTracks”

 

Search Term Bundle

Contains a list of different search terms, each type of search term can only appear once within the bundle, and you can have any combination of the search terms within the bundle.

POST request elements
st_keyword_aggregated

Uses the fields selected as default for search. See Global Settings.

“exactphrase” is optional, default value is “false”
“oroperation” is optional, default value is "false"
“wildcard” is optional, default value is "false"

Place a "%" into the st_keyword_aggregated to return all tracks.

Note: You can use either st_keyword_aggregated or st_keyword, but not both.

st_keyword

You can specify any combination of text fields you want to search from. Below is a list of text field for “fields” attribute, this is case sensitive.

TrackDisplayTitle
TrackComment
TrackGenre
TrackComposer
TrackPublisher
TrackKeywords
TrackLyrics
TrackVersion
AlbumCode
AlbumDisplayTitle
AlbumKeywords
LibraryName
CategoryAttributeName
TrackArtist
AlbumDescription
StyleName
TrackAlternateTitle

“exactphrase” is optional, default value is “false”
“oroperation” is optional, default value is "false"
“wildcard” is optional, default value is "false"

Note: You can use either st_keyword_aggregated or st_keyword, but not both.

st_duration Search on track duration field, both “start” or “end” is optional

st_bpm Search on track bpm field, both “start” or “end” is optional

st_releasedate Search on album release date field, both “start” or “end” is optional. Date format need to be “yyyy-MM-dd”

st_library Library filter, comma separated encrypted library id value, or operation

st_album Album filter, comma separated encrypted album id value, or operation

st_category Category filter, comma separated encrypted category id value, or categoryattributeid

Prefix categoryid with "CAT_" ie: CAT_068d650000009a71f
Prefix the category attributeid with "ATT_" ie: ATT_068d6500000001f

st_style Style filter, comma separated encrypted style id value, “oroperation” is optional, default value is "false"

st_membercomment Search on member comments, right now member can only comments on tracks, , “exactphrase” is optional, default value is “false”, “oroperation” is optional, default value is "false"

st_membertag Search on member tags, currently member can only tag on tracks, “oroperation” is optional, default value is "false"

st_rightholder A comma separated string of encrypted right holder IDs

 

 

 

Result view

This is the list of parameters that control how the results are displayed.

POST request elements
view

Required, value choose from { “track”, “album”, “library” }, case insensitive

sort_predefined

 

Optional, value choose from the below, case insensitive

If left empty will be the order records are stored on cloud.


Track

  • ReleaseDate_Asc
  • ReleaseDate_Desc
  • Alphabetic_Asc
  • Alphabetic_Desc
  • MemberLibraryOrder (then ordered by ReleaseDate_Desc)
  • DateTimeStamp_Asc (only for member favourite or playlist track search)
  • DateTimeStamp_Desc (only for member favourite or playlist track search)
  • Random
  • Custom (member order only for playlist track search)
  • RankExpression (contact us to setup customised ranking including up/down boosting on track manager in admin)


Album 

  • ReleaseDate_Asc
  • ReleaseDate_Desc
  • Alphabetic_Asc
  • Alphabetic_Desc
  • MemberLibraryOrder (then ordered by ReleaseDate_Desc)
  • Random
  • Count_Desc (track count)
  • RankExpression (contact us to setup customised ranking)

Label

  • ReleaseDate_Asc
  • ReleaseDate_Desc
  • Alphabetic_Asc
  • Alphabetic_Desc
  • MemberLibraryOrder
  • Random
  • LibraryLatestAlbum
  • Count_Desc  (album count)

rankexpression

If <sort_predefined>RankExpression</sort_predefined> is provided when <view>Track</view> then an <rankexpression> element is also required. 

skip Optional, skip a number of result

limit Required, a number of results to return

randomsortkey Optional, this key is for maintain result order for random sort paging, only use it when “sort_predefined” is “Random”.

library Optional, encrypted library id, this is different to “st_library” search term, this one can only take one value, and should only be used you expand a library to view the albums in it for a search result.

album Optional, encrypted album id, this is different to “st_album” search term, this one can only take one value, and should only be used you expand an album to view the tracks in it for a search result.

returntrackcategoryid

Pass “true” to this parameter to return track categories in the results.

Please use the GetCategory method to load the category tree in the memory of the calling application, then locate the category names in this tree before rendering your search results.

facet_composer

Pass “true” to this parameter to return composer facet in the results.

To control pagination and order you will need the additional parameters:

  • facet_composerskip
  • facet_composerlimit
  • facet_composersort

Sort options are as follows:

  • Count_Desc
  • Alphabetic_Asc
 
facet_album

Pass “true” to this parameter to return album facet in the results.

To control pagination and order you will need the additional parameters:

  • facet_albumskip
  • facet_albumlimit
  • facet_albumsort

Sort options are as follows:

  • Count_Desc
  • Alphabetic_Asc
  • ReleaseDate_Desc
 
 
facet_library

Pass “true” to this parameter to return label facet in the results.

To control pagination and order you will need the additional parameters:

  • facet_libraryskip
  • facet_librarylimit
  • facet_librarysort

Sort options are as follows:

  • Count_Desc
  • Alphabetic_Asc
  • MemberFavourite
 
facet_style

Pass “true” to this parameter to return album style facet in the results.

To control pagination and order you will need the additional parameters:

  • facet_styleskip
  • facet_stylelimit
  • facet_stylesort

Sort options are as follows:

  • Count_Desc
  • Alphabetic_Asc
facet_category
 

Pass “true” to this parameter to return category facet in the results. 

Set facet_categorycategoryids as "true" to also return categoryIDs

To control pagination and order you will need the additional parameters:

  • facet_categoryskip
  • facet_categorylimit
  • facet_categorysort

Sort options are as follows:

  • Count_Desc
  • Alphabetic_Asc

 

Save Search History

Store history to view reports in the admin.

POST request elements
savesearchhistory

 Optional, provide “true” to save search to history, default is “false”.

 

Successful Response:

<responsecloudsearch totaltracks="11" totalalbums="1" totallibraries="1">
     <searchfilters>
          <searchtype>normal</searchtype>
          <region>3a62f6be7414498b</region>
          <mainonly>true</mainonly>
          <parentsearchhistoryid>5tu2f6be7414498b<parentsearchhistoryid>
          <resultview>
               <view>track</view>
               <sort_predefined>Date_Desc</sort_predefined>
               <limit>2</limit>
               <randomsortkey>2</randomsortkey>
               <library>cc15df604221dcb1</library>
               <album>068d655e5079a71f</album>
          </resultview>
          <searchtermbundlehistory>
               <searchtermbundle searchhistoryid="0">
                    <st_duration searchtermid="1024" start="60" end="120"/>
               </searchtermbundle>
               <searchtermbundle searchhistoryid="1">
                    <st_library searchtermid="131072">cc15df604221dcb1,7c5edf91e7602217</st_library>
               </searchtermbundle>
               <searchtermbundle searchhistoryid="2">
                    <st_removesearchterms>
                    <st_removesearchterm searchhistoryid="0" searchtermid="1024"/>
                    <st_removesearchterm searchhistoryid="1" searchtermid="131072"/>
                    </st_removesearchterms>
               </searchtermbundle>
               <searchtermbundle searchhistoryid="3">
                    <st_keyword_aggregated searchtermid="1">pop</st_keyword_aggregated>
                    <st_removesearchterms/>
               </searchtermbundle>
          </searchtermbundlehistory>
     </searchfilters>
     <tracks>
          <track tracknumber="001" lengthseconds="64" comment="A hooky, arpeggiated synth line and sweeping fx kick off               this super fun, electro pop ditty. Emotive auto tuned vocals and a synth lead play in unison and lock you in as the               driving beat and thick bass pound out the rhythm. POI @ :30 Punchy, melodic break with tambourine, vocal oohs               and energized rhythm.   Piano, synth pad and guitar drive the piece home and leave you with a smile."                            composer="Adam Gubman (ASCAP)" publisher="" name="Contemplating Love" albumid="068d655e5079a71f"                    libraryid="cc15df604221dcb1" id="c45f3f611237a600" keywords="Electronic, TV, Commercial, Electro-Pop, Pop,                   Alternative, Rock, Driving, Male Vocal, Melodic, Uptempo, Inspirational, Program"                    
           lyrics="" displaytitle="Contemplating Love" genre="Electronic" tempo=""                                                                          instrumentation="Synth, Electronic Beat, Electric Guitar, Drums, Percussion, Male Vocals" bpm="127" mixout=""                  frequency="48000" bitrate="0" dateingested="2012-10-31 18:59:09" version="MAIN" alternatecount="3"/>
      </tracks>
</responsecloudsearch>

 

<searchfilters> contains all the search parameters you passed in to generate this result. In this example there are four <searchtermbundle> elements inside <searchtermbundlehistory> element, which means this search has been refined four times.

The response also contains a search result object, in this example it is <tracks> object, that’s because the “view” value in <searchview> element is “track”, if you pass in “album” or “library”, they will be <albums> or <libraries>. 

“totaltracks”, “totalalbums” and “totallibraries” in the root element is corresponding count for the search results.

If the search view is “track”, all three values will be returned, but only “totalalbums” and “totallibraries” will be returned for “album” and “library” view.

 

Track view

Album view

Library view

totaltracks

Yes

No

No

totalalbums

Yes

Yes

Yes

totallibraries

Yes

Yes

Yes

 

Search Within Results

Request body

<requestcloudsearch>
     <searchfilters>
               <searchtype>normal</searchtype>
               <memberaccount>3a62f6be7414498b</memberaccount>
               <region>3a62f6be7414498b</region>
               <includeinactive>false</includeinactive>
               <mainonly>true</mainonly>
               <playlist >true</playlist>
               <parentsearchhistoryid>5tu2f6be7414498b</parentsearchhistoryid>
               <searchtermbundlehistory>
                    <searchtermbundle searchhistoryid="0">
                         <st_duration searchtermid="1024" start="60" end="120"/>
                    </searchtermbundle>
                    <searchtermbundle searchhistoryid="1">
                         <st_library searchtermid="131072">cc15df604221dcb1,7c5edf91e7602217</st_library>
                    </searchtermbundle>
                    <searchtermbundle searchhistoryid="2">
                         <st_removesearchterms>
                              <st_removesearchterm searchhistoryid="0" searchtermid="1024"/>
                              <st_removesearchterm searchhistoryid="1" searchtermid="131072"/>
                         </st_removesearchterms>
                    </searchtermbundle>
                    <searchtermbundle searchhistoryid="3">
                         <st_keyword_aggregated searchtermid="1">pop</st_keyword_aggregated>
                    </searchtermbundle>
               </searchtermbundlehistory>
               <searchtermbundle>
                    <st_keyword_aggregated exactphrase="false" oroperation="false">pop</st_keyword_aggregated>
                    <st_keyword fields=”TrackKeywords,TrackLyrics” exactphrase="false" oroperation="false">pop</st_keyword>
                    <st_duration start="30" end="160" />
                    <st_bpm start="100" end="600" />
                    <st_releasedate start="2000-01-01" end="2014-10-31" />
                    <st_library>cc15df604221dcb1,7c5edf91e7602217</st_library>
                    <st_album>068d655e5079a71f,b00fed2ee4042aef</st_album>
                    <st_style oroperation="true">bd67975eea4a392e,b4b0986c3459e979,54eecfb527dee472</st_style>
                    <st_membercomment exactphrase="true" oroperation="false">pop</st_membercomment>
                    <st_membertag oroperation="false">p068d655e5079a71f,b00fed2ee4042aefp</st_membertag>
               </searchtermbundle>
               <resultview>
                    <view>track</view>
                    <sort_predefined>Date_Desc</sort_predefined>
                    <skip>0</skip>
                    <limit>2</limit>
                    <randomsortkey>2</randomsortkey>
                    <library>cc15df604221dcb1</library>
                    <album>068d655e5079a71f</album>
               </resultview>
      </searchfilters>
     <savesearchhistory>true</savesearchhistory>
</requestcloudsearch>

 

The "search within results" request is requires the <searchtermbundlehistory> element.

When building a "search within results" request, grab the entire <searchfilters> element from most recent search response.

Add a new <searchtermbundle> and <resultview> element to define the search refinement you would like to make.  

If you’re saving search history, the <searchfilter> in <responsecloudsearch> will contain an element called <parentsearchhistoryid>, it contains the encrypted history id of the search been saved. The "search within results" request requires this so that the history can be saved correctly. If <parentsearchhistoryid> is missing it will save the history as new search.

 

Removing items

Each <searchtermbundle> element has a “searchhistoryid” attribute

Each <st_....> search term element (except <st_removesearchterm> elements within <st_removesearchterms>) has a “searchtermid” attribute.

These two IDs are used by <st_removesearchterm> element for removing search terms from previous search. 

To remove items from the previous search you will need to add in <st_removesearchterms searchhistoryid="" searchtermid="" /> into the new <searchtermbundle>

 

Note: Consider creating strong type serializable classes for these objects to make the job easy. 

 

Was this article helpful?
0 out of 0 found this helpful
Have more questions? Submit a request

Comments

Please sign in to leave a comment.