SGmetadata REST API Example

SGmetadata REST API

Introduction

The SGmetadata REST API allows users to make requests for in-stream metadata from any platform that can make HTTPS GET requests. This page is documentation for the SGmetadata JavaScript client that abstracts the SGmetadata REST API.

Download

Additional SGMetadata API documentation can be downloaded here.

Introduction
JavaScript Client Integration
API Documentation and Examples

JavaScript Client Integration

Download the SGmetadata client JavaScript here.

Include the SGmetadata client JavaScript in the head of your page.<script src="sgmetadata-client.js" type="text/javascript"></script>

Add the following script tag to the end of your page just above the closing body tag. Make sure to set your own values for scraperUUID and accountApiKey.


                    <script type="text/javascript">
    //This is the UUID for the example scraper.
    var scraperUUID = 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx';
    //This is your SGmetadata account API key.
    var accountApiKey = 'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx';

    //Build an API client instance with your specific api key.
    //This client abstracts the HTTP endpoints for the SGmetadata api.
    var sgmd = SGMetadata({apiKey: accountApiKey});

    //Fetch an array of all metadata objects for the metadata scraper.
    sgmd.getMetadata(scraperUUID, function(metadataArray) {
        //Handle the array of metadata objects from the api response.
        yourMetadataDisplayFunction(metadataArray);
    });
</script>

If you wish to request Smart Metadata from the SGmetadata API, you may add the following script tag to the end of your page. Make sure to set your own value for monitorUUID.


                    <script type="text/javascript">
    //This is the UUID for the example Smart Monitor
    var monitorUUID = 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx';

    //Fetch the  most recent smart metadata object for the smart monitor.
    sgmd.getSmartMetadata(monitorUUID, function(smartMetadata) {
        //Handle the smart metadata object from the api response.
        yourMetadataDisplayFunction(smartMetadata);
    });

    //(Optional) Fetch the 10 most recent smart metadata objects for the smart monitor.
    sgmd.getRecentSmartMetadata(monitorUUID, 10, function(smartMetadataArray) {
        //Handle the smart metadata array from the api response.
        yourMetadataDisplayFunction(smartMetadataArray);
    });

    //(Optional) Fetch the first page of the smart metadata objects for the smart monitor.
    sgmd.getSmartMetadataPage(monitorUUID, 1, 10, function(smartMetadataPage) {
        //Handle the array of smart metadata objects from the api response.
        yourMetadataDisplayFunction(smartMetadataPage);
    });
    </script>

Additional calls to any SGMetadata API client functions can now be executed. For further documentation, read the API Documentation and Examples section below or download the API documentation here.

API Documentation and Examples

This section contains descriptions of all SGMetadata REST API client functions along with live examples of results from each API function. You can view the development console for detailed listings of the API response objects by pressing the f12 key.

SGMetadata.getCurrent(uuid, function callback(response){})

param uuid (String) The SGmetadata unique id string matching the SGmetadata scraper you wish to request metadata for.
param callback (Function) The function to invoke and pass a response object to when the api request is complete.
callback param response (Object) The metadata response object from the api request. Contains properties: StreamTitle, StreamUrl, date, timestamp.

The getCurrent function requests the most recent metadata object from the scraper.

The response object has the following properties:

StreamTitle (String)

The most recent metadata string from the stream.

Live Example:
StreamUrl (String or Undefined)

The most recent url query string from the stream. This field will be undefined if the stream does not send any StreamUrl metadata.

Live Example:
date (String)

The date of when the metadata changed. This property is localized to SGmetadata server time (Central Standard Time).

Live Example:
timestamp (Integer)

The epoch timestamp (in milliseconds) of when the metadata changed. This property can be used to build a localized display date.

Live Example:

Localized date using example timestamp:

SGMetadata.getMetadata(uuid, function callback(responseArray){})

param uuid (String) The SGmetadata unique id string matching the SGmetadata scraper you wish to request metadata for.
param callback (Function) The function to invoke and pass a response array to when the api request is complete.
callback param responseArray (Array of Objects) The array of metadata response objects from the api request. Each object in the array contains properties: StreamTitle, StreamUrl, date, timestamp.

The getMetadata function requests the entire history of metadata objects for the scraper matching the given UUID. The responseArray passed to the callback is an array of metadata objects with the same properties as the single response object returned by SGMetadata.getCurrent().

By default, the responseArray is in chronological order with the most recent (now playing) metadata at index 0, and the previously played song metadata at indices 1 to n where n is the total number of metadata items tracked by the scraper matching the given UUID.

The table below is constructed from data returned by a getMetadata call.

Index	StreamTitle	StreamUrl	date	timestamp

SGMetadata.getCurrentRaw(uuid, function callback(response){})

param uuid (String) The SGmetadata unique id string matching the SGmetadata scraper you wish to request metadata for.
param callback (Function) The function to invoke and pass a response string to when the api request is complete.
callback param response (String) The metadata response string from the api request.

The getCurrentRaw function requests the most recent raw metadata string from the scraper matching the given UUID. The response from this function is an unmodified string of all metadata that was most recently extracted from the stream by the scraper.

Live Example:

SGMetadata.getMetadataRaw(uuid, function callback(responseArray){})

param uuid (String) The SGmetadata unique id string matching the SGmetadata scraper you wish to request metadata for.
param callback (Function) The function to invoke and pass a response array to when the api request is complete.
callback param responseArray (Array of Strings) The array of metadata response strings from the api request.

The getMetadataRaw function requests the entire history of raw metadata strings for the scraper matching the given UUID. The responseArray passed to the callback is an array of raw metadata strings.

By default, the responseArray is in chronological order with the most recent (now playing) metadata string at index 0, and the previously played song metadata strings at indices 1 to n where n is the total number of metadata items tracked by the scraper matching the given UUID.

The table below is constructed from data returned by a getMetadataRaw call.

Index	Metadata

SGMetadata.getSmartMetadata(uuid, function callback(metadata){})

param uuid (String) The SGmetadata unique id string matching the Smart Monitor you wish to request metadata for.
param callback (Function) The function that will be invoked with response metadata when the api request is complete.
callback param metadata (String) The metadata object from the api request.

The getSmartMetadata function requests the most recent smart metadata object from the Smart Monitor matching the given UUID. The response from this function is a smart metadata object with the properties: streamTitle, streamUrl, and data.

streamTitle (String)

The pre-formatted stream title string created from the smart metadata data object.

Live Example:
streamUrl (String)

The pre-formatted stream url string created from the smart metadata data object.

Live Example:
data (Object)

The raw Smart Metadata data object used to generate the above streamTitle and streamUrl strings.

Live Example:

SGMetadata.getSmartMetadataPage(uuid, pageNumber, pageSize, function callback(smartMetadataPage){})

param uuid (String) The SGmetadata unique id string matching the Smart Monitor you wish to request metadata for.
param pageNumber (Integer) The page number you'd like your paginated response data to begin on.
param pageSize (Integer) The number of smart metadata entries you'd like to receive per-page.
param callback (Function) The function that will be invoked with response data when the api request is complete.
callback param smartMetadataPage (Object) The page object containing pagination metadata and an array of smart metadata objects. Contains properties: meta and data.

The getSmartMetadataPage function requests a single page of smart metadata objects from the entire history of metadata objects for the Smart Monitor matching the given UUID. The smartMetadataPage passed to the callback contains an array of smart metadata objects with the same properties as the single response object returned by SGMetadata.getSmartMetadata().

By default, the smartMetadataPage data is in chronological order with the least recent (oldest) smart metadata one page 1, and the most recent (newest) smart metadata on the last page indicated by meta.lastPage.

The table below is constructed from data returned by a getSmartMetadataPage call.

Index	streamTitle	streamUrl	date

SGMetadata.getRecentSmartMetadata(uuid, count, function callback(smartMetadataArray){})

param uuid (String) The SGmetadata unique id string matching the Smart Monitor you wish to request metadata for.
param count (Integer) The number of smart metadata objects you want to retrieve from the API.
param callback (Function) The function that will be invoked with response data when the api request is complete.
callback param smartMetadataArray (Array of Objects) The array of smart metadata objects. Each entry contains the properties: streamTitle, streamUrl, and data.

The getRecentSmartMetadata function requests X number of the most recent smart metadata objects from the Smart Monitor matching the given UUID. The data passed to the callback is array of smart metadata objects with the same properties as the single response object returned by SGMetadata.getSmartMetadata().

By default, the smartMetadataArray is in chronological order with the most recent (now playing) metadata object at index 0.

The table below is constructed from data returned by a getRecentSmartMetadata call.

Index	streamTitle	streamUrl	date