1. Introduction
This guidance document explains how to use the Application Programming Interface (API) for the Impact & Insight Toolkit, which allows you to connect other data tools or dashboards directly with your survey data.
This document has been written with those in mind that already have an understanding of APIs and the technologies involved.
To understand more about this API, please read the accompanying blogpost.
2. Using the API
By default, the API is disabled for each organisation. If you would like to make use of it, the first thing you need to do is get in touch.
Please email the Counting What Counts support team at [email protected] and let us know you would like to use the API.
We will enable the API for your organisation and provide you with your organisation ID, which you will need next.
To query data via the API, you need an API key which you create yourself using your Culture Counts login details (email and password) and the ID of the organisation whose data you want to access.
Note – You can only access data for an organisation which your Culture Counts user is associated with.
The API base URL is https://api.impactandinsight.co.uk.
To create an API key, you make a POST request to the v1/keys/keygen endpoint. See the documentation page for complete details about what information must be submitted to create an API key, to create a key, and to see the available endpoints.
Once you have your API key, you can make GET requests to the data endpoints using this key to query data on your evaluations and survey responses.
3. Managing API keys
- When you are provided with an API key, it is your responsibility to manage the key and to ensure it remains private, like you would a password. This is because anyone with your API key can use it to access data for your organisation.
- Use the documentation page to invalidate either specific keys or all keys for an organisation you are shared with or for your own email address. You might do this if you accidentally publish your API key and don’t want anyone else to use it.
- You can only have one key per email address/organisation ID combination. Creating a new API key for an organisation you have already created one for will invalidate any keys created previously. If your email address is associated with more than one organisation, you can have keys for each organisation.
- Keys will provide access for 30 days by default. You can specify a longer or shorter lifespan when you request your key.
4. Usage restrictions
The API is rate limited per organisation to:
-
- 100 requests in any 30-minute period
- 1000 requests in any 24-hour period
The database which the API interacts with is updated daily at approximately 3am. This means that you should wait until the next day to see any changes made to your evaluations, including ‘newly collected’ data.
5. Power BI example
We know that Power BI is a commonly-used dashboarding tool. Therefore, we are providing you with further information on how to connect your Toolkit data to a dashboard you’ve built in Power BI.
Step 1 – Create your API key
You can use the documentation page to create an API key as shown below.
- Under the /v1/keys/keygen section, click on ‘Try it out’. If you do not, you will not be able to enter any values into the fields.
- Enter your email and password for your Culture Counts account. Also enter the organisation ID which your account is associated with and which you would like to access the data for.
- By default, the API key is set to expire in 30 days. You can change this if you wish.
Once you have done this, click the blue ‘Execute’ button.
If you have entered your details correctly, you will then be provided with an API key and confirmation of the email address and organisation which it relates to.
Step 2 – Add the data using the Web data source
Once you have your API key, it can be used in a dashboard.
Click the ‘Get data’ button on the ribbon at the top.
This opens a panel where you can include the API endpoint you wish to add and your API key.
The image below shows that there are fields to complete with your own information for [YOUR ORGANISATION ID] and [YOUR API KEY]. You will also need to write the header parameter as “Authorization” and include the word “Bearer” before your API key.
Once this is done you will be able to load your Toolkit data directly into your dashboard.
If you have any further questions about using the Impact & Insight Toolkit API, please do get in touch.