Introduction
This is a brief overview how to use the Umbuzoo API. The API allow acces to all surveys and answers of their participants.
The response format is JSON and follows the HAL (Hypertext Application Language) draft.
Users and/or 3th party developers can use the API to define their own view on the surveys and their data.
Swagger UI
There’s also a Swagger UI side to test the API calls directly in the browser:
Authentication
To get your token, use this code:
import requests
# set own name and password
name = "yourname"
password = "yourpass"
baseUrl = "https://www.umbuzoo.de/api/v1"
response = requests.get(
"{}/getApiToken/?name={}&password={}".format(baseUrl, name, password),
verify=False)
token = response.text
curl -X GET --header 'Accept: text/html' \
'https://www.umbuzoo.de/api/v1/getApiToken/?name=yourname&password=yourpass'
# uses HTTPoison -> https://github.com/edgurgel/httpoison
conf = %{protocoll: 'https', host: 'www.umbuzoo.de', basePath: '/api/v1',
user: 'yourname', passwd: 'yourpass'}
url = "#{conf.protocoll}://#{conf.host}#{conf.basePath}/getApiToken/"
<> "?name=#{conf.user}&password=#{conf.passwd}"
token = case HTTPoison.get(url, [], hackney: [:insecure]) do
{:ok, %HTTPoison.Response{status_code: 200, body: body}} -> body
_ -> ""
end
Make sure to replace
yourname
andyourpass
with your name and password.
Access control to the Umbuzoo-API is implemented with tokens. So your first API call is always /getApiToken to get your token for the session. A Token expires after 1 hour (of it’s last use).
API usage is restricted to Pro- and Business Accounts (see Umbuzoo accounts).
The password
is the same that is used for the Umbuzoo login. The name
however ist not the E-Mail Adresse but the API-Name which could be seen on the users profile page.
Surveys List
To get a list of all your surveys use this code (replace the token
123456789
with your active token):
import requests, json
token = "123456789"
response = requests.get("{}/infos/?token={}".format(baseUrl, token), verify=False)
result = json.loads(response.text)
# print the name of all surveys
for theEntry in result.get("surveys", []):
print theEntry.get("name")
curl -X GET --header 'Accept: application/json' \
'https://www.umbuzoo.de/api/v1/infos/?token=123456789'
The above command returns JSON like this:
{
"surveys": [
{
"name": {
"en": "Do you like the Umbuzoo API documentation?",
"de": "Gefählt Ihnen die Umbuzoo API-Beschreibung?"
},
"id": "56f172ba2852aa2018055a88",
"replies": {
"completed": 56,
"total": 48
},
"_links": {
"info": { "href": "/api/v1/surveys/1/infos/"},
"self": { "href": "/api/v1/surveys/1/"}
}
}
],
"_links": {
"self": { "href": "/api/v1/infos/"}
}
}
The /infos/ path gives you a list of all your surveys.
HTTP Request
GET https://www.umbuzoo.de/api/v1/infos/
Description of some JSON fields
Name | Description | Example |
---|---|---|
name | The titel of the survey, grouped by it’s languages (as two letter ISO_639-1 language code - is allways used for languages in the API). | Do you like the Umbuzoo API documentation? |
id | The unique identifier of the survey. This is the default id for the survey participants in the URL. | 56f172ba2852aa2018055a88 |
replies | Summary of the surveys participants - total holds the number of all participants, completed is the number of the participants who had finished the survey. |
Survey definition
To receive the definition of a survey (replace the token
123456789
with your active token) use this code:
import requests, json
token = "123456789"
surveyIndex = 1
response = requests.get("{}/surveys/{}/?token={}".format(
baseUrl, surveyIndex, token), verify=False)
result = json.loads(response.text)
# print the headlines of all questions
for theEntry in result.get("questions", []):
print theEntry.get("headline")
curl -X GET --header 'Accept: application/json' \
'https://www.umbuzoo.de/api/v1/surveys/1/?token=123456789
The above command returns JSON like this:
{
"baseLanguage": "de",
"name": { "de": "The dark path"},
"questions": [
{
"id": "55e73f8d2852aa3f70e37b11",
"headline": { "de": "The beginning"},
"text": { "de": "You are in a dark wood. The way before you lookes like ..."},
"answers": {
"1": { "de": "Go ahead"},
"2": { "de": "Turn around and run"},
"3": { "de": "do nothing"}
},
"_links": {
"self": { "href": "/api/v1/surveys/1/questions/1/"},
"survey": { "href": "/api/v1/surveys/1/"
}
}
}
],
"is_active": true,
"id": "55e73f8d2852aa3f70e37b0e",
"supportedLanguages": ["de"],
"creation": { "de": "20:27:25 02.09.2015", "en": "20:27:25 09/02/2015"},
"_links": {
"access": { "de": "https://www.umbuzoo.de/d/55e73f8d2852aa3f70e37b0e/de/"},
"self": { "href": "/api/v1/surveys/17/"},
"questions": { "href": "/api/v1/surveys/17/questions/"}
},
"replies": {
"completed": 62,
"total": 78
}
}
This path returns the complete definition of a survey and some meta data (replies, state, …). If the survey has multiple languages all text are exported and grouped by their language code.
HTTP Request
GET https://www.umbuzoo.de/api/v1/surveys/<ID>/
Description of some JSON fields
Name | Description |
---|---|
name | The titel of the survey |
baseLanguage | Default language of the survey (is used when the participant url doasn’t have a language). |
questions | List of all questions in the survey. |
replies | Summary of the surveys participants (see above). |
is_active | Indicates if the survey is currently active (so that particpants can answer questions). |
id | The unique identifier of the survey (see above). |
Survey questions
To receive only the questions of a survey (replace the token
123456789
with your active token) use this code:
import requests, json
token = "123456789"
surveyIndex = 1
response = requests.get("{}/surveys/{}/questions/?token={}".format(
baseUrl, surveyIndex, token), verify=False)
result = json.loads(response.text)
# print the headlines of all questions
for theEntry in result.get("questions", []):
print theEntry.get("headline")
curl -X GET --header 'Accept: application/json' \
'https://www.umbuzoo.de/api/v1/surveys/1/questions/?token=123456789
The above command returns JSON like this:
{
"questions": [
{
"id": "55e73f8d2852aa3f70e37b11",
"replies": 78,
"headline": { "de": "The beginning"},
"text": { "de": "You are in a dark wood. The way before you lookes like ..."},
"answers": {
"1": { "de": "Go ahead"},
"2": { "de": "Turn around and run"},
"3": { "de": "do nothing"}
},
"_links": {
"self": { "href": "/api/v1/surveys/11/questions/1/"},
"survey": { "href": "/api/v1/surveys/1/"
}
}
}
],
"_links": {
"self": { "href": "/api/v1/surveys/1/questions/"},
"evaluation": { "href": "/api/v1/surveys/1/"}
}
}
This path list all questions definitions of the survey and how many participants had answered the question. The fields of the different question types can vary. Bellow are some common fields:
HTTP Request
GET https://www.umbuzoo.de/api/v1/surveys/<ID>/questions/
Description of some JSON fields
Name | Description |
---|---|
id | The unique identifier of the question |
headline | The titel of the question |
text | Question description |
answers | Possible answers. |
replies | How many participants had answered this questions |
Question details
To receive only one question of a survey (replace the token
123456789
with your active token) use this code:
import requests
token = "123456789"
surveyIndex = 1
questionIndex = 1
response = requests.get("{}/surveys/{}/questions{}/?token={}".format(
baseUrl, surveyIndex, questionIndex, token), verify=False)
curl -X GET --header 'Accept: application/json' \
'https://www.umbuzoo.de/api/v1/surveys/1/questions/1/?token=123456789
The above command returns JSON like this:
{
"id": "55e73f8d2852aa3f70e37b11",
"replies": 78,
"headline": { "de": "The beginning"},
"text": { "de": "You are in a dark wood. The way before you lookes like ..."},
"answers": {
"1": { "de": "Go ahead"},
"2": { "de": "Turn around and run"},
"3": { "de": "do nothing"}
},
"_links": {
"self": { "href": "/api/v1/surveys/11/questions/1/"},
"survey": { "href": "/api/v1/surveys/1/"
}
}
}
To receive just one question of the survey use this path (field explanation at previous path).
HTTP Request
GET https://www.umbuzoo.de/api/v1/surveys/<ID>/questions/<ID>/
Question replies
To get all replies of a question (replace the token
123456789
with your active token) use this code:
import requests
token = "123456789"
surveyIndex = 1
questionIndex = 1
response = requests.get("{}/surveys/{}/questions/{}/replies/?token={}".format(
baseUrl, surveyIndex, questionIndex, token), verify=False)
result = json.loads(response.text)
# print all answers
for theEntry in result.get("responses", []):
print theEntry.get("answers")
curl -X GET --header 'Accept: application/json' \
'https://www.umbuzoo.de/api/v1/surveys/11/questions/1/replies/?token=123456789
The above command returns JSON like this:
{
"responses": [
{
"id": "4e7013f184af040e9a1cfef3cb5ee62e527897b7",
"start": { "de": "09:27:46 03.09.2015", "en": "09:27:46 09/03/2015"},
"end": {"de": "09:27:51 03.09.2015", "en": "09:27:51 09/03/2015"},
"language": "de",
"completed": true,
"answers": [{ "code": 1}],
"_links": {
"survey": { "href": "/api/v1/surveys/17/" },
"question": { "href": "/api/v1/surveys/17/questions/1/" }
}
},
{
"id": "e0c33a196c414e14f127b0cab88269f3acde3ae4",
"start": { "de": "14:59:42 18.10.2015", "en": "14:59:42 10/18/2015"},
"end": { "de": "14:59:44 18.10.2015", "en": "14:59:44 10/18/2015" },
"language": "de",
"completed": false,
"answers": [{ "code": 3}],
"_links": {
"survey": { "href": "/api/v1/surveys/17/" },
"question": { "href": "/api/v1/surveys/17/questions/1/" }
}
}
],
"_links": {
"survey": { "href": "/api/v1/surveys/17/"},
"self": { "href": "/api/v1/surveys/17/questions/1/replies/" },
"question": { "href": "/api/v1/surveys/17/questions/1/"}
}
}
This path returns all the answers of the survey participants for the question.
HTTP Request
GET https://www.umbuzoo.de/api/v1/surveys/<ID>/questions/<ID>/replies/
Description of some JSON fields of the “responses” key
Name | Description |
---|---|
id | The unique identifier of the answer. |
answers | List of all answers. The code ist the key in the answers definition of a quesion (see above). |
Errors
Error Code | Meaning |
---|---|
400 | Bad Request – Your request sucks |
401 | Something went wrong concerning authentication |
500 | Internal Server Error – We had a problem with our server. Try again later. |