The LityxIQ rts (Real-time scoring) API allows user applications to request predictions from LityxIQ in real-time using an API, without the need to login or batch large files of data. To use the API, follow these steps:
1) To enable usage of the RTS API on your LityxIQ instance, contact your Lityx representative. You will be provided with an api key specific to your organization. It will be used when making calls to the API to validate and identify your applications. This will be referred to as your "api-key" in the documentation below. This key is the same for all models you wish to call the API.
2) In the Predict area of LityxIQ, select a model for which you want to call the API, and click Implement & Monitor -> Settings.
3) Click the Real-Time Scoring API tab, and copy the information provided and save them elsewhere. The two keys are each a long sequence of characters that identifies you and the selected model to the api when it is called. These will be referred to below as the "api-validate" and "api-data" keys. The other information provided is a data model for the JSON object that will need to be passed to the api. This includes a placeholder for all the variables the model requires in order to create scores. Your developer will need this information.
4) In your application (e.g., Java, PHP, Python), you will call the API at
https://apis.lityxiq.com/{servername}/rts
through a POST method. Replace {servername} with the identifier for your LityxIQ instance. For example, if you login to "client.lityxiq.com", the "servername" is "client" and you would call the api at https://apis.lityxiq.com/client/rts. In addition, also provide the following headers and data to the api (see below for examples in a variety of languages/environments).
- Header field "api-key": use the api-key obtained in Step 1.
- POST field "api-validate": use the api-validate key specific to the model obtained in Step 2
- POST field "api-data": use the api-data key specific to the model obtained in Step 2
- POST field "data": this should be a valid json object string with the following structure:
- (optional) element named "idvar" that identifies the name of the unique id variable in the data to be provided. If this is given, the api will expect the named variable to be in the provided dataset as documented below, and it will be returned as an identifier for the scores returned. If not provided, the scores returned will be identified using sequential numbering.
- (required) element named "data". This should be a json array of objects (up to 100 elements in the array), each of which contains name/value pairs to serve as input data for the model. The names in the name/value pairs should include all variables that are in the model (and therefore are necessary to provide scores).
- Example: {"idvar":"id","data":[{"id":"A","CLICKS_SUM":30,"CLICKS_WTAVG":20,"IMPRESSIONS_SUM":1000,"IMPRESSIONS_AVG":500},
{"id":"B","CLICKS_SUM":300,"CLICKS_WTAVG":200,"IMPRESSIONS_SUM":10000,"IMPRESSIONS_AVG":500000}]}
5) In your application, the response that comes back is json encoded with up to three nodes:
- message: This node will hold a returned message. In the case of an error, this will be a specific error message.
- status: This node will hold the string “success” or “error”. If the node is not in the response, “error” can be assumed.
- data: This output node will be an array with the scored results. Each element in the array represents an input record, and contains two fields: the id field provided (or the default name "id"), and "score" which contains the resulting prediction. The node will not be provided, or will be an empty array, upon error.
By default, your license includes governed access to the api with a limited number of api calls allowed each second and each day. Contact your Lityx representative for more information.
Example of Returned JSON Object:
{
"message": "Number of records successfully scored = 2",
"status": "success",
"data": [
{
"id": "A",
"score": -16.433185174981801
},
{
"id": "B",
"score": 96.300905412096199
}
]
}
Sample calls in various languages and environments:
C# (RestSharp):
var client = new RestClient("https://apis.lityxiq.com/client/rts");
client.Timeout = -1;
var request = new RestRequest(Method.POST);
request.AddHeader("api-key", "{api-key}");
request.AlwaysMultipartFormData = true;
request.AddParameter("api-validate", "{api-validate key}");
request.AddParameter("api-data", "{api-data key}");
request.AddParameter("data", "{\"idvar\":\"id\",\"data\":[{\"id\":\"A\",\"CLICKS_SUM\":30,\"CLICKS_WTAVG\":20,\"IMPRESSIONS_SUM\":1000,\"IMPRESSIONS_AVG\":500},
{\"id\":\"B\",\"CLICKS_SUM\":300,\"CLICKS_WTAVG\":200,\"IMPRESSIONS_SUM\":10000,\"IMPRESSIONS_AVG\":500000}]}");
IRestResponse response = client.Execute(request);
Console.WriteLine(response.Content);
curl:
curl --location --request POST 'https://apis.lityxiq.com/client/rts' \
--header 'api-key: {api-key}' \
--form 'api-validate={api-validate key}' \
--form 'api-data={api-data key}' \
--form 'data={"idvar":"id","data":[{"id":"A","CLICKS_SUM":30,"CLICKS_WTAVG":20,"IMPRESSIONS_SUM":1000,"IMPRESSIONS_AVG":500},
{"id":"B","CLICKS_SUM":300,"CLICKS_WTAVG":200,"IMPRESSIONS_SUM":10000,"IMPRESSIONS_AVG":500000}]}'
HTTP:
POST /client/rts? HTTP/1.1
Host: apis.lityxiq.com
api-key: {api-key}
=Content-Type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW
----WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="api-validate"
{api-validate key}
----WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="api-data"
{api-data key}
Content-Disposition: form-data; name="data"
{"idvar":"id","data":[{"id":"A","CLICKS_SUM":30,"CLICKS_WTAVG":20,"IMPRESSIONS_SUM":1000,"IMPRESSIONS_AVG":500},
{"id":"B","CLICKS_SUM":300,"CLICKS_WTAVG":200,"IMPRESSIONS_SUM":10000,"IMPRESSIONS_AVG":500000}]}
----WebKitFormBoundary7MA4YWxkTrZu0gW
Python http.client:
import http.client
import mimetypes
conn = http.client.HTTPSConnection("apis.lityxiq.com")
dataList = []
boundary = 'wL36Yn8afVp8Ag7AmP8qZ0SA4n1v9T'
dataList.append('--' + boundary)
dataList.append('Content-Disposition: form-data; name=api-validate;')
dataList.append('Content-Type: {}'.format('multipart/form-data'))
dataList.append('')
dataList.append("{api-validate key")
dataList.append('--' + boundary)
dataList.append('Content-Disposition: form-data; name=api-data;')
dataList.append('Content-Type: {}'.format('multipart/form-data'))
dataList.append('')
dataList.append("{api-data key}")
dataList.append('--' + boundary)
dataList.append('Content-Disposition: form-data; name=data;')
dataList.append('Content-Type: {}'.format('multipart/form-data'))
dataList.append('')
dataList.append("{\"idvar\":\"id\",\"data\":[{\"id\":\"A\",\"CLICKS_SUM\":30,\"CLICKS_WTAVG\":20,\"IMPRESSIONS_SUM\":1000,\"IMPRESSIONS_AVG\":500},
{\"id\":\"B\",\"CLICKS_SUM\":300,\"CLICKS_WTAVG\":200,\"IMPRESSIONS_SUM\":10000,\"IMPRESSIONS_AVG\":500000}]}")
dataList.append('--'+boundary+'--')
dataList.append('')
body = '\r\n'.join(dataList)
payload = body
headers = {
'api-key': '{api-key}',
'Content-type': 'multipart/form-data; boundary={}'.format(boundary)
}
conn.request("POST", "/client/rts", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))