Get Oral Reading Measures for Students

Use this to calculate the Lexile® oral reading measure for an individual student performance.

Overview

There are two ways to get a student measure:
  1. Send text and an audio performance to be analyzed and receive a Lexile oral reading measure. This request must be made in multipart/form-data, which means you're passing a textfile and audiofile.
  2. Send student performance characteristics and a Lexile oral readability measure for a text to receive a 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

Parameters

Each call should include the general parameters and the parameters relevant to the inputType you set.

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.
  • audio: Use this if you want to pass an audio performance to get a measurement.
A request using the audio 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}"},
)

The audio inputType request includes these parameters:

Table 2. Audio Input Parameters
Parameter Format Description
textFile String The text file that corresponds with an audio file that will be measured.

The file should be an unformatted text file (UTF8).

audioFile String The binary audio file for measurement.
The file should be:
  • 16 bit-depth (minimum)
  • between 22.05kHz (minimum) to 44.1kHz (recommended) sampling frequency
  • in .wav or .mp3 file format
If the audio file is too short or the audio in the file is too soft we may not be able to measure it.
speechModel String Indicates if the audio should be evaluated as adult or child speech. Typically the switch from child to adult is around 12 to 13 years old. Options are:
  • child: Use this for performances given by a person who is a child. If no speechModel is set, the API defaults to child.
  • adult: Use this for performances given by a person who is an adult.
  • auto: Use when you cannot specify if the performer is an adult or child.
A request using the characteristics inputType might look like:
body = {"wcpm": 120, "oralReadingDifficulty": {"measure": {"value": 1060}}, "accuracy": 0.75}
response = requests.post(
    (
        "https://oralreading-analyzer.lexile.com/reader/performance/ability"
        "?inputType=characteristics"
    ),
    json=body,
    headers={"Authorization": f"Bearer {access_token}"},
)

The characteristics inputType request includes these parameters:

Table 3. Characteristic Input 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

What your receive in the response will depend on the inputType used.

A response using the audio inputType might look like: 
{
    "performanceId":29,
    "wcpm":9.046362608367884,
    "accuracy":0.3,
    "oralReadingAbility":{
       "measure":{
          "value":-1840,
          "display":"BR1840L",
          "uncertainty":193
       },
       "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"
 }

The audio inputType response includes these parameters:

Table 4. Audio Input Type Response
Parameter Format Description
performanceID Integer A list of the identifiers assigned to a single audio and text pair.
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
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.
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 Object The current version number for the API.
A response for the characteristics inputType might look like:
{    
    "oralReadingAbility":{
       "measure":{
          "value":655,
          "display":"655L",
          "uncertainty":193
       },
       "displayName":"Lexile Oral Reading Measure"
    },
    "wcpm":120.0,
    "accuracy":0.75,
    "apiVersion":"apiVersion"
 }

The characteristics inputType response includes these parameters:

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.

Additionally, these response codes may be returned:

Code Description Example
200 The call was successful. 
{
   "performanceId":18016,
   "wcpm":80,
   "accuracy":0.7
},
   "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."
    ]
  }
}
503 The service is unavailable. 
{
  "message": "Service temporarily unavailable, try again later",
  "exceptionType": "APIException",
  "additionalInfo": "Error when calling remote service"
}