API extension (?parameter?) to allow 'labels' to be returned not just 'names'

What is the general goal of the feature?
To allow API users (e.g. those pulling KoBo data into Power BI) to be able to directly access the values by label (in the specified language) rather than by name.

This is a frequently-requested item with multiple forum posts. There are several workarounds listed (e.g. make forms public and do a join, make submissions public (!!!), use a separate connector, or export as csv etc.) but ideally it would be more intuitive for a user to just have a flag/parameter to be able to specify that they want labels to be returned with their data.

Some workarounds - e.g. connecting to csv format via API rather than JSON format - only work for forms without repeat groups, so need to make sure the repeat group use case is also catered for.

What are the most likely user stories for how and when this would be used by someone on your team?

Anyone connecting KoBo and Power BI - or connecting to the KoBo API for any reason.

Can you sketch out graphically how you think this should look/work in practice?
Flag on API call, similar to how users can specify format for Excel export via the UI.

NOTE it may just be that this exists somehow and itā€™s just that additional documentation in support site is required!

How useful would this feature be to other users or organizations?
Very

What can you contribute to making this feature a reality?
Testing support

Thanks a lot, here are some references:

Hello @nat ,
Might using Excel download with Label option (and language choice) a workaround?
Kind regards

But then you cannot query from an external software (excel power query , power Bi , tableauā€¦) we use this type of things more and more, rather than a "static " file that we need to download everytime we need a refresh

2 Likes

Unfortunately itā€™s not - need an automated integration process, as some of our dashboards get updated 6 times a day. The API is great for connecting to, just a few tweaks (such as the above) are needed to make it more usable in a streamlined manner :wink:

Cheers and many thanks @wroos and @iker.montes

1 Like

Hi @nat, thank you for the feature request. How would you suggest the response object look with the labels? Unfortunately labels arenā€™t unique, may be in multiple languages, contain invalid JSON characters, etc. and therefore cannot be used as keys in the JSON response.

1 Like

Thanks @Josh - yes agree some complexities with certain languages and non-uniqueness. Re multiple languages, I would just go with one (specified as a param) rather than trying to return all languages at the time.

Acknowledge what youā€™ve said above, and also that the labels can be verbose - an in-between step that would massively help would be to at least have a flag to include/exclude groups from the ā€˜nameā€™ key.
Could then have one API call to get the big list of name-label mappings for a form (by language), then use that data to map to the separate API call to get the submission data with names.

At the moment if Iā€™m trying to map the labels to the names returned in submissions I have to figure out complicated logic to split out the groups (several of my forms have complicated repeat groups going on).

Hope that makes sense and thanks a lot.

Dear @nat ,
You surely know that you can get a full list (per language) with SPSS Label export from Toolbox which seems usable for parsing.
Kind regards

Thanks @wroos, yes can get a manual list of names-labels via the UI also by just exporting the form itself. However thereā€™s still not a 1:1 match between the names list and the data returned in submissions API due to the groups being also included with names. A number of us are looking to get these details programmatically rather than manual file download via UI. Cheers!

Understood. Just thought that labels and variable names normally should be stable (after tested form design), so even transfering once might be sufficient - different to the dynamic data.
Have a comfortable week-end

1 Like

This in-between step (allowing user to specify whether or not groups appear in the API response) would also help with the situation below. @Josh should I log a separate Suggestion Box item for the groups/no groups flag do you think?

Hi @nat, you can log a separate suggestion for this. In a sense these are both about making the JSON API more flexible but it would be helpful to discover what flexibility is desired.

1 Like

Thanks, have logged!

2 Likes

Noting that the new-ish Synchronous Exports functionality sorts out a lot of these problems! Thanks!

Can configure the export to show the labels, and to ignore (or include) the groups. Can also include/exclude questions from the results - which is great when wanting to leave sensitive data out and have it not even come to PBI.

https://support.kobotoolbox.org/synchronous_exports.html

2 Likes