Get Reports Information

GET /reports

Enables the retrieval of report metadata based upon the query parameters given.

Each element in the data array is a report object which means that data.id is the report ID (not the survey ID).

Dates will be provided in ISO 8601 format. For example, 2012-02-13T01:34:52Z will be used instead of February 2, 2012 1:34:52a UTC. This can be parsed in Java using the SimpleDateFormat and this pattern "yyyy-MM-dd'T'HH:mm:ss'Z".
new java.text.SimpleDateFormat("yyyy-MM-dd'T'HH:mm:ss'Z").format(new Date());

Resource URL

https://api.ideasystem.org/v1/reports

Parameters (survey_id and survey_group_id are exclusive. If multiple were provided, only first one in the order will be used.)

page
optional
Default: 0
Example: /v1/reports?page=1
Used to retrieve more results. Can be incremented until the results returned are less than the max parameter. The first page is number 0.
max
optional
Default: 10
Example: /v1/reports?max=10
The max parameter can be used to limit how many results are returned. It is recommended that this value be set as low as possible given the client needs. The max allowable value is 100. If a value greater than 100 is specified, only 100 results will be returned.
survey_id
optional
 
Example: /v1/reports?survey_id=1234
Filters reports by specified survey ID (unique survey identifier in the IDEA system).
survey_group_id
optional
 
Example: /v1/reports?survey_group_id=1234
Filters reports by specified survey group ID (unique survey group identifier in the IDEA system).
type
optional
Default: ALL
Example: /v1/reports?type=Comment
Filters reports by specified type. Will return all types of reports by default. This can be one of the following: [ALL, Admin, Chair, Comment, Extra Likert, Diagnostic, Short, Teaching Essentials, Advisor, Advising Staff, Advising Student].
survey_year
optional
 
Example: /v1/reports?survey_year=2012
This is recommended to improve performance. If only a survey_id is provided, survey year can be looked up but will impact performance. If survey_year is provided without survey_id than all surveys for that year will be returned.

Response

The response to this will be an HTTP 200 status along with a JSON body. If an error occurs with the parameters, an HTTP 400 error will be returned along with an error message. The JSON body is a collection of report meta-data objects along with parameters to support paging (max, page, total_results).

Response Parameters (JSON Body)

max
Example: "max": 50
Shows the maximum number of responses.
page
Example: "page": 1
Shows the page number.
total_results
Example: "total_results": 143
Shows the total number of results that are provided by the given query.
data
Example: "data": { ... }
An array of report objects will be returned in this section. The size of this array should match the total_results.
data.id
Example: "id": 123
A unique report identifier in the IDEA system.
data.status
Example: "status": "available"
The status of the report generation. It will be one of the following values: [available, error, not ready].
data.status_message
Example: "status_message": "The report has not been generated. Please try again later."
A brief description of the status. When the status is error or not ready this will be very useful for users.
data.available_after
Example: "available_after": "2012-04-05T05:00:00Z"
A suggested time to try again. This is only relevant when the status is not ready. Otherwise, this can be ignored.
data.pdf_url
Example: "pdf_url": "https://api.ideasystem.org/v1/report/456/pdf"
The (absolute) URL to the PDF that makes up this report.
data.model_url
Example: "model_url": "https://api.ideasystem.org/v1/report/456/model"
The (absolute) URL to the report model that makes up this report.
data.type
Example: "type": "Diagnostic"
The type of report this is. It will be one of the following: [Admin, Chair, Comment, Extra Likert, Diagnostic, Short, Teaching Essentials, Advisor, Advising Staff, Advising Student].
data.survey_id
Example: "survey_id": 1234
A unique survey identifier in the IDEA system.
data.survey_group_id
Example: "surveyGroupId": 2345
A unique survey group identifier in the idea system.
data.creation_date
Example: "creation_date": "2012-04-05T05:00:00Z"
The date/time that this report was created.

Example

This request will get all reports that are associated with a survey group that has an ID of 1234.

Request

GET /v1/reports?survey_group_ID=1234

Response (as JSON)

HTTP 200
{
"max": 100,
"page": 0,
"total_results": 3,
"data": [
    {
        "id": 456,
        "status": "available",
        "status_message": "",
        "available_after": "",
        "pdf_url": "https://api.ideasystem.org/v1/report/456/pdf",
        "model_url": "https://api.ideasystem.org/v1/report/456/model",
        "type": "Admin",
        "survey_id": 123,
        "survey_group_id": 1234,
        "creation_date": "2012-04-05T05:00:00Z"
    },
    {
        "id": 457,
        "status": "error",
        "status_message": "An error occurred while generating the report; the IDEA Server was unreachable.",
        "available_after": "",
        "pdf_url": "https://api.ideasystem.org/v1/report/457/pdf",
        "model_url": "https://api.ideasystem.org/v1/report/457/model",
        "type": "Comment",
        "survey_id": 123,
        "survey_group_id": 1234,
        "creation_date": "2012-04-05T05:00:00Z"
    },
    {
        "id": 458,
        "status": "not ready",
        "status_message": "The report has not been generated, please try again later.",
        "available_after": "2012-04-06T05:00:00Z",
        "pdf_url": "https://api.ideasystem.org/v1/report/458/pdf",
        "model_url": "https://api.ideasystem.org/v1/report/458/model",
        "type": "Extra Likert",
        "survey_id": 123,
        "survey_group_id": 1234,
        "creation_date": "2012-04-05T05:00:00Z"
    }]
}