I’ve been working on integrating KoboToolbox into a Python-based workflow and have encountered some difficulties due to limited and somewhat unclear documentation regarding API compatibility—particularly in relation to ODK standards.
Specifically, I attempted to use the PyODK library, which is designed for interacting with ODK Central, but I was unable to establish a successful connection with KoboToolbox. It’s not entirely clear to me whether KoboToolbox is partially or fully compatible with ODK’s APIs (such as OData, OpenRosa, or Central’s REST endpoints), or if an entirely different approach is needed.
Could anyone clarify the following?
Is KoboToolbox currently compatible with PyODK, either fully or partially?
Are there any plans to support PyODK in the future?
Is there a recommended Python library or SDK for interacting with KoboToolbox APIs?
Are there examples or best practices available for programmatically interacting with submissions, forms, and attachments using Python?
I appreciate any guidance or suggestions the community can offer. Thank you in advance for your support and for the excellent work behind KoboToolbox.
pyODK is a Python-based API client for ODK Central that’s used to automate form management, data analysis, and more. This release adds the most requested feature, support for Entities!
This is the key piece here The README for pyODK gets a little more specific, with a hyperlink: “An API client for the ODK Central API.” The ODK Central API is not an open standard in the sense that OpenRosa Protocol and the ODK XForms Specification are. Instead, it’s a REST HTTP API for a product (ODK Central) that implements some of those standards, and in doing so, provides an alternative to KoboToolbox.
There’s a lot of confusion around the name “ODK”, which originally abbreviated Open Data Kit, an academic project and suite of open-source software that began around 2010 at the University of Washington. The ODK “ecosystem” encompasses many tools that interoperate to varying degrees using OpenRosa and ODK XForms standards. You’re likely familiar with Enketo and ODK Collect: these tools can communicate with any server that implements OpenRosa and, using the ODK XForms format, retrieve blank forms and upload submissions.
“ODK” today is often used synonymously with Get ODK Inc., a comparatively young organization that builds ODK Central and sells it as a product. Get ODK Inc. is a great group of folks that includes one of the original authors of the Open Data Kit paper (full text here). They also generously host and maintain much of the documentation and shared tools around the OpenDataKit standards, as you can see from my links above. (To add to the confusion, there’s also an ODK-X, but I won’t describe it here. You can refer to https://opendatakit.org/ if you’re curious.)
Prior to Get ODK Inc., the shared “ecosystem” tools and specifications were governed by the Technical Steering Committee, which was then changed into the Technical Advisory Board:
The Technical Advisory Board (TAB) represents the broader ODK community. It reviews and gives feedback on major roadmap decisions, new designs, specifications, features, and protocol changes.
The TAB was formerly the Technical Steering Committee (TSC). When Get ODK Inc. was created, the TAB agreed to become an advisory body to the new entity and change its name.
The TAB, in turn, was wound down in early 2024 and subsequently removed from the stated governance of Get ODK Inc. Its replacement is the ODK Insiders program.
Perhaps some of these answers are self-evident (or maybe not!), but to be clear:
The answer to both is no. PyODK is for the ODK Central REST API, not the API specified by the OpenRosa protocol.
There’s nothing official for this yet, and I’m not aware of one that does more than retrieve data.
Most third-party use of the API so far has been to download submission data. Uploading submissions and manipulating forms are less common use cases, and they do not yet have the documentation and examples that I would like. However, you could look at the kobo-transfer project as an example of how to read almost everything related to a Kobo project from the API and write it back again. Specifically, for uploading submissions that include attachments, you could refer to kobo-transfer/transfer/xml.py at 15377a38f8190d0e4287abc62f9ac80bb094c997 · kobotoolbox/kobo-transfer · GitHub.
Thanks for using KoboToolbox. Best of luck with your work!
kobo-transfer covers both reading and writing via API. This is exactly what you need! The only thing - I’m not quite sure how to properly generate XML for attachments. Has anyone already tried this via Python directly?
The 