Retrieve Report Data

This recipe describes how to retrieve report data; report data being the aggregated and calculated responses. This is not the raw responses and not the report PDF. The overall process is as follows:

  1. GET /reports
  2. GET /report/:reportID/model
  3. GET /report/:reportID/model/:questionID
  4. GET /survey/:surveyID
  5. GET /forms/:formID/questions

GET /reports

The first step in the process of retrieving report data is to get the reports that you care about. You can use the GET /reports end-point to track down the report information you are interested in. For example, you might query for all reports associated with a survey by providing a survey_id. Or you might query for all reports associated with a group of surveys by providing a survey_group_id.

The returned JSON data will provide information about the requested reports, including a unique report identifier. The report ID (data[].id) can be used in subsequent calls to the IDEA REST API.


GET /report/:reportID/model

Using a report ID returned from the GET /reports call you can query for the report model. A report model provides the aggregated and calculated data associated with a single survey report. This model might contain a list of text responses (comment report) or calculated data (diagnostic report).

The returned JSON data provides meta data about the report (associated survey and report type) as well as summary report data (number of respondents asked to respond and number who responded). In addition, it will return a ID for each question (that can be used with a different REST end-point).


GET /report/:reportID/model/:questionID

Using a report_id and question_id (from the GET /report/:reportID/model call), the response data can be queried. This will provide the aggregated and calculated response data for that question on the specified report.

The returned JSON data contains the aggregated and calculated response data. This might be a list of textual answers (comment report) or a collection of calculated values (mean, standard deviation, etc.).


GET /survey/:surveyID

Using the survey_id that is returned from the GET /reports call, you can get the meta-data information about a particular survey instance.

The returned JSON data contains meta-data about this survey instance. This includes the survey subject information as well as the form information. If custom questions are used, they are included in the rater form.


GET /forms/:formID/questions

Get question data using the info_form.id and/or rater_form.id returned from the GET /survey/:surveyID call.

The returned JSON data contains question identifying information include the group and question number. It will also contain the question text and any response options.

Note: This information might be cached on the client side to avoid making this call. Questions on a form should not change often (if ever).