NAV
python shell elixir

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:

api-swagger.umbuzoo.de

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 and yourpass 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.