MyStore Search API

The MyStore Search API allows web applications to search for SNOCAP MyStores and display them on a web page. The API accepts artist names and/or track titles passed as URL parameters and returns results as an object in javascript object notation (JSON). This interface is useful for applications that wish to render MyStore storefronts on web pages based on contextual metadata matching. For example, a web site may wish to add MyStores on pages that discuss a particular artist or song, allowing users to sample, purchase and download relevent tracks.

Terms of Use

By using the SNOCAP MyStore Search API, you accept and agree to be bound by the Terms of Use.

Note: This API is BETA. The location of the URL, the format and names of the parameters, and the format of the results may change. We will try to maintain backwards compatibility, but may choose to alter it in the name of progress.

Syntax

http://restsearch.snocap.com/RESTSearch/snocapsearch.php?
artist=artistterms&title=titleterms&binaryoperator=operator

Parameter Description
artistterms One or more terms, separated by "+", used to match against arist names associated with MyStores. This parameter is optional, but either artistterms or titleterms must be supplied.
titleterms One or more terms, separated by "+", used to match against track titles associated with MyStores. This parameter is optional, but either artistterms or titleterms must be supplied.
operator Either the string "and" or "or". When "and" is passed, all terms supplied for artist and title must match terms in the MyStore. When "or" is passed, any term supplied in artist and title may match terms in the MyStore. If this parameter is not provided, the "or" operator is used.

Return Value

The MyStore Search API returns an object in JSON notation containing an array of search results. The returned object has the following fields.

Field Description
TotalNumStores
The number of MyStores returned in the result. A maximum of 100 results are returned.
Stores[]
An array of "Stores" objects.
Stores[].StoreID 
For this particular store, the unique code that is used to identify the MyStore and render the storefront.
Stores[].TotalNumTracks 
For this particular store, the number of tracks that contained matching terms.
Stores[].Tracks[] 
An array of "Tracks" objects.
Stores[].Tracks[].TrackID 
An identifier refering to this particular track in this particular store.
Stores[].Tracks[].Artists[] 
An array of artist names matching the search terms for this particular track in this particular store.
Stores[].Tracks[].Titles[] 
An array of track titles matching the search terms for this particular track in this particular store.

JSON Notation Example

If you invoke the search API with the following parameters, a single store is returned.

http://restsearch.snocap.com/RESTSearch/snocapsearch.php?
artist=thor&title=metal&binaryoperator=and

The JSON results are as follows (with extra whitespace added for readability):

{
  "TotalNumStores":1,
  "Stores":
  [
    {
      "StoreID": "T3-31324-G8TCN32XFR-N",
      "TotalNumTracks":1,
      "Tracks":
      [
        {
          "TrackID":3619277,
          "Artists":["Steel Gerbil of Thor"],
          "Titles":["Metal Dogs Rust in the Rain"]
        }
      ]
    }
  ]
}

The same result as you would actually get it, with whitespace removed, looks like this:


{"TotalNumStores":1,"Stores":[{"StoreID":"T3-31324-G8TCN32XFR-N","TotalNumTracks":1,"Tracks":[{"TrackID":3619277,"Artists":["Steel Gerbil of Thor"],"Titles":["Metal Dogs Rust in the Rain"]}]}]}

Rendering a MyStore with a StoreID

The StoreID value returned in the API results is a unique identifier from which a MyStore flash storefront can be rendered. To render a storefront in a web page, generate the following HTML:

<embed src="http://void.snocap.com/s/StoreID/" width="425" height="300" 
  style="background: url(http://void.snocap.com/b/StoreID)" />

where StoreID is the value of the StoreID field returned in the results.

The rendered storefront corresponding to the previous example is displayed here.

Javascript Code Sample

The following javascript code uses the XMLHttpRequest object to issue a MyStore search, then converts the resulting JSON string into an object and dynamically adds the corresponding MyStores to an HTML element.

var xmlHttp; // a global object representing the XMLHttpRequest

//
// This function is called with the artist and title terms used
//  in the search. The "and" operator is hardcoded here.
//
function doSearch(artist, title)
{
   xmlHttp=GetXmlHttpObject();
  if (xmlHttp==null)
  {
    alert ("Your browser does not support Ajax");
    return;
  }

  var url="http://restsearch.snocap.com/RESTSearch/snocapsearch.php?artist=" 
    + artist + "&title=" + title + "&binaryoperator=and";

  xmlHttp.onreadystatechange=stateChanged;
  xmlHttp.open("GET",url,true);
  xmlHttp.send(null);
} 

//
// This is the callback function invoked when the 
// search API returns
//
function stateChanged() 
{
  if (xmlHttp.readyState==4 || xmlHttp.readyState=="complete")
  { 
    var displayStr="";

    // The responseText contains the string in JSON format.  
    // Evaluate it to convert to a javascript object.
    var myObj = eval( "(" + xmlHttp.responseText + ")");

    // Get all the MyStores returned and build the HTML that 
    // will display them
    var i;
    for(i = 0; i < myObj.TotalNumStores; i++)
    {
      displayStr = displayStr + 
        '<embed src="http://void.snocap.com/s/' + 
        myObj.Stores[i].StoreID +
        '/" width="425" height="300" style="background: url(http://void.snocap.com/b/' + 
        myObj.Stores[i].StoreID +
        ')" />';
    }

    // Add the MyStores to the innerHTML of the element "targetElement"
    document.getElementById("targetelement").innerHTML=displayStr;
  } 
} 

//
// This is a cross-browser function used to get the XMLHttp object
//
function GetXmlHttpObject()
{ 
  var objXMLHttp=null
  if (window.XMLHttpRequest)
  {
    objXMLHttp=new XMLHttpRequest();
  }
  else if (window.ActiveXObject)
  {
    objXMLHttp=new ActiveXObject("Microsoft.XMLHTTP");
  }
  return objXMLHttp;
} 

Cross-Domain Scripting Issues

Most browsers prevent pages served from one domain to access code served from another. The example above actually won't work when the page containing this javascript is served from a domain other than "SNOCAP.COM". The common practice to address this issue is to either invoke the MyStore Search API from a server and process the results on the back-end before the web page is sent to the browser, or to implement a web proxy that runs in the same domain as the page that is calling it. A proxy can simply pass the parameters to the SNOCAP API and return the results to the caller. Since the proxy and the page that calls it are served from the same domain, there are no cross-domain issues.

The Yahoo! Developer Network has a good discussion of this issue and the common work-arounds here.

Leave a Reply

Please log in using one of these methods to post your comment:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

Follow

Get every new post delivered to your Inbox.

%d bloggers like this: