Welcome to the Je Leve La Main API !

Overview

The Je Leve La Main API (Application Programming Interface) is a web service that allows manipulating and computing statistics on Je Leve La Main data in your own applications.

You can interact with the API by sending HTTP requests in the language of your choice, or in an Object-oriented (and easier) way by using the JavaScript SDK (Software Development Kit).

The main purpose of Je Leve La Main API is to :

Retrieve sets of users matching some conditions (e.g. session attendees, user group members...),
Retrieve sets of quizzes matching some conditions (e.g. author, creation date...),
Compute the results of a set of users on a set of quizzes (e.g. number of good answers, percentile, ...) . Results may be detailed (results of each user) or aggregated (e.g. min, max or average grouped by quiz or user).

Since the data sets computed by the API may be very large, they are returned under the form of pages containing a limited number of items. It is possible to combine data sets of same nature (users, quizzes or results) by applying set operators such as union or intersection.

The API also allows you to insert data to your Je Leve La Main account, such as quizzes.

The documentation pages provide a detailed description of API requests, and include an interactive part that allows you to try them on live data.

Prerequisites

An API key is required to submit requests to the Je Leve La Main API from your web or server applications. The API key manager allows you to consult, add and delete API keys. You need to be logged in to use it; if not, click on the "Login" button at the right top of the page).

In addition, an access token may be required if your application manipulates private user data through the API. See the authentication section for details.

Example of use

The Je Leve La Main application includes a module drawing various charts related to session statistics. This module is an example of API client and has its own API key.

To illustrate how the chart module interacts with the API, let consider a session #71330434 with 30 attendees (a classroom) where 2 quizzes have been played.

In the chart module, a user asks to display the histogram of the average number of good answers and obtains the following result :

The data required to draw this histogram are retrieved by the chart module by sending 3 requests to the API :

Request #1: The chart module sends a getUserSet request to the API to retrieve the attendees of the session #71330434 :

GET https://api.jelevelamain.fr/getUserSet?sessionId=71330434&apiKey=API_KEY&accessToken=ACCESS_TOKEN

where API_KEY is the API key of the chart module and ACCESS_TOKEN the access token of the user that is logged in Je Leve La Main.

The API response is the first page of a user set identified by tLVJ87xTktKONNdG4TVw-g :

{
    "dataSetId" : "tLVJ87xTktKONNdG4TVw-g",
    "itemType" : "user",
    "numberOfPages" : 1,    
    "numberOfItemsPerPage" : 50,   
    "totalNumberOfItems" : 30,
    "items" : User[], 
    "currentPageIndex" : 1 
}

Request #2: The chart module sends a getQuizSet request to the API to retrieve the quizzes played in the session #71330434 :

GET https://api.jelevelamain.fr/getQuizSet?sessionId=71330434&apiKey=API_KEY&accessToken=ACCESS_TOKEN

The API response is the first page of a quiz set identified by vQc6eAvCbNClWxfUUbc0Tg :

{
    "dataSetId" : "vQc6eAvCbNClWxfUUbc0Tg",
    "itemType" : "quiz",
    "numberOfPages" : 1,    
    "numberOfItemsPerPage" : 50,   
    "totalNumberOfItems" : 2,
    "items" : Quiz[], 
    "currentPageIndex" : 1 
}

Request #3: The chart module sends a getResults request to the API to retrieve the average number of good answers of each user of the set tLVJ87xTktKONNdG4TVw-g on the quizzes of the set vQc6eAvCbNClWxfUUbc0Tg :

GET https://api.jelevelamain.fr/getResults?sessionId=71330434&userSetId=tLVJ87xTktKONNdG4TVw-g&quizSetId=vQc6eAvCbNClWxfUUbc0Tg&sessionIds=71330434&resultTypes=nbGoodAnswers&includeQuizzes=answered&aggregationFunctions=average&groupBy=user&apiKey=API_KEY&accessToken=ACCESS_TOKEN

{
    "dataSetId" : "DkkSL7fpfzqS-3dlosI66A",
    "itemType" : "computedResult",
    "numberOfPages" : 1,    
    "numberOfItemsPerPage" : 50,   
    "totalNumberOfItems" : 30,
    "items" : ComputedResult[], 
    "currentPageIndex" : 1 
}

Note that only 3 requests are required because each data set is entirely included in one page. For larger sets, the chart module must send getDataSetPage requests to retrieve all the items.