UPCOMING WEBINAR: Finding the story in your survey data Register now >>

Articles in this section

How to Get Started with the Displayr API

  • Updated
Follow

The Displayr API is useful for automating certain functions, such as setting up basic projects and/or updating or merging data files. The API has a technical reference guide.

It is rarely sensible to attempt to use the API to create beautiful online documents or advanced statistical analyses. It's much more sensible to create a single document in Displayr and use it as a template.

This article contains the steps required to get you started with the Displayr API.

 

Requirements

Please note these steps require a Displayr license.

  • The API Documentation. The documentation can be found here with more technical details found here. Please note that this documentation is designed and written to be used by computer programmers.
  • A PC running Windows.
  • Python software.
  • An Enterprise Displayr license with purchased View hours.
  • Company secret credentials. To obtain your Company secret please contact Displayr support by emailing support@displayr.com.
  • The createproject.zip containing a QScript, a chart template, and a data file.
  • For a fully automated worked example of how to use the Displayr API to build and update a presentable dashboard, see Displayr API Demo.

Step 1 - Install Python 

  1. Download the installer: Windows x86-64 executable installer.
  2. Run the installer.
  3. Tick Add Python 3.9 to PATH (it's at the bottom of the screen).
  4. Press Customize installation.
  5. Press Next.
  6. Choose Precompile standard library (on Advanced Options screen).
  7. Click Install and wait for the installation to complete and press Close when it is complete.
  8. Open the Windows Command Prompt (press the Windows key on your keyboard, type Command, select Command Prompt).
  9. 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 - Download and update the createproject.py file 

  1. Download the createproject zip file in the Requirements section above.
  2. Double-click on the file to open it.

  3. The zip file contains multiple files including a Python script for creating projects (createproject.py).

    Save all the files somewhere on your computer or network.
  4. Open the createproject.py file using a text editor (e.g. Notepad if using Windows).
  5. On line 6, depending on the deployed region you may have to change the host_name.
  6. You can find out your Region by looking at the domain URL for your account. Depending on the Region change the host_name accordingly on lines 6 through 14 of the createproject.py file.

    Region Host Name

    australiaeast

    australiaeast.displayr.com

    canadacentral

    canadacentral.displayr.com

    app (hosted in East US)

    app.displayr.com

    southeastasia

    southeastasia.displayr.com

    westeurope

    westeurope.displayr.com
  7. On line 42, insert the Company secret where it says insert-company-secret-here-(contact-displayr-support)
  8. On line 45 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).
  9. Save the file.

Step 3 - Run the API Script

  1. Find the folder containing the API script files in Windows Explorer, and copy the file path (eg C:\Users....\DisplayrAPIClient).
  2. Open the Windows Command Prompt by pressing the Windows key on your keyboard and typing Command into the search bar, and selecting Command Prompt.
  3. Type cd and then space and Ctrl-V to paste in your path and press Enter (eg, cd  C:\Users....\DisplayrAPIClient).
  4. Type the name of your file (eg createproject.py unless you renamed the file) and press Enter.
  5. Windows will likely confirm that you want to run this using Python; check \Always use this app to run .py files and press OK. 
  6. OPTIONAL: In case the script doesn't run, repeat Step 4. 
  7. If you don't get an error, Windows will return an output, the bottom of which will look similar to the below.
    :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>'
  8. In Displayr, go to or refresh your Documents page and confirm a new document was created. 

Next

How to Obtain the Document Secret for Use in the Displayr API

How to Import Data via the Displayr API

How to Merge Data Files Using the Displayr API

How to Create a QScript for Importing Data into a New Document via the Displayr API

 

 

Related articles