Get Aggregate Oral Reading Measures for Students

Use this to calculate the aggregate Lexile oral reading measure for the aggregate of performances.

Overview

You can use this to get a Lexile oral reading measure that is an aggregate measure based on multiple performances by a student during a single testing event. There are two ways to get an aggregate measure.
  1. Send a list of performanceIDs that you received as a response using the Get Oral Reading Measures for Students call.
  2. Send student performance data from one or more performances and a Lexile oral readability measure for the text associated with each performance to receive an aggregate Lexile oral reading measure.

Use the inputType parameter to indicate which you are trying to use and make sure you pass the correct parameters for the inputType you selected.

URI

reader/performance/ability/aggregate

Parameters

You can include these parameters in your request. If you're making a request with the performanceID inputType, you will need to pass performance ids received from a Get Oral Reading Measures for Students call. If you're making a request with the characteristics inputType, you will not need to pass performanceId but will need to use the parameters in the Table 3 table.

Table 1. General Required Parameters
Parameter Format Description
Authorization String Your access token should be included in the header of your request. If you need an accessToken, use Retrieve an Auth Token to generate it.

This needs to have the structure "Bearer {accessToken}"

inputType String Indicates the type of information being sent with the request. Can be:
  • characteristics: Use this when you want to pass characteristics of an audio performance, like wcpm, to get a measurement.
  • performanceIds: Use this if you want to pass performanceIds received using the Get Oral Reading Measures for Students call the to get a measurement.
annotatePerformances Boolean This indicates whether you want to get an Lexile oral reading measure for each performance or want to receive a single aggregate measurement.

Values you can pass are:

  • True: An annotations object that contains a measurement for each performance will be returned in addition to an aggregate measurement for all performances.
  • False: The call will only return an aggregate measurement for all performances.
A request when you're using the performanceIds inputType might look like:
text_file = requests.get(
    "https://s3.amazonaws.com/mmincstatic/oralreadingexamples/example.txt"
).content
audio_file = requests.get(
    "https://s3.amazonaws.com/mmincstatic/oralreadingexamples/example.wav"
).content

body = {"textFile": text_file, "audioFile": audio_file}
response = requests.post(
    (
        "https://oralreading-analyzer.lexile.com/reader/performance/ability"
        "?inputType=audio"
    ),
    files=body,
    headers={"Authorization": f"Bearer {access_token}"},
)

performance_id = response.json()["performanceId"]

 Post to aggregate endpoint with list of performance IDS
body = {"performanceIds": [performance_id, performance_id, performance_id]}
response = requests.post(
    (
        "https://oralreading-analyzer.lexile.com/reader/performance/ability/aggregate"
        "?inputType=performanceIds"
    ),
    json=body,
    headers={"Authorization": f"Bearer {access_token}"},
)

A performanceIds inputType request includes these parameters:

Table 2. PerformanceID Parameters
Parameter Format Description
performanceID Integer A list of the identifiers assigned to a single audio and text pair.
A request when you're using the characteristics inputType might look like:
body = {
    "performanceCharacteristics": [
        {
            "oral_reading_difficulty": {"measure": {"value": 100}},
            "wcpm": 120,
            "accuracy": 0.75,
        },
        {
            "oral_reading_difficulty": {"measure": {"value": 100}},
            "wcpm": 120,
            "accuracy": 0.75,
        },
    ]
}
response = requests.post(
    (
        "https://oralreading-analyzer.lexile.com/reader/performance/ability/aggregate"
        "?inputType=characteristics"
    ),
    json=body,
    headers={"Authorization": f"Bearer {access_token}"},
)

A characteristics inputType request includes these parameters:

Table 3. Characteristics Parameters
Parameter Format Description
wcpm Number Words correct per minute.

Example: 160

accuracy Number The accuracy of words spoken compared to the text. This will be a number between zero and one.

Example: 0.9

oralReadingDifficulty Object This the Lexile® oral readability measure for a text. It contains:
  • measure:
    • value: The Lexile measure for the text rounded to the nearest 10L.
    • display: The measure to be used when reporting a Lexile oral readability measure for a text.
When relevant, this can also include displayName. This is the name used for the measurement.

Responses

If annotateMeasurement is true, the response will contain an annotation object and an aggregate object. What your receive in the response for each object will depend on the inputType used. Please refer to the table that matches your inputType.
Note: Some of the parameters listed might not be included in the response when annotateMeasurement is false.
A performanceIds inputType response will look like:
{
    "annotations":"None",
       "oralReadingAbility":{
          "measure":{
             "value":-1840,
             "uncertainty":193,
             "display":"BR1840L"
          },
          "displayName":"Lexile Oral Reading Measure"
       }
    },
    "feedback": {
        "behaviors": {
            "APPROPRIATE_RATE": 0.75,
            "TOO_SLOW": 0.01,
            "TOO_FAST": 0.62,
            "VARIED_RATE": 0.08,
            "NON_SIGHT_CORRECT": 1.0,
            "NON_SIGHT_OKAY": 0.07,
            "NON_SIGHT_SKIP": 0.03,
            "NON_SIGHT_GUESS": 0.02,
            "SIGHT_AUTOMATIC": 1.0,
            "SIGHT_SLOW": 0.0,
            "SIGHT_SKIPS": 0.03,
            "SIGHT_GUESSES": 0.0,
            "PAUSING_GOOD": 0.75,
            "RUN_ON": 0.87,
            "TOO_MUCH_PAUSING": 0.16,
            "GOOD_INTONATION": 0.75,
            "BAD_INTONATION": 0.89
        },
        "readingAdvice": "Good job correctly reading larger and harder words. Remember to pause at the ends of sentences."
    },
    "apiVersion":"apiVersion"
 }
Table 4. Performance ID Input Type Response
Parameter Format Description
performanceID Integer A list of the identifiers assigned to a single audio and text pair.
feedback String Providing feedback based on performance. This object contains:
  • behaviors
    • APPROPRIATE_RATE: Student reads at an appropriate rate. Example: 0.5
    • TOO_SLOW: Student reads too slowly. Example: 0.5
    • TOO_FAST: Student reads too fast. Example: 0.5
    • Varied Rate: student's reading rate fluctuates significantly. Example: 0.5
    • NON_SIGHT_CORRECT: Student reads non sight words correctly. Example: 0.5
    • NON_SIGHT_OKAY: Student reads non sight words with some pronunciation mistakes or hesitation. Example: 0.5
    • NON_SIGHT_SKIP: Student tends to skip non sight words. Example: 0.5
    • NON_SIGHT_GUESS: Student tends to guess at non sight words. Example: 0.5
    • SIGHT_AUTOMATIC: Student reads sight words with accuracy and automaticity. Example: 0.5
    • SIGHT_SLOW: Student reads sight words slowly, without automaticity. Example: 0.5
    • SIGHT_SKIPS: Student tends to skip sight words. Example: 0.5
    • SIGHT_GUESSES: Student tends to guess at sight words. Example: 0.5
    • PAUSING_GOOD: Student pauses at the appropriate times. Example: 0.5
    • RUN_ON: Student does not pause at appropriate times. Example: 0.5
    • TOO_MUCH_PAUSING: Student pauses too much or inappropriately. Example: 0.5
    • GOOD_INTONATION: Student demonstrates good intonation at the ends of sentences. Example: 0.5
    • BAD_INTONATION: Student demonstrates bad intonation at the ends of sentences. Example: 0.5
  • readingAdvice: An overall plain language feedback message based on the observed reading behaviors, highlighting a positive aspect of the performance and identifying an area for practice or improvement. Example: 0.5
apiVersion String The current version number for the API.
A the characteristics inputType response will look like:
{
    "annotations":"None",
          "measure":{
             "value":100,
             "display":"100L"
          },
          "displayName":"Lexile Oral Readability Measure"
       },
       "oralReadingAbility":{
          "measure":{
             "value":-245,
             "uncertainty":136,
             "display":"BR245L"
          },
          "displayName":"Lexile Oral Reading Measure"
       }
    },
    "apiVersion":"apiVersion"
 }
Table 5. Characteristics Input Type Response
Parameter Format Description
oralReadingAbility Object This is the Lexile oral reading measure for a student. It contains:
  • measure
    • value: The Lexile oral reading measure for a student rounded to the nearest 5L. Example: 400
    • display: The measure to be used when reporting a Lexile oral reading measure for a student. The letters included with the measure indicate what type of measure this is. Example: 400L
    • uncertainty: The degree of uncertainty expressed in Lexiles.
When relevant, this can also include displayName. This is the name used for the measurement.
apiVersion String The current version number for the API.
apiVersion Object The current version number for the API.

Additionally, these response codes may be returned:

Code Description Example
200 The call was successful.
{
   "annotations":[
      "performanceId":18016,
      "wcpm":80,
      "accuracy":0.7,
    ],
      "oralReadingAbility":      {
         "measure":{
            "value":210,
            "display":"210L",
            "uncertainty":20
         },
         "displayName":"Lexile Oral Reading"
      }
   ],
      "oralReadingAbility":{
         "measure":{
            "value":210,
            "display":"210L",
            "uncertainty":20
         },
         "displayName":"Lexile Oral Reading"
      }
   },
    "feedback": {
        "behaviors": {
            "APPROPRIATE_RATE": 0.75,
            "TOO_SLOW": 0.01,
            "TOO_FAST": 0.62,
            "VARIED_RATE": 0.08,
            "NON_SIGHT_CORRECT": 1.0,
            "NON_SIGHT_OKAY": 0.07,
            "NON_SIGHT_SKIP": 0.03,
            "NON_SIGHT_GUESS": 0.02,
            "SIGHT_AUTOMATIC": 1.0,
            "SIGHT_SLOW": 0.0,
            "SIGHT_SKIPS": 0.03,
            "SIGHT_GUESSES": 0.0,
            "PAUSING_GOOD": 0.75,
            "RUN_ON": 0.87,
            "TOO_MUCH_PAUSING": 0.16,
            "GOOD_INTONATION": 0.75,
            "BAD_INTONATION": 0.89
        },
        "readingAdvice": "Good job correctly reading larger and harder words. Remember to pause at the ends of sentences."
    },
   "apiVersion":"0.1.1"
}
400 The request wasn't successful due to invalid input, a misspelled parameter, or a missing required parameter.

For example, you could receive this error when the audio is too soft or the file is too short to be measured.

{
     "message": "Invalid input.",
     "exceptionType": "ValidationError",
     "additionalInfo": "Check validation errors for specifics.",
     "validationErrors": {
     "audioFile": [
     "Sample Depth of 8 bits is too low."
  ],
     "textFile": [
     "Text file must have a .txt extension and be UTF-8 encoded."
]
}
}
422 The request failed due to the audio recording's performance having characteristics that made its score unreliable.
Note: One unreliable score can affect an aggregate score.
{
     "message": "The audio recording's performance has characteristics that made it's score unreliable.",
     "exceptionType": "UnReportableScoreException"
}
422 The request wasn't successful due to the audio file not meeting the 50% accuracy threshold.
{
     "message": "The audio recording's performance has characteristics that made it's score unreliable.",
     "exceptionType": "UnReportableScoreException"
}
422 The audio recording's performance has characteristics that made it score unreliable.

Media Type: application/json

{
     "message": "The audio recording's performance has characteristics that made it's score unreliable.",
     "exceptionType": "UnReportableScoreException"
}
503 The service is unavailable.
{
  "message": "Service temporarily unavailable, try again later",
  "exceptionType": "APIException",
  "additionalInfo": "Error when calling remote service"
}