# Results

Evalytics uses a couple of generic result-endpoints with which all results can be retrieved (assuming the user has permission to a specific result). By setting the context, a combination of `type`, `id`, `comparisonType` and optionally a `comparisonId`, the desired results can be retrieved.

## Averages

<mark style="color:blue;">`GET`</mark> `https://api-portal.evalytics.nl/result/averages`

Returns a list of total averages within the given context (e.g. an evaluation).

#### Query Parameters

| Name                      | Type    | Description                                                                                                                                                                                                                                        |
| ------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| element                   | array   | <p>Determines which results the API will return.<br><br>Possible values:<br><code>totalAverage, subjectAverage, teacherAverage, examAverage, genericAverage</code></p>                                                                             |
| type                      | string  | <p>Context in which results are being searched.<br><br>Possible values:<code>organisation, evaluation, teacher, subject</code></p>                                                                                                                 |
| id                        | integer | Use in combination with `type` to retrieve results from within specific context. E.g. if `type` if set to `evaluation`, given `id` must be an evaluation id.                                                                                       |
| comparisonType            | string  | <p>Further defines the context. E.g. if an evaluation has multiple teachers, this can be used to get results for a specific teacher within that evaluation.<br><br>Possible values:<br><code>organisation, evaluation, teacher, subject</code></p> |
| comparisonId              | integer | Use in combination with `comparisonType` to retrieve results within the sub context.                                                                                                                                                               |
| startDate                 | string  | Uses the format `YYYY-MM-DD`                                                                                                                                                                                                                       |
| endDate                   | string  | Uses the format `YYYY-MM-DD`                                                                                                                                                                                                                       |
| includeChildOrganisations | boolean | By default only results for the organisation present in the `accessToken` are retrieved. By setting this to `true`, results for child organisations will also be returned if available.                                                            |

{% tabs %}
{% tab title="200 " %}

```scheme
{
  "name": string,
  "averages": [
    {
      "type": string,
      "average": number
    }
  ]
}
```

{% endtab %}
{% endtabs %}

## Average history

<mark style="color:blue;">`GET`</mark> `https://api-portal.evalytics.nl/result/averageHistory`

Returns a list of averages per quarter, per type, within the given context. Note that this only works if the context supports history, i.e. not for evaluations.

#### Query Parameters

| Name                      | Type    | Description                                                                                                                                                                                                                            |
| ------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| element                   | string  | <p>Determines which results the API will return.<br><br>Possible values:<br><code>totalAverage, subjectAverage, teacherAverage, examAverage, genericAverage</code></p>                                                                 |
| type                      | string  | <p>Context in which results are being searched.<br><br>Possible values:<code>organisation, subject, teacher</code></p>                                                                                                                 |
| id                        | integer | Use in combination with `type` to retrieve results from within specific context. E.g. if `type` if set to `evaluation`, given `id` must be an evaluation id.                                                                           |
| comparisonType            | string  | <p>Further defines the context. E.g. if an evaluation has multiple teachers, this can be used to get results for a specific teacher within that evaluation.<br><br>Possible values:<br><code>organisation, teacher, subject</code></p> |
| comparisonId              | integer | Use in combination with `comparisonType` to retrieve results within the sub context.                                                                                                                                                   |
| startDate                 | string  | Uses the format `YYYY-MM-DD`                                                                                                                                                                                                           |
| endDate                   | string  | Uses the format `YYYY-MM-DD`                                                                                                                                                                                                           |
| includeChildOrganisations | boolean | By default only results for the organisation present in the `accessToken` are retrieved. By setting this to `true`, results for child organisations will also be returned if available.                                                |

{% tabs %}
{% tab title="200 " %}

```scheme
[
  {
    "type": string,
    "history": [
      {
        "average": number,
        "quarter": integer,
        "year": integer
      }
    ]
  }
]
```

{% endtab %}
{% endtabs %}

## List

<mark style="color:blue;">`GET`</mark> `https://api-portal.evalytics.nl/result/list`

Returns a list of items with their average results for the given context (e.g. a list of evaluations for an organisation).

#### Query Parameters

| Name                                             | Type    | Description                                                                                                                                                                                                                                        |
| ------------------------------------------------ | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| element                                          | array   | <p>Determines which results the API will return.<br><br>Possible values:<br><code>totalAverage, subjectAverage, teacherAverage, examAverage, genericAverage</code></p>                                                                             |
| type<mark style="color:red;">\*</mark>           | string  | <p>Context in which results are being searched.<br><br>Possible values:<code>organisation, evaluation, teacher, subject</code></p>                                                                                                                 |
| id                                               | integer | Use in combination with `type` to retrieve results from within specific context. E.g. if `type` if set to `evaluation`, given `id` must be an evaluation id.                                                                                       |
| comparisonType<mark style="color:red;">\*</mark> | string  | <p>Further defines the context. E.g. if an evaluation has multiple teachers, this can be used to get results for a specific teacher within that evaluation.<br><br>Possible values:<br><code>organisation, evaluation, teacher, subject</code></p> |
| comparisonId                                     | integer | Use in combination with `comparisonType` to retrieve results within the sub context.                                                                                                                                                               |
| startDate                                        | string  | Uses the format `YYYY-MM-DD`                                                                                                                                                                                                                       |
| endDate                                          | string  | Uses the format `YYYY-MM-DD`                                                                                                                                                                                                                       |
| searchQuery                                      | string  |                                                                                                                                                                                                                                                    |
| includeChildOrganisations                        | boolean | By default only results for the organisation present in the `accessToken` are retrieved. By setting this to `true`, results for child organisations will also be returned if available.                                                            |
| skip                                             | integer | Defaults to `0`                                                                                                                                                                                                                                    |
| limit                                            | integer | Defaults to `30`                                                                                                                                                                                                                                   |
| orderBy                                          | string  | <p>Possible values:<br><code>name ASC, name DESC, totalAverage ASC, totalAverage DESC, subjectAverage ASC, subjectAverage DESC, teacherAverage ASC, teacherAverage DESC, examAverage ASC, examAverage DESC, enddate ASC, enddate DESC</code></p>   |

{% tabs %}
{% tab title="200 Note that the response can have minor differences depending on the context. E.g. if the context is a teacher, only a teacherAverage will be present." %}

```scheme
{
  "metadata": {
    "resultSet": {
      "count": integer,
      "limit": integer,
      "skip": integer
    }
  },
  "results": [
    {
      "id": integer,
      "name": string,
      "code": string,
      "evaluations": integer,
      "totalAverage": number,
      "teacherPersonalAverage": number,
      "examAverage": number,
      "teacherAverage": number,
      "subjectAverage": number,
      "response": integer,
      "expectedResponse": integer
    }
  ]
}
```

{% endtab %}
{% endtabs %}

## Questions

<mark style="color:blue;">`GET`</mark> `https://api-portal.evalytics.nl/result/questions`

Returns a list of questions  with their average results for the given context (e.g. a list of questions for a specific evaluation).

#### Query Parameters

| Name                                   | Type    | Description                                                                                                                                                                                                                                        |
| -------------------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| element                                | array   | <p>Determines which results the API will return.<br><br>Possible values:<br><code>subjectQuestions, teacherQuestions, examQuestions, genericQuestions</code></p>                                                                                   |
| type<mark style="color:red;">\*</mark> | string  | <p>Context in which results are being searched.<br><br>Possible values:<code>organisation, evaluation, teacher, subject</code></p>                                                                                                                 |
| id                                     | integer | Use in combination with `type` to retrieve results from within specific context. E.g. if `type` if set to `evaluation`, given `id` must be an evaluation id.                                                                                       |
| comparisonType                         | string  | <p>Further defines the context. E.g. if an evaluation has multiple teachers, this can be used to get results for a specific teacher within that evaluation.<br><br>Possible values:<br><code>organisation, evaluation, teacher, subject</code></p> |
| comparisonId                           | integer | Use in combination with `comparisonType` to retrieve results within the sub context.                                                                                                                                                               |
| startDate                              | string  | Uses the format `YYYY-MM-DD`                                                                                                                                                                                                                       |
| endDate                                | string  | Uses the format `YYYY-MM-DD`                                                                                                                                                                                                                       |
| includedInAverage                      | boolean | By default all question results are retrieved. By setting this to `true`, only questions that count towards global averages will be returned.                                                                                                      |
| includeChildOrganisations              | boolean | By default only results for the organisation present in the `accessToken` are retrieved. By setting this to `true`, results for child organisations will also be returned if available.                                                            |
| orderBy                                | string  | <p>Possible values:<br><code>question ASC, question DESC</code></p>                                                                                                                                                                                |

{% tabs %}
{% tab title="200 " %}

```scheme
{
  "questionGroups": [
    {
      "name": string,
      "questions": [
        {
          "typeId": integer,
          "hash": string,
          "code": string
          "type": integer,
          "topicType": integer,
          "questionType": integer,
          "isIncludedInAverage": boolean,
          "response": integer,
          "scale": {
            "name": string,
            "scale": object,
            "input": string
          },
          "question": string,
          "average": number,
          "deviation": number
        }
      ]
    }
  ],
  "hasLabels": boolean
}
```

{% endtab %}
{% endtabs %}

## Question

<mark style="color:blue;">`GET`</mark> `https://api-portal.evalytics.nl/result/question/:hash`

Returns a single question with it's average result and result distribution for the given context (e.g. a single topic question).

#### Path Parameters

| Name | Type   | Description         |
| ---- | ------ | ------------------- |
| hash | string | The question's hash |

#### Query Parameters

| Name                      | Type    | Description                                                                                                                                                                                                                                        |
| ------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| type                      | string  | <p>Context in which results are being searched.<br><br>Possible values:<code>organisation, evaluation, teacher, subject</code></p>                                                                                                                 |
| id                        | integer | Use in combination with `type` to retrieve results from within specific context. E.g. if `type` if set to `evaluation`, given `id` must be an evaluation id.                                                                                       |
| comparisonType            | string  | <p>Further defines the context. E.g. if an evaluation has multiple teachers, this can be used to get results for a specific teacher within that evaluation.<br><br>Possible values:<br><code>organisation, evaluation, teacher, subject</code></p> |
| comparisonId              | integer | Use in combination with `comparisonType` to retrieve results within the sub context.                                                                                                                                                               |
| startDate                 | string  | Uses the format `YYYY-MM-DD`                                                                                                                                                                                                                       |
| endDate                   | string  | Uses the format `YYYY-MM-DD`                                                                                                                                                                                                                       |
| includeChildOrganisations | boolean | By default only results for the organisation present in the `accessToken` are retrieved. By setting this to `true`, results for child organisations will also be returned if available.                                                            |

{% tabs %}
{% tab title="200 " %}

```scheme
{
  "typeId": integer,
  "hash": string,
  "code": string,
  "type": integer,
  "topicType": integer,
  "response": integer,
  "scale": {
    "name": string,
    "scale": object,
    "input": string
  },
  "question": string,
  "scoreDistribution": object,
  "average": number,
  "deviation": number,
  "averageIndex": integer,
  "explanations": array
}
```

{% endtab %}
{% endtabs %}