Get Measure Using Item IDs with Results and Prior Student Information

Overview

This Bayesian function should be used when:

There is prior information about a student. For example, a previously-computed ability with uncertainty and number of days since that assessment elapsedDays.
The student has taken some number of items, each represented by an item ID.
The item responses (correct/incorrect) for each item are known.

URL

POST /api/score/items/idsWithResults/bayes

Request

The following parameters are required in the request. An example is provided in the Code Example section.


Parameter	Type	Description
`priorAbility`	Integer	The student’s prior ability estimate.
`priorUncertainty`	Integer	Uncertainty associated with the student’s prior ability estimate.
`elapsedDays`	Integer	Number of days since the student’s measure was last updated.
`items`	Array	Array of item objects. Each item object is a dictionary with required parameters: `itemid` String ID of item used in the request body. Must have a prefix of “Q”, “L”, or “S”. MetaMetrics will provide these IDs. `results` String Item response results: `0` (incorrect) or `1` (correct).

Response

This returns an object that contains the computed ability and uncertainty. See Scoring Service Response Codes for an explanation of error codes that might be returned.


Parameter	Type	Description
`ability`	Integer	The student’s new ability estimate.
`uncertainty`	Integer	Uncertainty associated with the student’s new ability estimate.
`framework`	String	Either Lexile or Quantile Framework used to produce the measure.
`apiVersion`	String	The current version number for the API.

Code Examples

The following show examples of the request followed by the response. The Python example is written for use with Python 3 and above.

import java.io.BufferedReader;
                   import java.io.IOException;
                   import java.io.InputStreamReader;
                   import java.util.HashMap;
                   import java.util.List;
                   import java.util.ArrayList;
                   import java.util.Arrays;
                   import java.util.Map;
                   import org.apache.http.HttpHeaders;
                   import org.apache.http.HttpResponse;
                   import org.apache.http.client.HttpClient;
                   import org.apache.http.client.methods.HttpPost;
                   import org.apache.http.entity.StringEntity;
                   import org.apache.http.impl.client.HttpClientBuilder;
                   
                   import org.json.JSONObject;
                   
                   
                   public class BayesItemIdWithResults {
                   public static void main( String[] args )
                   {
                   try
                   {
                   // Call 7
                   
                   String baseURL = "https://scoring.lexile.com";
                   String clientId = "your_client_id";
                   String clientSecret = "your_client_secret";
                   
                   HttpClient client = HttpClientBuilder.create().build();
                   HttpPost authPost = new HttpPost(baseURL + "/authToken");
                   JSONObject jsonInput = new JSONObject();
                   jsonInput.put("clientId", clientId);
                   jsonInput.put("clientSecret", clientSecret);
                   StringEntity input = new StringEntity(jsonInput.toString());
                   authPost.setEntity(input);
                   authPost.setHeader(HttpHeaders.CONTENT_TYPE, "application/json");
                   HttpResponse response = client.execute(authPost); 
                   StringBuilder stringBuilder = new StringBuilder();
                   BufferedReader rd = new BufferedReader(new InputStreamReader(response.getEntity().getContent()));
                   String line;
                   while ((line = rd.readLine()) != null) 
                   {
                   stringBuilder.append(line);
                   }
                   JSONObject json = new JSONObject(stringBuilder.toString());
                   String token = (String) json.get("accessToken");
                   Integer expires = (Integer) json.get("expiresIn");
                   
                   
                   // 1) Basic Example
                   
                   HttpPost postItemId = new HttpPost(baseURL + "/api/score/items/idsWithResults/bayes");
                   JSONObject postData = new JSONObject();
                   postData.put("numberCorrect", 2);
                   postData.put("framework", "quantile");
                   postData.put("priorAbility", 500);
                   postData.put("priorUncertainty", 100);
                   postData.put("elapsedDays", 50);
                   
                   JSONArray itemList = new JSONArray();
                   JSONObject item = new JSONObject();
                   item.put("id","L17075");
                   item.put("result", 0);
                   itemList.put(item);
                   JSONObject item2 = new JSONObject();
                   item2.put("id","L17076");
                   item2.put("result", 1);
                   itemList.put(item2);
                   JSONObject item3 = new JSONObject();
                   item3.put("id","L17078");
                   item3.put("result", 1);
                   itemList.put(item3);
                   postData.put("items", itemList);
                   
                   StringEntity itemIdInput = new StringEntity(postData.toString());
                   input.setContentType("application/json");
                   postItemId.setEntity(itemIdInput);
                   postItemId.setHeader(HttpHeaders.AUTHORIZATION, "Bearer " + token);
                   postItemId.setHeader(HttpHeaders.CONTENT_TYPE, "application/json");
                   response = client.execute(postItemId); 
                   stringBuilder = new StringBuilder();
                   rd = new BufferedReader(new InputStreamReader(response.getEntity().getContent()));
                   while ((line = rd.readLine()) != null) 
                   {
                   stringBuilder.append(line);
                   }
                   JSONObject output = new JSONObject(stringBuilder.toString());
                   Integer ability = (Integer) output.get("ability");
                   Integer uncertainty = (Integer) output.get("uncertainty");
                   String framework = (String) output.get("framework");
                   String apiVersion = (String) output.get("apiVersion");
                   }
                   catch(IOException e) 
                   {
                   e.printStackTrace();
                   }
                   }
                   }
                   
                   //System.out.println(stringBuilder.toString());

# Call 7
                       
                       # /authToken
                       
                       import requests
                       import json
                       
                       base_url = "https://scoring.lexile.com"
                       client_id = "your_client_id"  # replace with your provided client ID
                       client_secret = "your_client_secret"  # replace with your provided client secret
                       response = requests.post(
                       f"{base_url}/authToken",
                       data={"clientId": client_id, "clientSecret": client_secret},
                       )
                       access_token = response.json()["accessToken"]  # use in Authorization header
                       
                       # use these headers to make requests
                       headers = {
                       "Authorization": f"Bearer {access_token}",
                       "Content-Type": "application/json",
                       }
                       
                       
                       # /api/score/items/idsWithResults/bayes
                       
                       # 1) Basic Example
                       data = {
                       "priorAbility": 500,
                       "priorUncertainty": 100,
                       "elapsedDays": 15,
                       "framework": "lexile",
                       "items": [
                       {"id": "L17075", "result": 0},
                       {"id": "L17076", "result": 1},
                       {"id": "L17078", "result": 1},
                       ],
                       }
                       response = requests.post(
                       f"{base_url}/api/score/items/idsWithResults/bayes", headers=headers, json=data
                       )
                       response.json()
                       # returns
                       # {
                       #    "ability": <int>,
                       #    "uncertainty": <int>
                       #    "framework": ["lexile", "quantile"]
                       #    "apiVersion": <string>
                       # }