Embed API

👤 This documentation is intended for Site Administrators.

Periscope's Embed API allows the user to programmatically specify filters and their values in the URL when embedding dashboards or individual charts.

Note: Use of the Embed API and Whitelabeled Embeds (Removing "Powered by Periscope Data" footer) are add-on features. Site administrators can contact their Account Manager for additional information. 

<div><UL>
<LI><a href="#EmbedDashboard">Programmatically Embedding Dashboards</a></LI>
<UL>
<LI><a href="#EncodeDashboard">Encoding the Data For A Dashboard</a></LI>
<LI><a href="#SignRequestDashboard">Signing the Request</a></LI>
</UL>
<LI><a href="#EmbedChart">Programmatically Embedding Single Charts</a></LI>
<UL>
<LI><a href="#EncodeChart">Encoding the Data For A Single Chart</a></LI>
<LI><a href="#SignRequestChart">Signing the Request</a></LI>
</UL>
<LI><a href="#LookingforMore">Looking for More?</a></LI>
</UL></div>
<HR>

<a name="EmbedDashboard"></a>

Programmatically Embedding Dashboards

The embed API URLs take the following form:

https://www.periscopedata.com/api/embedded_dashboard?data={data}&signature={signature}

<a name="EncodeDashboard"></a>

Encoding the Data For A Dashboard

The data to specify the embed's parameters is a URL-encoded JSON blob. The documentation on the various options available to the embed API are here. For this example, the blob should look like:

{
    "dashboard": 7863,    
    "embed": "v2",    
    "filters": [{"name": "Filter1", "value": "value1"},
         {"name": "Filter2", "value": "1234"}]
}

The data should be URL-encoded. The above blob URL-encodes to:

%7B%22dashboard%22%3A7863%2C%22embed%22%3A%22v2%22%2C%22filters%22%3A%5B%7B%22name%22%3A%22Filter1%22%2C%22value%22%3A%22value1%22%7D%2C%7B%22name%22%3A%22Filter2%22%2C%22value%22%3A%221234%22%7D%5D%7D

<a href="#top">Back to top</a>

<a name="SignRequestDashboard"></a>

Signing the Request

The API key is required to calculate the signature. The administrator can find it in the Billing and Authentication tab of the gear menu in the lower left-hand corner of Periscope.

Note: The API Key is unique to a site and is what allows changing the embed to any dashboard or filter set. Avoid exposing this API Key by storing them as environment variables. If an API Key has been accidentally revealed, please reach out to support@periscopedata.com or the in-app live chat to get the API Key rotated.

The signature is the hex-encoded SHA256-HMAC of the API key and the URL path, including the data. For the URL path, add '/api/embedded_dashboard?data=' to the beginning of the encoded JSON such that the string to encode is:

/api/embedded_dashboard?data=%7B%22dashboard%22%3A7863%2C%22embed%22%3A%22v2%22%2C%22filters%22%3A%5B%7B%22name%22%3A%22Filter1%22%2C%22value%22%3A%22value1%22%7D%2C%7B%22name%22%3A%22Filter2%22%2C%22value%22%3A%221234%22%7D%5D%7D

For this example, use a sample API key of e179017a-62b0-4996-8a38-e91aa9f1.

Given this API key and this path, the hex(sha256_hmac(key, path)) is:

adcb671e8e24572464c31e8f9ffc5f638ab302a0b673f72554d3cff96a692740

Thus, the final request is:

https://www.periscopedata.com/api/embedded_dashboard?data=%7B%22dashboard%22%3A7863%2C%22embed%22%3A%22v2%22%2C%22filters%22%3A%5B%7B%22name%22%3A%22Filter1%22%2C%22value%22%3A%22value1%22%7D%2C%7B%22name%22%3A%22Filter2%22%2C%22value%22%3A%221234%22%7D%5D%7D&signature=adcb671e8e24572464c31e8f9ffc5f638ab302a0b673f72554d3cff96a692740

<a href="#top">Back to top</a>

<a name="EmbedChart"></a>

Programmatically Embedding Single Charts

The embed API URLs take the following form:

https://www.periscopedata.com/api/embedded_dashboard?data={data}&signature={signature}

<a name="EncodeChart"></a>

Encoding the Data For Single Charts

The documentation on the various options available to the embed API are here. For single chart embeds, the blob should look like:

{
    "dashboard": 7863,  
    "chart" : 4458861,  
    "embed": "v2",    
    "filters": [{"name": "Filter1", "value": "value1"},
         {"name": "Filter2", "value": "1234"}]
}  

The above blob URL-encodes to:

%7B%22dashboard%22%3A7863%2C%22widget%22%3A+4458861%2C+%22embed%22%3A%22v2%22%2C%22filters%22%3A%5B%7B%22name%22%3A%22Filter1%22%2C%22value%22%3A%22value1%22%7D%2C%7B%22name%22%3A%22Filter2%22%2C%22value%22%3A%221234%22%7D%5D%7D

<a name="SignRequestChart"></a>

Signing the Request

Calculating the signature for a single chart embed is done the same way it is done for embedded dashboards described above.

<a href="#top">Back to top</a>

<a name="LookingforMore"></a>

Looking for More?

For addition Embed API Options, click here.

Try our community page for guidance on topics like:

<a href="#top">Back to top</a>

Our support team is ready to help