Quick Start

Here are simple examples of calling the Geneea VoC API. Expected inputs and outputs are described in the VoC API Reference, which also contains a full description of the API. To use the API, you need a valid API key. Please get in touch with us if you do not have it here.

Define Configuration

First, you need to set up a configuration for your particular use case aka touchpoint. You provide the following information:

• name: name your configuration

• description: describe your configuration (optional).

• domain: Optionally, set the domain of the questionnaire. Out of the box, we support these domains: general (voc), restaurants (voc-hospitality), or banking (voc-banking).

• language: Optionally, specify the language of the answers (en, cs, sk, de). If not specified, the langauge is detected automatically.

• textColumns: Specify, what types of text answers (verbatims) are provided. We distinguish three types:

  • PROS – positive texts (answers to questions like What did you like?)

  • CONS – negative texts (answers to questions like What didn’t you like?).

  • OTHER – general texts (answers to questions like Why did you assign this score, Your comment, Any other comment, etc.)

• metaColumns: Set the names and types of metadata (optional).

In the following example, we set up a configuration to analyze questionnaires about banking with three answers in English: positive feedback in positive_text, negative feedback in negative_text, and general feedback in general_text:

pythonphp

import requests

def vocConfig(input):
    url = 'https://voc-api.geneea.com/gfas/v1/config'
    headers = {
        'content-type': 'application/json',
        'Authorization': 'user_key <your user key>'
    }
    return requests.post(url, json=input, headers=headers).json()

print(vocConfig({
    'name': 'touchpoint_1', 'description': 'for API testing',
    'domain': 'voc-banking', 'language': 'en',
    'textColumns': [
        {'name': 'positive_text', 'type': 'PROS'},
        {'name': 'negative_text', 'type': 'CONS'},
        {'name': 'other_text', 'type': 'OTHER'}
    ],
    'metaColumns': [
        {'name': 'stars', 'type': 'NUM'}
    ]
}))

Through this you will get your configId.

{
    'configId': '5fe0ae5efb1b79330d91f08ee1a9e9f6'
}

This configId needs to be used in subsequent requests.

Analyze Feedback

The following requests analyzes a single answer to a questionnaire configured above.

pythonphp

import requests

def callGeneea(input):
    url = 'https://voc-api.geneea.com/gfas/v1/analysis'
    headers = {
        'Accept': 'application/json',
        'Authorization': 'user_key <your key>'
    }
    return requests.post(url, json=input, headers=headers).json()

print(callGeneea({
    'feedbackId': '1',
    'configId': '5fe0ae5efb1b79330d91f08ee1a9e9f6',
    'texts': {
        'positive_text': 'I really liked the logo of the credit card.',
        'negative_text': 'I did not like the interest.',
        'other_text': 'I have no other feedback.'
    },
    'metadata': {
        'stars': 3
    },
    'date': '2019-02-03T10:15:30Z'
}))

produces the following results (see the AnalysisResponse reference page for explanation):

{
    'feedbackId': '1',
    'configName': 'touchpoint_1',
    'textAnalyses': {
        'positive_text': <ANALYSIS_OBJ>,
        'negative_text': <ANALYSIS_OBJ>,
        'other_text': <ANALYSIS_OBJ>
    }
}

where the <ANALYSIS_OBJ> has a structure as G3 Response.

Listing Configs

You can list all your configs using the configs method:

pythoncUrl

import requests

def vocConfigs():
    url = 'https://voc-api.geneea.com/gfas/v1/configs'
    headers = {
        'content-type': 'application/json',
        'Authorization': 'user_key <your user key>'
    }
    return requests.get(url, headers=headers).json()

print(vocConfigs())

Updating Configs

A config can be updated using the same endpoint as was used to create it, just the config id is filled as well. The following call updates the configs description:

python

import requests

def vocConfig(input):
    url = 'https://voc-api.geneea.com/gfas/v1/config'
    headers = {
        'content-type': 'application/json',
        'Authorization': 'user_key <your user key>'
    }
    return requests.post(url, json=input, headers=headers).json()

print(vocConfig({
    'configId': '5fe0ae5efb1b79330d91f08ee1a9e9f6',
    'name': 'touchpoint_1', 'description': 'Some new description',
    'domain': 'voc-banking', 'language': 'en',
    'textColumns': [
        {'name': 'positive_text', 'type': 'PROS'},
        {'name': 'negative_text', 'type': 'CONS'},
        {'name': 'other_text', 'type': 'OTHER'}
    ],
    'metaColumns': [
        {'name': 'stars', 'type': 'NUM'}
    ]
}))