The REST API is the underlying interface for our official PredictBGL API. This reference document is designed for those interested in exploring API features in detail.
Please join our API group so that we can keep you informed of updates, changes, down-time etc -
See Sample web interface, sample PHP code.
API index:
We require that all requests are performed over SSL.
Every string passed to and from the PredictBGL API needs to be UTF-8 encoded.
The current version of our API is version 1.0.
All dates in the API are UTC/GMT strings in the following format:
"2012-12-31 22:31:20"
In code format, which can be used in all programming languages that support
strftime or strptime:
"%Y-%m-%d %H:%i:%s" - MySQL "Y-m-d H:i:s" - PHP
Internally, all dates are stored in UTC/GMT time.
By default, results are returned in XML format. To specify JSON, AMF, PLIST or YAML format, append the desired output format to the function name e.g.
| Default |
https://www.PredictBGL.com/api/1.0/login?email=email&password=password |
| JSON |
https://www.PredictBGL.com/api/1.0/login.json?email=email&password=password |
| XML |
https://www.PredictBGL.com/api/1.0/login.xml?email=email&password=password |
| AMF |
https://www.PredictBGL.com/api/1.0/login.amf?email=email&password=password |
| PLIST |
https://www.PredictBGL.com/api/1.0/login.plist?email=email&password=password |
| YAML |
https://www.PredictBGL.com/api/1.0/login.yaml?email=email&password=password |
Errors are returned using standard HTTP error code syntax. Any additional info is included in the body of the return call, JSON-formatted. Error codes not listed here are in the REST API methods listed below.
| Code | Description |
|---|---|
| 400 | Bad input parameter. Error message should indicate which one and why. |
| 401 | Bad or expired token. This can happen if the user or PredictBGL revoked or expired an access token. To fix, you should re-authenticate the user. |
| 404 | File or folder not found at the specified path. |
| 405 | Request method not expected (generally should be GET or POST). |
| 503 | Your app is making too many requests and is being rate limited. 503s can trigger on a per-app or per-user basis. |
Create a new account (app only)
https://www.PredictBGL.com/api/1.0/create_account?first=first&last=last&email=email&password=password&third_party_id=tpi
If the email is not known, an account is created but the user must confirm it first.
If the email and password are already known (e.g. signup instead of login by mistake), it returns a user id and an API request token for future requests. This allows the user to signup, switch to email to confirm, then return to the app to continue login without having to switch screens or re-enter email and password.
The API token is a varchar(40).
Sample JSON response on success
{
"user_id": 2132,
"token": "2132-gerio77fe88ihvab2jpuu8pvl7",
"result": true,
"message": "Ok"
}
Sample JSON response on failure
{
"result": false,
"message": "User already exists"
}
or
{
"result": false,
"message": "Please check your Inbox for an activation email."
}
PredictBGL uses a Client Login to authenticate all API requests. See Sample. You can also obtain an API Token via a POST request to an OAuth-style interface.
Login and obtain authentication token for future requests. The token is consistent and can be stored for all future requests. It only changes when specifically requested by the user, and is independent of name, email address or password changes.
https://www.PredictBGL.com/api/1.0/login?email=email&password=password
A request token and user_id, or an error message. The token is a varchar(40).
Note: Message can be 'Ok' or a special message is returned to support product. This must be displayed to the user each time it occurs.
Sample JSON response on success
{
"token": "2132-gerio77fe88ihvab2jpuu8pvl7",
"user_id": 3,
"result": true,
"message": "Ok"
}
Sample JSON response on Recall
{
"token": "2132-gerio77fe88ihvab2jpuu8pvl7",
"user_id": 3,
"result": true,
"message": "Warning - your service needs updating as no device or version is being passed to login"
}
Sample JSON response on failure
{
"result": false,
"message": "Incorrect password, 3 attempts are left before your account is disabled."
}
In addition to the login endpoint above, you can also obtain an API Token via a GET or POST request to an OAuth-style interface at https://www.PredictBGL.com/get_token.html.
Obtain authentication token for future requests. The token is consistent and can be stored for all future requests. It only changes when specifically requested by the user, and is independent of name, email address or password changes.
http:// or https://www.PredictBGL.com/api/1.0/get_token.html
Note: Do NOT pass passwords unless you call the https version of this function (it is also possible to call it via http).
If successful, a redirect occurs to success_url with '?token=<API token>' on success.
token is a varchar(40).
Removes authentication. See Sample
https://www.PredictBGL.com/api/1.0/logout?token=token
Sample JSON response
{
"result": true,
"message": "Logout Ok"
}
Add a log entry. See Sample. Note - to convert mg/dL to mmol/L, simply divide by 18.
https://www.PredictBGL.com/api/1.0/add?token=token&value=value
| Data type being logged | log_type | value | other | notes | guid |
| BGL | 1 | Blood sugar level in mmol/l e.g. 4.6 | The prediction in mmol/L, if known, zero if not. Changed 2015-11-01. Set the prediction: Get the prediction in mmol: Valid prediction range: 0 to 31.5 mmol/L. |
||
| Insulin | 2 | Number of units, may be decimal e.g. 0.5, 1.6, 16 | Type of insulin, see below | ||
| Carbs | 3 | Amount of carbs in grams e.g. 60, 32, 3 | GI type. Use 2 if unknown. | Formerly was in person's units | |
| Protein | 4 | Protein amount in grams | |||
| Fat | 5 | Fat amount in grams | |||
| Fibre | 6 | Fiber amount in grams | |||
| Ketones | 7 | Ketone reading, no '%', e.g. 7.3 | |||
| Blood Pressure | 8 | Systolic (in mmHg)/Diastolic (in mmHg) e.g. 190/80 | Note - extract returns Systolic in value and Diastolic in other | ||
| Lab A1C/HbA1C | 9 | A1C reading, no '%' e.g. 7.1 | |||
| Notes | 10 | Notes text | |||
| Fructose | 11 | Fructose reading, no '%' e.g. 8.3 | |||
| Weight | 12 | Weight in kg e.g. 78, 105 | Formerly was in person's units | ||
| Exercise - Low Impact | 13 | Duration in minutes, e.g. 60 | |||
| Exercise - Medium Impact | 14 | Duration in minutes, e.g. 45 | |||
| Exercise - High Impact | 15 | Duration in minutes, e.g. 45 | |||
| Illness | 16 | Duration in hours, e.g. 48 | |||
| Pre-menstruation | 17 | Duration in hours, e.g. 48 | |||
| Adrenaline | 18 | Duration in hours, e.g. 2 | |||
| Stress | 19 | Duration in hours, e.g. 6 | |||
| Height | 20 | Height in cm e.g. 188, 144 | Formerly was in person's units | ||
| A1C/HbA1C - New | 21 | A1C reading, in mmol/mol eg. 54 - these are measured differently to log_type 9 | |||
| BGL Sensor | 22 | BGLs from sensor data in mmol/l, generally every 5 minutes | Formerly was in person's units | ||
| Audit | 23 | Version number | Audit log, describing changes to ratios or settings | ||
| Temp Basal | 24 | Duration in minutes, e.g. 45 | % change from 0% to 200%, stored as the percentage minus 100, e.g. 0% is stored as -100, 100% is stored as 0, 200% is stored as +100. | ||
|
--25-29 for future use-- |
|||||
| Endocrinologist visit | 30 | ||||
| Optometrist visit | 31 | ||||
| Kidney test | 32 | ||||
| Blood test | 33 | ||||
| Nerve test | 34 | ||||
| Diabetes educator visit | 35 | ||||
| Dietician visit | 36 | ||||
| Thyroid test | 37 | ||||
| HbA1C - Home test | 38 | A1C reading, no '%' e.g. 7.1. Less accurate than Lab test | |||
| Custom factor 1 | 39 | Duration in minutes, e.g. 45 | |||
| Custom factor 2 | 40 | Duration in minutes, e.g. 45 | |||
| Alcohol | 41 | ||||
| C-Peptide | 42 | Value in % | |||
| Fasting Plasma Glucose test | 43 | In mmol/l | Formerly was in person's units | ||
| Oral Glucose Tolerance test | 44 | In mmol/l | Formerly was in person's units | ||
| Random Plasma Glucose test | 45 | In mmol/l | Formerly was in person's units | ||
| Triglyceride | 46 | In mmol/l | Formerly was in person's units | ||
| Podiatrist visit | 47 | ||||
| Liver test | 48 | ||||
| Vitamin D | 49 | In IU | |||
| Cholesterol LDL | 50 | ||||
| Cholesterol HDL | 51 | ||||
| Cholesterol VLDL | 52 | ||||
| Cholesterol Total | 53 | ||||
| Pain | 54 | Duration in hours | |||
| Split Dose | 55 | Dose - number of units | Duration in minutes divided by 5 ie value of 3 = 15 minutes | ||
| Feeling Happy | 56 | - | - | ||
| Feeling Hypo | 57 | - | - | ||
| Feeling Nervous | 58 | - | - | ||
| Feeling Normal | 59 | - | - | ||
| Feeling Sad | 60 | - | - | ||
| Body Fat Percentage | 61 | % | |||
| Body Water Percentage | 62 | % | |||
| Physician visit | 63 | ||||
| Fluid Intake | 64 | mls | |||
| 1 | Humalog |
| 2 | Lantus |
| 3 | Actrapid |
| 4 | Humulin NPH |
| 5 | Monotard |
| 6 | Novorapid |
| 8 | Humulin R |
| 9 | Levemir |
| 12 | Humalog mix 25 |
| 13 | Humalog mix 50 |
| 14 | Humulin 30/70 |
| 15 | NovoMix 30 |
| 16 | Protaphane |
| 17 | Mixtard 30/70 |
| 18 | Mixtard 50/50 |
| 19 | Apidra |
| 20 | Novorapid |
| 21 | Protaphane |
| 22 | Tresiba |
| 1 | Low GI |
| 2 | Normal GI - use this by default |
| 3 | High GI |
| 4 | Very high GI (e.g. in the case of Hypo recovery) |
| 5 | Very low GI/Fatty (e.g. generally high fat foods such as pizza, lasagne) |
Id of inserted record, or error message.
Sample call
{
"token": "2132-gerio77fe88ihvab2jpuu8pvl7",
"log_type": 1,
"time": "2014-06-03 14:00:03",
"value": 12.2,
"notes": "A big high today"
}
Sample response on success
{
"token": "2132-gerio77fe88ihvab2jpuu8pvl7",
"result": true,
"message": "Ok",
"id": 1278129,
"points", 30
}
Sample response on failure
{
"result": false,
"message": "BGL must be in range 1.2 to 28 mmol\/l, Lo or Hi (not 200)"
}
Adds an array of log entries. Note - to convert mg/dL to mmol/L, simply divide by 18.
https://www.PredictBGL.com/api/1.0/add_logs?token=token&logs=<array>
An array containing Ids for each inserted record (or 0 on error), and an error message for each inserted record.
Sample call
{
"token": "2132-gerio77fe88ihvab2jpuu8pvl7",
"logs": [ [
"log_type": 1,
"time": "2014-06-03 14:00:03",
"value": 12.2,
"notes": "A big high today" ],
[
"log_type": 2,
"time": "2014-06-03 14:01:53",
"value": 1.5,
"other": 2,
"notes": "my correction dose" ]
]
}
Sample response on success or failure
{
"token": "2132-gerio77fe88ihvab2jpuu8pvl7",
"result": true,
"id": [ 92473, 92474, 92475, 0 ],
"message": [ "", "", "", "BGL must be in range 1.2 to 28 mmol\/l, Lo or Hi (not 200)"]
}
Add a log entry that has been deleted on the remote device. All log entries that have been deleted must be records for auditing purposes.
https://www.PredictBGL.com/api/1.0/add_deleted?token=token&value=value
Id of inserted record, or error message.
Sample response on success
{
"token": "2132-gerio77fe88ihvab2jpuu8pvl7",
"result": true,
"message": "Ok",
"id": 1278129
}
Sample response on failure
{
"result": false,
"message": "BGL must be in range 1.2 to 28 mmol\/l, Lo or Hi (not 200)"
}
https://www.PredictBGL.com/api/1.0/update?token=token&log_id=log_id&value=value
Sample response on success
{
"result": true,
"message": "Ok",
"id": 1278129
}
Sample response on failure
{
"result": false,
"message": "BGL must be in range 1.2 to 28 mmol\/l, Lo or Hi (not 200)"
}Updates a log entry. Only the field(s) being changed need to be specified. Note that audit entries cannot be updated, although the website as the master
https://www.PredictBGL.com/api/1.0/update_logs?token=token&logs=<array>
An array of messages for each updated record.
Sample call
{
"token": "2132-gerio77fe88ihvab2jpuu8pvl7",
"logs": [ [
"log_id": 1458354,
"log_type": 1,
"time": "2014-06-03 14:00:03",
"value": 35,
"notes": "A big high today" ],
[
"log_id": 1458355,
"log_type": 2,
"time": "2014-06-03 14:01:53",
"value": 1.5,
"other": 2 ]
]
}
Sample response on success or failure
{
"result": true,
"message": [ "BGL must be in range 1.2 to 28 mmol\/l, Lo or Hi (not 200)", "" ]
}
Deletes a log entry, and moves it to the deleted logs for audit purposes.
https://www.PredictBGL.com/api/1.0/delete?token=token&log_id=log_id
Status message, or error message.
Sample response on success
{
"result": 1,
"message": "Success",
}
Sample response on failure
{
"result": 2,
"message": "Not found"
}
or
{
"result": 3,
"message": "Missing log_id"
}
https://www.PredictBGL.com/api/1.0/units?token=token
Sample JSON response
{
"result": true,
"message": "Ok",
"carb_units": 1,
"carb_units_name": "exchanges",
"bgl_units": 1,
"bgl_units_name": "mg\/dl",
"dimensional_units": 1,
"dimensional_units_name": "Imperial",
"time_zone_offset": 600
}
Updates a log entry. Only the field(s) being changed need to be specified. Note that audit entries cannot be updated, although the website as the master
https://www.PredictBGL.com/api/1.0/update?token=token&log_id=log_id&value=value
Id of updated record, or error message.
Sample response on success
{
"result": true,
"message": "Ok",
"id": 1278129
}
Sample response on failure
{
"result": false,
"message": "BGL must be in range 1.2 to 28 mmol\/l, Lo or Hi (not 200)"
}
Deletes a log entry, and moves it to the deleted logs for audit purposes.
https://www.PredictBGL.com/api/1.0/delete?token=token&log_id=log_id
Status message, or error message.
Sample response on success
{
"result": 1,
"message": "Success",
}
Sample response on failure
{
"result": 2,
"message": "Not found"
}
or
{
"result": 3,
"message": "Missing log_id"
}
https://www.PredictBGL.com/api/1.0/units?token=token
Sample JSON response
{
"result": true,
"message": "Ok",
"carb_units": 1,
"carb_units_name": "exchanges",
"bgl_units": 1,
"bgl_units_name": "mg\/dl",
"dimensional_units": 1,
"dimensional_units_name": "Imperial",
"time_zone_offset": 600
}
https://www.PredictBGL.com/api/1.0/sync_status?token=token
Sample JSON response
{
"result": true,
"message": "Ok",
"version": 165,
"last_log": "2014-08-14 14:22:10"
}
https://www.PredictBGL.com/api/1.0/settings?token=token
Sample JSON response
{
"result": true,
"message": "Ok",
"version": 171,
"ratios": {
"1": [
{
"start_min": 0,
"value": 3,
"other": 0
}
],
"2": [
{
"start_min": 0,
"value": 8,
"other": 0
},
{
"start_min": 660,
"value": 12,
"other": 0
},
{
"start_min": 1080,
"value": 18,
"other": 0
}
],
"3": [
{
"start_min": 0,
"value": 6,
"other": 0
},
{
"start_min": 480,
"value": 4.8,
"other": 0
},
{
"start_min": 1140,
"value": 6,
"other": 0
}
],
"4": [
{
"start_min": 0,
"value": 0,
"other": 0
}
],
"5": [
{
"start_min": 420,
"value": 45,
"other": 1
},
{
"start_min": 630,
"value": 30,
"other": 2
},
{
"start_min": 780,
"value": 60,
"other": 3
},
{
"start_min": 930,
"value": 30,
"other": 4
},
{
"start_min": 1080,
"value": 60,
"other": 5
},
{
"start_min": 1290,
"value": 30,
"other": 6
}
],
"6": [
{
"start_min": 0,
"value": 0,
"other": 0
}
],
"7": [
{
"start_min": 1320,
"value": 17,
"other": 2
}
]
},
"ratio_names": {
"1": "Insulin sensitivity",
"2": "Carb sensitivity",
"3": "Target BGL",
"4": "Basal rate",
"5": "Meal times",
"6": "Dawn phenomenon",
"7": "Basal insulins"
},
"factors": {
"exercise1_insulin": 10,
"exercise2_insulin": 70,
"exercise3_insulin": 100,
"exercise3_sugar": 127,
"stress_insulin": -128,
"stress_sugar": 20,
"illness_insulin": -30,
"adrenaline_insulin": -30,
"pain_insulin": -30,
"premen_insulin": -5,
"custom_insulin": 20,
"custom2_insulin": 0
},
"insulins": {
"use_calc": 1,
"model_basal": 1,
"insulin_short": 1,
"insulin_short2": 0,
"insulin_long": 2,
"insulin_long2": 0,
"active_insulin_time": 4,
"insulin_increment": 0.5,
"max_bolus": 13,
"t2_return": 0
},
"carbs": {
"protein_conversion": 50,
"fat_conversion": 10,
"carb_units": 0,
"default_gi": 2,
"delayed_eating": 1,
"lowbgl_treatment": 0,
"lowbgl_grams": 3,
"liver_threshold": 0,
"liver_rate": 0
},
"other": {
"gender": 1,
"use_calc": 1,
"avatar": "085286b6dcef440d.png",
"dob": "1973-02-21",
"bgl_units": 0,
"dimensional_units": 0,
"timezone_offset": -660,
"diabetes_type_id": 1,
"role_type_id": 1,
"year_diagnosis": 1982,
"therapy_type_id": 2,
"chart_low_range": 4,
"chart_high_range": 10,
"chart_max": 18,
"chart_meter_error": 1,
"pattern_days": 5,
"setup_percent_complete": 94,
"default_exercise": 14,
"reminder_meal": 1,
"reminder_basal": 1
},
"need": [
{
"id": "meals",
"msg": "What time is coffee? Please setup your usual meal times <img src=\"..\/images\/icon-meal.png\" width=\"16\" height=\"16\" alt=\"Meals\">",
"url": "settings-meals.html"
},
{
"id": "ins_sens",
"msg": "Do you take extra insulin when your BGL is high? Please setup your Correction Ratio (AKA Insulin Sensitivity). <a target=\"_blank\" href=\"\/scenarios\/calculating-insulin-sensitivity-factor-ISF.html\">Worksheet<\/a>\n| <a target=\"_blank\" href=\"https:\/\/www.youtube.com\/watch?v=iExsa0VHTZU&rel=0\">Video<\/a>",
"url": "settings-sensitivity-insulin.html"
}
]
}
https://www.PredictBGL.com/api/1.0/setup_check?token=token
Sample JSON response
{
"need": [
{
"id": "hba1c",
"msg": "You have not entered an <b>A1C\/HbA1C<\/b> in the last 6 months. This is a good measure of control. <a target=\"_blank\" href=\"..\/settings-health-care-team.html\">Make appointment<\/a>",
"url": "logs.html?new=1&logtype_id=9"
}
],
"result": true,
"message": "Ok"
}
Check if the API is running correctly.
https://www.PredictBGL.com/api/1.0/ping
A status message. Note - UTC/GMT time.
Sample JSON response on success
{
"result": "PredictBGL.com API Live, 2013-02-18 12:37:01",
"message": "Ok"
}
Sample JSON response on failure
- no result
Check if the database is running correctly.
https://www.PredictBGL.com/api/1.0/ping_db
A status message. Note - UTC/GMT time.
Sample JSON response on success
{
"result": "PredictBGL.com DB Live, 2013-02-18 12:37:01",
"message": "Ok"
}
Sample JSON response on failure
- no result
https://www.PredictBGL.com/api/1.0/log_range?token=token
Sample JSON response on success
{
"token": "2132-gerio77fe88ihvab2jpuu8pvl7",
"result": true,
"message": "Ok",
"start_date": "2011-11-29 07:02:00",
"end_date": "2013-02-18 03:02:12"}
Sample response on failure
{
"result": false,
"message": "Invalid user"
}
https://www.PredictBGL.com/api/1.0/extract?token=token&start_date=start_date&end_date=end_date&page=page
Sample JSON response on success
{
"logs": [
{
"log_id": 92473,
"user_id": 1,
"logtype_id": 1,
"other": 0,
"time": "2013-01-28 11:27:00",
"value": 7.33333,
"notes": null
},
{
"log_id": 92533,
"user_id": 1,
"logtype_id": 3,
"other": 2,
"time": "2013-02-05 00:26:00",
"value": 100,
"notes": ""
}
],
"rows": 2,
"logs_deleted": [
{
"log_id": 92478
}
],
"rows_deleted": 1,
"max_logs": 100,
"result": true,
"message": "Ok"
}
Sample JSON response on final page
{
"logs": [
],
"rows": 0,
"max_logs": 100,
"result": true,
"message": "Ok"
}
Sample response on failure
{
"result": false,
"message": "Query error"
}
https://www.PredictBGL.com/api/1.0/predict?token=token&subscriber=subscriber_token&start_date=start_date&end_date=end_date&third_party_id=tpi
Sample JSON response on success
{
"token": "2132-gerio77fe88ihvab2jpuu8pvl7",
"prediction": [
{
"time": "2013-01-28 11:25:00",
"value": 7.3,
},
{
"time": "2013-01-28 11:30:00",
"value": 6.9,
},
....
{
"time": "2013-01-28 14:25:00",
"value": 5.0,
}
],
"rows": 120,
"result": true,
"message": "Ok"
}
Sample response on failure
{
"result": false,
"message": "Incomplete setup"
}
N/A - POST only:
https://www.PredictBGL.com/api/1.0/import token=token subscriber=subscriber_token upload=file_data
Sample JSON response on success
{
"result": true,
"message": "372 rows imported"
}
Sample response on failure
{
"result": false,
"message": "Unknown file type"
}
N/A - POST only:
https://www.PredictBGL.com/api/1.0/avatar token=token avatar=file_data
Sample JSON response on success
{
"result": true,
"message": "Avatar set"
}
Sample response on failure
{
"result": false,
"message": "Avatar too big"
}
https://www.PredictBGL.com/api/1.0/nonce?token=token
https://www.PredictBGL.com/reports.html?nonce=nonce
Sample JSON response on success
{
"token": "2132-gerio77fe88ihvab2jpuu8pvl7",
"result": true,
"message": "Ok",
"nonce": "2132-dsfdsgfjdsgfjdskjfdds76dsfdsf76dsf76ds6f76dsf768dsf68ds6f8ds6f8d6fds87s"
}
Sample response on failure
{
"result": false,
"message": "Invalid user"
}