Implementation Guide


HM API Cloud Search aims to provide fast and efficient searching of a number of entities within the Harvest Media platform.

Currently we support searching on:

  1. Tracks
  2. Albums
  3. Libraries
  4. Composers
  5. Categories
  6. Keywords
  7. All of the above

The way in which you configure to search for each of these entities varies, however the core framework remains the same. At the core of each requestcloudsearch and responsecloudsearch object we have the following sections..

A quick summary of each is below:

  • Options; these are used to set up the search environment. For example, in this section you would identify whether you are searching on tracks account-wide, or just within tracks for a member. You can look at these as your top-level configuration options.

  • SearchTermBundle; this is your current search terms for the search being performed

  • SearchTermBundleHistory; these are you previous search terms for the search being performed. This should only exist if you are performing within result searches, otherwise you will only ever have a SearchTermBundle

  • ResultView; where the Configuration options are your top-level options setting up the environment, this is your current search options setting up your search results. Here, you can set up paging or modify the order in which the results are returned.


Whilst a search sounds simple in nature, setting up a "within results" search can be confusing at first. As such, below, we have listed a number of key things to look out for as well as a few recommendations on how to use various options.

Search Filters & Search Crumbs

In general, if your site maintains a list of search crumbs to show the user the terms on which they have been searching on, each of these should map to a single SearchTermBundle. This is a good way to break down how youearchTermBundle & SearchTermBundleHistory should look when requesting a search.

Example of a site having just one search crumb (a simple not-within-result search) – Keyword: Pop

  • In this example, when performing the request, you would have a SearchTermBundle and no SearchTermBundleHistory,
  • In this example, when receiving the response, you would have no SearchTermBundle however a single SearchTermBundleHistory of the keyword search Pop

Example of a site having more than one search crumb (a within-result search) – Keyword: Pop & Keyword: Dance

  • In this example, when performing a request, you would have a SearchTermBundle and a single SearchTermBundleHistory. The SearchTermBundle of keyword search Dance and a SearchTermBundleHistory of keyword search Pop
  • In this example, when receiving the response, you would have no SearchTermBundle however two SearchTermBundleHistory. 1 for keyword search Pop and 1 for keyword search Dance


Regions & Members

In order for searches to be saved against the correct region, it is recommended to always include Region and MemberAccount. These are set within the Configuration Options section.


Composer, Categories, Libraries and Albums

When performing searches for a specific entity, for example a specific Album or Library it is recommended to search using ID’s as opposed to free text on the Album title or Library name. We have gone to lengths to provide efficient structures for searching using these terms so in order to have the fastest possible responses delivered to your site, please use these.


Search History

Search history is an important part of our Cloud Search capabilities. In order to have your search history maintained there are a number of rules that should be followed. Following these will not only mean your search history will be saved, but they will also enhance your knowledge of our Cloud Search capabilities:

Search History & the Response Object

After having performed a search you will notice that in your Response Object it will include a ParentSearchHistoryID property as well as a SearchTermBundleHistory. These MUST be maintained for future searches if you are doing within result searches. If this is not sent into subsequent searches then the search history will not be maintained and your search may not work as expected or be recorded as expected when viewing the Search Keyword Reports in the HM Admin

  • ParentSearchHistoryID; this will change each time you perform a search. In order to maintain a correct search history you will need to pass the changed value into any within-result searches each time. For new searches you need to remove it.

  • SearchTermBundleHistory; will contain your SearchTermBundle that you passed into the Request Object, however it will contain the following important attributes; SearchTermBundle contains a “searchhistoryid” attribute and the SearchTerm_ contains a “SearchTermID”. It’s essential that they are included in the Request object for within result searches each time until a new search is performed from scratch.

Search History, the Request Object and removing search crumbs

When removing a search crumb from a within-result search it is important that the removal is sent in the request when performing a new search and is not just removed. This is so that the search history maintains that a removal took place.

If we take our previous example, in which we had Keyword: Pop & Keyword: Dance, and remove Dance then we need to send that removal to perform the search. So we would have two SearchTermBundleHistory, one for Pop and one for Dance and a single SearchTermBundle that includes our removal of Pop (<st_removesearchterm searchhistoryid="1" searchtermid="131072"/>)


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


Article is closed for comments.