Render API

👤 This documentation is intended for Developers.

The Render API is a great way to dynamically generate a downloadable pdf image of an entire dashboard for uses like email distribution and static embeds. 

Note: Render API is an add-on feature. Site administrators can contact their Account Manager for additional information. 

Using the API

Before using the API, ensure that all charts fit within the PDF page lines (viewable when charts are resized or moved). For optimal performance, ensure charts that are using the Render API are querying against the origin database and refrain from using dashboards that have a long-running query.

The Render API URL takes the following form as a POST request:

https://api.periscopedata.com/api/v1/screenshot_requests

Customers can make a request to the API using the following format:

HEADERS
Content-Type:application/json
HTTP-X-PARTNER-AUTH:<site_name>:<api_key>
BODY
     {
       "data" : {
           "dashboard_id": 1234,
           "daterange": {"start": "2015-01-01", "end": "2015-01-05"},
           "aggregation": "daily",
           "filters": [{"name": "AGE", "value": [1, 2]}],
           "dashboard_ts":  1446069112
       }
}

Each of these parameters are discussed in detail below.

Site Name

In this section, enter the site name, found in the dashboard's URL. In the example below, the site name is examplesite.

https://app.periscopedata.com/app/examplesite/1234/My-Dashboard

API Key

The account's API key is under the Settings Gear Icon Menu -> Billing and Authentication under Authentication. This ensures only account users are able to make Render API requests.

Dashboard ID

The dashboard ID can be found in the dashboard's URL, immediately preceding the dashboard name. For instance, the dashboard ID for "My Dashboard" is 1234.

https://app.periscopedata.com/app/examplesite/1234/My-Dashboard

Daterange Filter

When using the pre-built daterange filter options or selecting a number of days before the current date, include it using:

"daterange": {"days": 7}

When using a custom range, the user must specify the start and end dates:

"daterange": {"start": "2015-01-01", "end": "2015-01-05"},

Aggregation Filter

To include the dashboard aggregation in the JSON blob, add the following on its own line in the blob:

"aggregation": "daily"

Custom Filters

If the user wants to pass custom filters to the Render API link, include them like so:

"filters": [{"name": "Filter1", "value": "value1"}, {"name": "Filter2", "value": "1234"}]

If there are multiple filter values to be included for the same filter, there are the options to either include it twice or pass an array:

"filters": [{"name": "Filter1", "value": "1234"}, {"name": "Filter1", "value": "5678"}] "filters": [{"name": "Filter1", "value": ["1234", "5678"]}]

To implement child filters, an additional parameter that specifies the group (parent value) must be included. This will always be equivalent to the value of the parent filter being used:

"filters": [{"name": "ParentFilter", "value": 1234}, {"name": "ChildFilter", "value": "5678", "group": "1234"}]

When using filters in the chart titles, the display value, which is populated into the chart title, must be included. The JSON blob cannot be used with the array syntax to ensure proper parsing:

"filters": [{"name": "Filter1", "value": "1234", "display": "Display1"}]

Unused Filters

If a filter is not being used, simply omit it from the blob and no value will be passed for it.

Data Latency

The dashboard_ts value is integer seconds since the epoch (Note: millisecond precision is not supported). Charts with data older than this timestamp will be refreshed and show the updated data in the returned image.

Render API Usage

Run the JSON defining the above dashboard parameters. Periscope allows 60 API requests a minute. Periscope will return a 429 error if this limit is exceeded. If a 429 error occurs, please retry the request after one minute.

Periscope allows 500 Render API requests every 24 hours.

The response will include a URL that points to a file on S3 with the PDF of the dashboard screenshot.

Example:

{
   "url": "https://periscope-render-virginia.s3.amazonaws.com/734091687549dd3swpfc01ad094ce9.pdf"
}

Note: The S3 URL is a pre-signed URL and does expire.

The S3 URL will be immediately generated. However, please allow a few minutes for the PDF to become available. Initially, the URL will point to a text file containing 'Screenshot not ready.' Once the PDF has been uploaded, the URL will point to the downloadable PDF. 

Our support team is ready to help