Personalized Glycemic Response Prediction API

Last updated: June 2nd, 2016 - 4:00pm PST

Introduction

Using the Suggestic API is simple. Just follow the tutorial and send any questions our way.

Good luck!


Disclaimer

The API is provided as is, for research and academic use. Please use it responsibly.

Do not prescribe any changes in treatment without medical consent. For any additional information please contact us or refer to our general SAFETY INFORMATION & DISCLAIMER:

Suggestic services are intended to be used together with advice from your healthcare professional who is familiar with your diagnosis and treatment of diabetes. Do not make any changes to your treatment without talking to your healthcare provider first. Suggestic services are intended to provide additional information, which may include glucose ranges prediction that might or might not be suitable for you or your health care provider. Suggestic services are not intended to replace the real-time display of your continuous glucose monitor and/or insulin pump data on your glucometer, if any. Your treatment decisions should be based on blood glucose measurements obtained from a blood glucose meter and your health care provider.

By using this or any Suggestic service you are agreeing to Suggestic's terms and conditions of use.


Usage

Coming soon...


Authentication

Authentication it's extremely simple, you just need an API Key provided by Suggestic. (don't have one? [email protected]). Any API interaction requires your API Key.

For this tutorial, let's use the following API Key:

d4a5652c6971c7468ffcf98c48536d45

Important: All data is anonymous to keep user privacy. Please never send personal identifiable information in any request.


Create a New Predictor

Your first step is to create a new glycemic response predictor. Each predictor is trained individually with each user's data in order to provide specific glycemic response predictions for that user. This needs to be done for each user you expect to have a prediction for.

Each predictor has a unique ID that identifies itself and any data associated with it. In practical terms, you will (most likely) have one Suggestic predictor ID for each of your user's IDs.

curl -X POST 
-H "api_key: d4a5652c6971c7468ffcf98c48536d45" 
-H "Content-Type: application/json" 
-d '{"attributes":{
"numerical":["Fats","Carbs","Proteins","ExerciseTime"],
"categorical":["ExerciseType","InsulinType"],
"text":["Notes"]},
"attributes_categories":{
"nutrition":["Fats","Carbs"]:
"excercise":["ExerciseTime","ExerciseType"]
}
}' "http://api.suggestic.com:8000/v1//glycemic_response/predictor/create"

Try request in console

attributes represents the schema of the data used by a predictor. It contains a variable list of categorized fields that are defined at the creation of a new predictor.

attributes_categories contains optional info about the nature of each variable. Possible values are "excercise", "nutrition", "medication", "biomarkers" and "recreation".

Important: There are 3 default attributes with reserved names; DateTime, Glucose and entryID. You do not need to define or categorize these, as they represent the base log entry schema and they exist by default.

DateTime uses the ISO8601 format, Glucose is a any numeric value and entryID is a string. Details are presented later on.

Response is as follows:

{
  "message": "Predictor successfully created",
  "code": 201,
  "ID": "0a48c154-9f0e-4deb-85ce-fbca61fd5385"
}

ID represents the predictor's unique ID. Any future calls to this predictor requires its ID.


Data Upload

Data is represented in the form of a log, a log entry is a colection of measurements or description of activities with a single mandatory timestamp. This stems from the fact that many applications allow a user to log different values at the same time.

Examples of log entries: A glucose measurement and a timestamp A glucose measurement, carb content ingested in last meal, heart rate and a timestamp * Weight, body fat and a timestamp

You are free to send a single log entry or an array of log entries in each request.

Important: there are 3 mandatory requirements when logging data: You must always send a DateTime. When sending a glucose value (optional) you must call it Glucose. To be able to delete a single log_entry* in the future, you must include an entryID (optional).

For all other values see "Data Catalog" at the end of this documentation.

Adding a single log entry (an array with one element) can be done like this:

curl -X POST 
-H "api_key: d4a5652c6971c7468ffcf98c48536d45" 
-d '{"log_entries":[
        {
            "BasalInsulin": "Lantus\u00ae", 
            "BolusInsulin": "Humalog\u00ae", 
            "BolusValue": "3.2", 
            "CarbRatio": "6.0", 
            "Carbs": "20.0", 
            "DateTime": "16.02.2015 14:28:00", 
            "Glucose": "13.4", 
            "Sensitivity": "1.1100011", 
            "Weight": "84.0",
            "entryID": "adknb739ndn29292nn8e8"
        }]
    }' "http://api.suggestic.com:8000/v1//glycemic_response/predictor/log/put/0a48c154-9f0e-4deb-85ce-fbca61fd5385"

Try request in console

Note that log_entries contains an array of log entries. In this example, the array contains only one log entry. There is no problem with different log entries sharing a single timestamp.

{
  "message": "Log data successfully added",
  "ID": "0a48c154-9f0e-4deb-85ce-fbca61fd5385",
  "code":201
}

For each log entry only variables described in attributes at the time the predictor was created will be considered.

Besides any key names defined in attributes, as explained before, there are two special key names. Glucose and DateTime which are reserved to contain values of glucose measurements and timestamps. The Glucose value is optional in a log entry, but DateTime is mandatory.

After uploading significant historical data for the user you can go ahead with predictor training.

Note: In general terms, the more historical data is sent, the better performance the predictor will exhibit.


Predictor Training

Once you log historical data succesfully you can continue the process by training your predictor.

We recommend to log a minimum of 50 entries before training, in order to see good results, but this is entirely up to you.

To start training the predictor, use its ID, as follows:

curl -X POST 
-H "api_key: d4a5652c6971c7468ffcf98c48536d45" 
-H "Content-Type: application/json" 
-d '{"sizelimit":200}'
"http://api.suggestic.com:8000/v1/glycemic_response/predictor/train/0a48c154-9f0e-4deb-85ce-fbca61fd5385"

Try request in console

{
  "message": "Predictor training initialized",
  "code": 202,
  "ID": "0a48c154-9f0e-4deb-85ce-fbca61fd5385"
}

Although a response is given imediately, the training process continues in the background for several minutes.

You are free to re-train your predictor whenever you see fit, by calling the train method. Either way, your predictor will be automatically re-trained after a significan amount of new data has been logged.

At any time, you can check on the predictor's status, as follows:

curl -X GET 
-H "api_key: d4a5652c6971c7468ffcf98c48536d45" 
-H "Cache-Control: no-cache" 
-H "Postman-Token: 53d0ae9a-706d-1275-4e6b-81dbefb15963"
"http://api.suggestic.com:8000/v1/glycemic_response/predictor/status/0a48c154-9f0e-4deb-85ce-fbca61fd5385"

Try request in console

{
  "status": "deployable",
  "estimated_accuracy": 0.956,
  "ID": "0a48c154-9f0e-4deb-85ce-fbca61fd5385",
  "creation_date": "2016-02-24 17:20:25.586094"
}

Predictor Status

At any time you can obtain information about the status of a predictor using its ID, as follows:

curl -X GET 
-H "api_key: d4a5652c6971c7468ffcf98c48536d45" 
"http://api.suggestic.com:8000/v1/glycemic_response/predictor/status/0a48c154-9f0e-4deb-85ce-fbca61fd5385"

Try request in console

{
  "status": "created",
  "estimated_accuracy": null,
  "ID": "0a48c154-9f0e-4deb-85ce-fbca61fd5385",
  "creation_date": "2016-02-24 17:20:25.586094",
  "code":200
}

status represents the currents status of a predictor. You can start using a predictor when its status is ready.

Training a predictor can take serveral minutes, there is no need to query the predictor's status every second.

estimated_accuracy represents the percentage of times the predictor is expected to provide an accurate glucose range.

Note: A predictor's estimated_accuracy will remain unchanged until a significant amount of data is logged and then retrained. You do not need to retrain the predictor manually as it will do so automatically once a significant amount of new data is added.

Feel free to choose your own cutoff level. Please contact us if you have any questions about this point.


Making Predictions

Once a predictor's status is ready, it is ready to make predictions. For each prediction a new log entry is required. Remember that you can only log data types that were included at the moment of the predictor's creation.

You can choose whether you want this log entry to be added to the log using the add_to_log attribute.

Each prediction consists of a predicted_range wich represents the glucose level predicted at a certain time in the future, represented by mins_ahead, with a certain time range variation, described by mins_ahead_window

Both predicted_range and mins_ahead are dynamically created for each predictor,so you will see differences from one user to another.

You can use the prediction service as follows:

curl -X POST 
-H "api_key: d4a5652c6971c7468ffcf98c48536d45" 
-H "Content-Type: application/json" 
-d '{
    "BasalInsulin": "Lantus\u00ae", 
    "BolusInsulin": "Humalog\u00ae", 
    "CarbRatio": "9.6", 
    "DateTime": "03.08.2014 19:48:00", 
    "Glucose": "20.75702", 
    "Notes": "After Meal, Time After Meal 3.0 hours", 
    "Sensitivity": "2.4", 
    "Weight": "84.0", 
}' "http://api.suggestic.com:8000/v1/glycemic_response/predictor/predict/0a48c154-9f0e-4deb-85ce-fbca61fd5385"

Try request in console

In the following response you can see a predicted glucose level in the range of 14.29 and 31.58 expected to happen in 747.99 minutes from the moment of the prediction, more or less 123.19 minutes. In other words, that prediction is expected to fall between the next 624.8 and 871.78 minutes from now.

{
  "code": 200,
  "mins_ahead_window": 123.19992226723386,
  "mins_ahead": 747.9970089730808,
  "ID": "0a48c154-9f0e-4deb-85ce-fbca61fd5385",
  "predicted_range": [
    14.29,
    31.58
  ],
  "message": "Successful prediction"
}

Initial Attribute Creation

When a predictor is created you need to consider the types of data you would like it to use. After a predictor is created it will not allow changes in the list of attributes.

We recommend that you add all your existing fields at the time of creation of a predictor so you are then free to send any combination of data in each log entry.

When creating a new predictor you will have to define your attributes and categorize them as: "numerical"- for any continuos numeric value, like glucose or grams of carbs. "categorical" - for discrete numeric categories or text, like tags or type of insulin. * "text" - for unstructured text, like a note.

You do not need to define or categorize the DateTime, Glucose or entryID attributes as they represent the base log entry schema and they exist by default.

DateTime uses the ISO8601 format, Glucose is a any numeric value and entryID is a text string.

Important: Please make sure you are consistent with the units you use. If you log glucose data in mmol/L you will get a prediction in mmol/L. You can do any unit conversion at your end. If you log glucose in different units for the same user predictions will be highly incorrect. For any other type of data we recommend that you create different attributes for each unit. For example, you can have: Weight_Kg, Weight_Lb and so on.


Deleting a Single Log Entry

You can delete a single log_entry using it's entryID


Data Catalog and Categories

In general, we recommend uploading the maximum amount of available data and data types. The Suggestic platform will automatically select the best attributes as they relate to the specific dataset and previous experience.

Some recommended categories of data to use are: glucose, insulin, medication, biomarkers, nutrition, exercise, sleep and stress.

Note: Although you don't need to use any specific attribute names, we ask you to be as explicit as possible so the platform can better correlate your data.