Displayr is designed to make it it easy to interact with the app via drag and drop, but sometimes it can be useful to grab its API and programmatically tell it what to do. In particular, this can be useful for automatically setting up documents or merging and updating data files. This blog post is the first in a series which shows you how to do this.
When using Displayr's API you need to write some code to access that API. That code must be written and run from somewhere external to Displayr. There are lots of ways to do this, but in these tutorials we assume that you are using Python on a Windows PC.
What is the Displayr API Good For?
The Displayr API is useful for:
- Automatic setup of basic projects
- Automated updating and merging of data files
It is rarely sensible to attempt to use the API to create beautiful online documents or advanced statistical analyses.
In the case of gorgeous online documents, it is almost always much faster to create a document, use it as a template, and then manually change the data, rather than attempting to write code that automates the creation of a document. This is because it is neither efficient nor appropriate to attempt to automate complicated visual layouts. We do not make all the relevant tools available for such automation in the API.
In the case of advanced statistical analysis, it is also generally a lot faster to create a single document and use it as a template.
The API is documented here. Please keep in mind when reviewing its documentation that APIs are designed for computer programmers, and the documentation is written with this audience in mind.
Step 1: Install Python
- Download the installer: Windows x86-64 executable installer
- Run the installer.
- Tick Add Python 3.7 to PATH (it's at the bottom of the screen)
- Press Customize installation
- Press Next
- Choose Precompile standard library (on Advanced Options screen)
- Click Install and wait for the installation to complete and press Close when it is complete
- Open the Windows Command Prompt (press the Windows key on your keyboard, type Command, select Command Prompt)
- Run the following line of code in the command prompt:
pip install requests. This causes various things to be installed. Leave the command prompt open on your screen. We will use it later.
Step 2: Obtain your Company secret credentials from Displayr
In order to use the API you need a code, known as the Company secret. Contact Displayr support (firstname.lastname@example.org) and request the Company secret for your API. This is not available for free accounts.
Step 3: Download the createproject.zip file
- Click here to download the zip file
- Double-click on it to open it
- Save its contents somewhere on your computer or network
The zip file contains:
- A file called qscript.QScript which contains a QScript giving Displayr a series of instructions (e.g., uploading a data file, creating new pages, creating charts, applying templates to these charts)
- A chart template called LinePlot.QTemplate
- A data file called Phone.sav
Step 4: Open createproject.py in a text editor
A text editor is a program specifically designed for editing text files. All windows computers come with a simple text editor called Notepad. Please open Notepad - if using a modern version of Windows, type Notepad into the Type here to search box at the bottom of the screen - or another text editor. Do not use Word or WordPad.
Step 5: Update the file
The file createproject.py tells Displayr to create the document, by running the QScript. To get it to run you need to make a few modifications:
- On line 33, insert the Company secret where it says insert-company-secret-here-(contact-displayr-support)
- On line 36 replace insert-new-document-name-here with your desired name for the document to be created. If you wish to overwrite an existing document you will need to first delete that document (otherwise, you will see the message Check that the project name is unique).
- Save the file.
Step 6: Running the API script
- Find the folder containing the API script files in Windows Explorer, and click into top toolbar and copy the file path (see to the right)
- If it's not already open, open the Windows Command Prompt (press the Windows key on your keyboard, type Command, select Command Prompt)
- Type cd and then space and Ctrl-V to paste in your path and press Enter (e.g., cd Users\Chris\Demo).
- Type the name of your file (createproject.py if you have not changed this) and press Enter
- Windows will likely confirm that you want to run this using Python; check \Always use this app to run .py files and press OK
- If you don't get an error, you will see some output. The bottom of it will look something like this. If it contains the word Success, all has gone well :b'<!DOCTYPE html>\r\n<html>\r\n<head>\r\n <title>API/ImportUpdatedData Output</title>\r\n</head>\r\n<body>\r\n<h1>Success</h1>\r\n\r\n\r\n</body>\r\n</html>'
- Go to your Documents page and it will contain the new document. If you already had Documents open, refresh the page to make it appear.
Step 7: Make a note of the Document secret
When a document is created a Document secret credential (also known as the project secret) is created at the same time. You need this if you wish to modify this document using the API. This can also be obtained from the documents Document settings page.
The next post in this series is Merging Data Files using the API.