Citric¶

A client to the LimeSurvey Remote Control API 2, written in modern Python.

Release v3.0.0. (What’s new?)

Features¶

Supports the full RPC API via the Session class.
Best effort to implement all the RPC methods in the Client class. See the API coverage page for details.
Easily export survey data to CSV files, Pandas DataFrames and DuckDB databases.
Easily download survey files (e.g. images, audio, etc.) to a local directory.
Tested against LimeSurvey versions 6 and 7.
Experimental support for the new REST API.

Installation¶

From PyPI:

# using pip
pip install citric

# using uv
uv add citric

or from conda-forge:

# using conda
conda install -c conda-forge citric

# using pixi
pixi add citric

Usage¶

from citric import Client

# Connect to your LimeSurvey instance
client = Client(
    "https://mylimesite.limequery.com/admin/remotecontrol",
    "myusername",
    "mypassword",
)

# Print the LimeSurvey version
print(client.get_server_version())

# Print every survey's title
for survey in client.list_surveys():
    print(survey["surveyls_title"])

Prerequisites¶

Python 3.11+
A LimeSurvey server with JSON RPC enabled (typically can be done at /admin/globalsettings#interfaces)
A LimeSurvey username and password

Supported versions¶

The latest 6.x and 7.x are tested continuously and are expected to work. Integration tests are run against a LimeSurvey instance, and both PostgreSQL and MySQL backends, using Docker Compose.