Get question API

Given a questionID how can I retrieve details of a question?

When you say ‘details’, do you mean the definition (question title, type, options etc) or the answers to it?

If the first, you would need to get and parse the questionnaire document - a json structure that is available either as api/v1/questionnaires/[id]/[version]/document or as part of the export archive (look for document.json in the downloaded zip).

Unfortunately the document structure is not yet documented (we’re working on that) so you’d have to do ‘little bit of guessing’. If you’re in python world, ssaw has some useful parts already covered. For example, you can get a questionnaire object by:

from ssaw.models import Group, QuestionnaireDocument
from ssaw.utils import get_properties
# this is somewhat technical detail that needs to be here for now. 
# Resolves issue of circular reference that Group class may contain 
# instances of the same Group 

# Depending whether you have the contents of the questionnaire
# already read into a text or in a file, you can call one of the following:
# if document variable contains the questionnaire in text format
q = QuestionnaireDocument.parse_obj(document)
# or if you have the document.json file saved then
q = QuestionnaireDocument.parse_file(path_to_file)

# show questionnaire variable name and title
print(q.variable_name, q.title)

# at this moment q contains questionaire objects in the same tree structure,
# i.e. q.children[1] refers to to the second section, 
# q.children[1].children[3].title shows forth element's title etc

# get_properties() instead returns a dictionary of variable_name: obj pairs
flat_list = get_properties(q)

# so now you can get the details of a specific question based on its variable name:
print(flat_list["gender"].is_filtered_combobox) # returns True/False
print(flat_list["countries"].answers) # answer values for categorical question

Users who work in R may have similar parsers written also so they may chime in as well.

My {susopara} package does something similar: parse_questionnaire() ingests the JSON file and transforms it into a rectangular data file. If you know what the columns mean–they are carried over from JSON names and the source code comments provide some limited documentation–you can fetch what you need. As I have practical needs, I’m trying to build out accessor functions. For the moment, I only have extract_answer_options() to extract the answer options a target question–in my use, typically multi-select questions whose labels get “lost” in export.

For the readers of this thread: Survey Solutions doesn’t loose the labels on it’s own because of some defect, but rather truncates them to fit into the limitations of the export format to which it exports the data. For example, the format of Stata data files allows the variable labels to occupy up to 80 characters:

SPSS file could be even more restrictive as it is limited to 120 bytes (or approximately 60 characters given 2-byte characters).

Survey Solutions automatically issues a warning (to the questionnaire designer) that a variable label will be truncated so that he/she is aware of the situation and can make corrections. I believe the warning code is 217.

Typically the correction would be to introduce the proper variable label, which is shorter than the question text. For example:

Question text: “Which meat items have you or anyone in your household consumed within the recall period (from September 01, 2021 to September 07, 2021)? Include the items that you’ve purchased or that were given to you for free.”

Question options:
1. Pork
2. Beef
3. Rabbit
4. Chicken
5. Other

The concatenated version of the question text and the value label would be too large to fit into the 80 characters limit. But we can introduce the variable label “Meat items consumed” and the corresponding column labels will then be:

- Meat items consumed: Pork
- Meat items consumed: Beef

which is satisfactory.

We have intentionally didn’t make this an error, but kept as a warning, because in principle, having the PDF document of the questionnaire makes the data decipherable even in the case where the labels are truncated. But clearly, it is best to adhere to the warning and resolve the situation still during the design of the questionnaire. Regardless of the warning, export the data using the questionnaire you’re designing and see whether the meta-information coming out of the questionnaire is looking good from the analyst point of view.

Hope this helps, Sergiy

Sorry for the confusing, loose language. Indeed, the labels are not “lost”.

Thanks for the tip about using short variable labels for mutli-select questions. This is a good practice, beyond its benefits for “recoverability” of value labels for answer options in Designer.

Are there any export files that contain the labels that have not been truncated? I know that the JSON representation contains them. I am curious if they can be found elsewhere too.

Let’s assume that users, like me, fail to specify variable labels in Designer. :wink: