caplena_api_demo module¶

Demo script illustrating how to do basic operations on the Caplena API

Example

Steps to run:

Make sure you have a compatible (version >= 2.7) python environment
$ python –version
Make sure you have installed the requests library (if not, install using pip install requests)
$ pip install requests
Set the CAPLENA_API_KEY variable at the bottom of this script
Call the script
$ python caplena_api_demo.py

Notes

This script is not intended to be shared with third parties. Every receiving party agrees to use it solely for own purposes and purposes that are intended by the original author (Caplena GmbH).

class caplena_api_demo.CaplenaAPI(language, api_key)[source]¶

Bases: object

Class enabling interaction with (parts of) the Caplena.co API

Example

To call an API instantiate a CaplenaAPI object and then call its methods

>>> api = CaplenaAPI('de', '$(API_KEY)')
>>> api.listProjects()
[{"name": "project 1",
 "questions": [{"name": "question A"}, ...]},
 "rows": [{"answers": [{...}, ...], "auxiliary_columns": [...]}]
]

valid_languages = ['en', 'de']¶

listProjects()[source]¶

API method to list all projects that belong to this user.

List all projects of the user.

Note: The returned projects contain global meta information of the projects and their questions, but not the response texts.

Returns: projects – A list of all projects belonging to the user
Return type: list(Project)

listInheritableProjects()[source]¶

API method to list all projects of which inheritance is possible.

List contains all projects belonging to user, as well as Caplena provided models.

Note: The returned projects only contain basic meta information on the project and their questions, but not the response texts. To get more detailed information about a certain project call the listprojects method.

Returns: projects – A list of all projects that can be used for inheritance. This is the concatenation of all projects owned by the user and global Caplena models.
Return type: list(Project)

listQuestions()[source]¶

API method to list all questions that belong to this user.

List all questions of the user.

Note: The returned questions only contain global meta information of the questions and not the response texts.

Returns: questions – A list of all questions belonging to the user if the call was successful, False otherwise
Return type: list(Question)

getQuestion(question_id)[source]¶

API method to get question info.

Get question by ID.

Note: The returned questions only contain meta information of the question and not the response texts.

Returns: question – A question object
Return type: Question

getProject(project_id)[source]¶

API method to get project info.

Get project by ID.

Note: The returned questions only contain meta information of the question and not the response texts.

Returns: project – A project object
Return type: Project

createProject(name, language, translate=False, auxiliary_column_names=[], questions=[], rows=[], translation_engine='GT', upload_async=True, request_training=True)[source]¶

API method to create a new project

Note: * When creating a new project you can also create questions and rows belonging to it. * Creating new questions is _only_ possible when creating a new project. Questions cannot be added to an existing project. * Rows can also be added to a project at a later time

Parameters

name (str, required) – Name of the new project
language (str, required) – Language of the project, valid choices are {en|de} Has nothing to do with the language the API is set to (the attribute language.)
translate (bool, optional) – Flag indicating whether to translate this project (where other language than language detected) using the Google API.
auxiliary_column_names (list, optional) – List of strings, naming additional columns that will be sent with each row. Can also be an empty list. The number of elements in this list must match the number of elements in the auxiliary_columns field when adding rows.
questions (list(Question)) – List of questions to create
rows (list(Row)) – List of objects of type Row
async (bool) – If true, send async request, required if uploading more than 20 rows at once or if uploading answers with reviewed=True
request_training (bool) – If true, automatically request training after uploading answers
translation_engine (str) – Choice of translation engine, either ‘GT’ for Google Translate or ‘DL’ for DeepL

Returns

project – A new Project object

Return type

Project

addRowsToProject(project_id, rows, upload_async=True, request_training=True)[source]¶

API method to add rows to a previously created project.

Parameters

project_id (int) – ID of the project to add the rows to
rows (list(Row)) – List of objects of type Row
async (bool) – If true, send async request, required if uploading more than 20 rows at once or if uploading answers with reviewed=True
request_training (bool) – If true, automatically request training after uploading answers

Returns

rows – A list of the newly created rows

Return type

list(Row)

listRows(project_id)[source]¶

API method to list all rows of a specific project.

Parameters: project_id (int) – ID of the project of which to return the rows
Returns: answers – A list of all rows belonging to the question
Return type: list(Row)

listAnswers(question_id, no_group=False)[source]¶

API method to list all answers of a specific question.

Parameters

question_id (int) – ID of the question of which to return the answers
no_group (bool) – If true, no grouping will be applied to answers list, overriding the group_identical property of the question

Returns

answers – A list of all answers belonging to the question

Return type

list(Answer)

requestPredictions(question_id, **kwargs)[source]¶

API method to request the AI-assistant to train itself based on coded answers of specified question. Only works if at least 6 answers have been coded.

Parameters: question_id (int) – ID of the question of which to request AI to make predictions
Returns: success – True if request successful, False otherwise
Return type: bool

getPredictions(question_id)[source]¶

API method to get AI-coded codes and respective answers. Requires previous call to requestPredictions().

Parameters: question_id (int) – ID of the question of which to return the code predictions made by AI
Returns: result – None if no predictions are available (response code 204) Otherwise contains keys answers (with itself has keys id and codes) which are the predictions, model (meta information on model performance)
Return type: Predictions|None

deleteQuestion(question_id)[source]¶

API method to delete question and its answers.

Parameters: question_id (int) – ID of the question to delete
Returns: success – True if request successful, False otherwise
Return type: bool

deleteProject(project_id)[source]¶

API method to delete projects, its questions and corresponding answers.

Parameters: project_id (int) – ID of the project to delete
Returns: success – True if request successful, False otherwise
Return type: bool

updateQuestion(question, request_training=False)[source]¶

API method to update question

Parameters: question (question) – modified question instance
Returns: question – newly updated question instance
Return type: Question

updateAnswers(answers, question, request_training=False)[source]¶

API method to update question

Parameters: question (question) – modified question instance
Returns: question – newly updated question instance
Return type: Question

class caplena_api_demo.Code(id, label, category, **kwargs)[source]¶

Bases: src.utils.CaplenaObj

Code object

id¶

Code ID

Type: int, required

label¶

Code name

Type: str, required

category¶

Code category

Type: str, required

classmethod from_json(json_data)[source]¶

class caplena_api_demo.Question(name, description='', codebook=[], group_identical=True, group_identical_exclude='', smart_sort=False, inherits_from=None, id=None, question_category='NO', **kwargs)[source]¶

Bases: src.utils.CaplenaObj

Question object

name¶

Name of the question.

Type: str, required

description¶

String describing this question

Type: str, optional

group_identical¶

Flag indicating whether to group identical answers in coding view and when listing answers. Default=true

Type: bool, optional

group_identical_exclude¶

All answer texts matching this regular expression won’t be grouped. Default=’’

Type: str, optional

smart_sort¶

If the smart sorting feature should be enabled. Default=true

Type: bool, optional

codebook¶

List of codes (dictionaries), each containing the keys id, label and category Can also be an empty list.

Type: list(Code), optional

inherits_from¶

ID of another question of this user, that the model should be based on. The codebook of that question should be identical or almost identical in order for the AI to deliver good results.

Type: int, optional

classmethod from_json(json_data)[source]¶

class caplena_api_demo.Answer(text, question, source_language='', reviewed=False, codes=[], id=None, **kwargs)[source]¶

Bases: src.utils.CaplenaObj

Answer object

text¶

Text of the answer.

Type: str, required

question¶

The name of the question this answer belongs to

Type: str, required

reviewed¶

Answers having the “reviewed” are assumed to have all codes correct and will be used to train the AI.

Type: bool, optional

codes¶

List of integers (code IDs). Assigning codes to an answer. Will be used to train the AI.

Type: list(int), optional

source_language¶

ISO Code (2 characters, e.g. ‘de’ or ‘en’) specifying in which language the text is written. Relevant for translation, taking precedance over automatic language detection

Type: str, optional

classmethod from_json(json_data)[source]¶

class caplena_api_demo.Row(auxiliary_columns, answers, **kwargs)[source]¶

Bases: src.utils.CaplenaObj

Row object

auxiliary_columns¶

Needs to have the same number of elemenst as the auxiliary_column_names field of the project it belongs to

Type: list(str), required

answers¶

A list of answers, whereby exactly one answer needs to be provided for every question of the project it belongs to

Type: list(Answer), required

classmethod from_json(json_data)[source]¶

class caplena_api_demo.Project(name, language, questions, rows=[], auxiliary_column_names=[], translation_engine='google', translate=False, translated=0, id=None, **kwargs)[source]¶

Bases: src.utils.CaplenaObj

Project object

name¶

Name of the project.

Type: str, required

language¶

Language of question, must be iso tag

Type: str, required

questions¶

Questions belonging to the project

Type: list(Questions), required

auxiliary_column_names¶

Names of the auxiliary columns

Type: list(str), optional

translation_engine¶

Which translation engine to use, can be either google or `deepl

Type: str, optional

translate¶

If true translate answers using translation_engine

Type: bool, optional

inherits_from¶

ID of another question of this user, that the model should be based on. The codebook of that question should be identical or almost identical in order for the AI to deliver good results.

Type: int, optional

to_dict()[source]¶

classmethod from_json(json_data)[source]¶

class caplena_api_demo.Predictions(answers, model, **kwargs)[source]¶

Bases: src.utils.CaplenaObj

answerslist(Answer), required: A list of answers, whereby exactly one answer needs to be provided for every question of the project it belongs to
modeldict, required: Meta information about the model

classmethod from_json(json_data)[source]¶

Previous topic

This Page

caplena_api_demo module¶