Get Oral Readability Measures for Texts

Use this call to calculate the Lexile® oral readability measure for a text that is used for oral reading performances.

Overview

Get a reading difficulty measure on the text files you're using for your oral reading performances. This request must be made in multipart/form-data format.

URI

/text/difficulty

Parameters

A request to get the oral readability measure for a text might look like:
text_file = requests.get(
    "https://s3.amazonaws.com/mmincstatic/oralreadingexamples/example.txt"
).content
files = {"textFile": ("filename.txt", text_file)}
response = requests.post(
    "https://oralreading-analyzer.lexile.com/text/difficulty",
    files=files,
    headers={"Authorization": f"Bearer {access_token}"},
)

The request includes these 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}"
textFile String The text file that corresponds with an audio file that will be measured.

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

Response

A response that contains the oral readability measure might look like:
{
    "oralReadingDifficulty":{
       "measure":{
          "value":1060,
          "display":"1060L"
       },
       "displayName":"Lexile Oral Readability Measure"
    },
    "apiVersion":"apiVersion",
}

These values may be returned in the response:

Parameter Format Description
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.
displayName String The name that is commonly used for the measure that was returned.
apiVersion String The current version number for the API.

Additionally, these response codes may be returned:

Code Description Example
200 The call was successful. 
{
  "oralReadingDifficulty": {
    "measure": {
      "value": 210
    }
  },
  "apiVersion": "ac86530c-develop",
 }
400 The request wasn't successful due to invalid input, a misspelled parameter, or a missing required parameter. 
{
  "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"
}