Embed API

Programmatically Embedding Dashboards

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

Note: Whitelabeled Embeds (Removing "Powered by Periscope Data" footer) are an add-on feature. Site administrators can contact their Account Manager for additional information. 

The embed API URLs take the following form:

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

Encoding the Data

The data to specify the embed's parameters is a URL-encoded JSON blob. You can find our documentation on the various options available to the embed API 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

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

Our support team is ready to help