Skip to main content

LimeSurvey RC2 API Web Services Client

Project description

LimeSurvey RC2 API Web Services Client


This module provides a class which can be used as a client for interacting with LimeSurvey Remote Control 2 API.


From pip:

pip install limesurveyrc2api

or from GitHub, for example using the master branch:

pip install

Example Usage

The tests are a good place to refer to for api usage, until proper docs are written, anyway. Here is how to get a list of surveys.

from limesurveyrc2api.limesurvey import LimeSurvey

url = "http://localhost:443/limesurvey/index.php/admin/remotecontrol"
username = "admin"
password = "admin"

# Open a session.
api = LimeSurvey(url=url, username=username)

# Get a list of surveys the admin can see, and print their IDs.
result = api.survey.list_surveys()
for survey in result:

# Close the session.

Implemented Methods

It's just a start, so the list of implemented methods is shorter than not.

  • Sessions
    • get_session_key (
    • release_session_key (api.close)
  • Survey
    • list_surveys
    • list_questions
  • Token
    • add_participants
    • delete_participants
    • get_participant_properties
    • get_summary
    • invite_participants
    • list_participants

Error Handling

Where possible, error messages from the RC2API are translated into Python exceptions (specifically, a LimeSurveyError), with the caller method and error message included in the exception message plus any other relevant info.



# Get a copy of the repository.
mkdir -P ~/repos/limesurveyrc2api
cd ~/repos/limesurveyrc2api
git clone repo

# Create and activate a virtual environment for the install.
/usr/local/bin/python3.9 -m venv venv
source venv/bin/activate

# Install limesurveyrc2api, and it's development dependencies.
cd ~/repos/limesurveyrc2api/repo
pip install -e .
pip install -r dev_requirements.pip

# Leave the virtualenv.


Useful references for the RC2API:

Discovering Error Messages

If extending or maintaining this project, be aware that discovering error messages to raise an exception from is a relatively tedious process. It involves reading through the handler script, looking for lines like the following.

return array('status' => 'No permission');

Whether or not the message is an error depends on the context of the line and the message text. For example, some RC2API methods that delete objects return a message that looks like an error but indicate success, e.g. "status": "OK".

Running Tests

  • Copy tests/config.ini.tmpl to tests/config.ini and edit it with the details of a RC2API enabled LimeSurvey installation.
  • LimeSurvey instance setup steps:
    • Install LimeSurvey by following the manual instructions
    • Log in as admin, then go to Configuration -> Global Settings:
      • Enable the RC2API, under: Interfaces -> RPC interface enabled: JSON-RPC -> Save
      • Configure the test smtp host, under Email settings:
        • Email method: SMTP
        • SMTP host: localhost:10025
        • SMTP username, password: blank
        • Email batch size: 50
        • Save
    • Load at least 1 survey, by either:
      • Logging in as admin, then Surveys -> Create a new survey, then add groups and questions by hand
      • Logging in as admin, then Surveys -> Create a new survey, then import the .LSS file under tests/fixtures
      • Once the methods are implemented for it, create a survey programmatically
    • Activate the survey: Surveys -> SurveyName -> Activate this Survey
    • Initialise participants table: Survey -> SurveyName -> Survey Participants -> Initialise participants table
  • From the project root folder, run the tests either:
    • For minimal result info: python -m unittest
    • For more detailed info: python test

Test Problems

There is a PHP 5.6.0+ issue where the API response value includes a deprecation warning, which breaks the JSON response parsing. To deal with this, ensure that the following php.ini setting is set: always_populate_raw_post_data = -1.

Intellij Setup

Project setup for IDEA requires defining a "project SDK", under File -> Project Structure -> Project. Since this is a Python project, the SDK is the interpreter you want to use, which could (should) be a virtual environment interpreter.

Since the SDK setting is user specific, it'll need to be created the first time you load up this project. This should create an entry under Platform Settings -> Global Libraries; and a file /.idea/misc.xml, containing the name of the global library (SDK) selected for this project.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

limesurveyrc2api-2.0.0.tar.gz (9.8 kB view hashes)

Uploaded source

Built Distribution

limesurveyrc2api-2.0.0-py3-none-any.whl (9.2 kB view hashes)

Uploaded py3

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring Fastly Fastly CDN Google Google Object Storage and Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page