Medal API Dashboard

Introduction

The Medal API allows you to perform all the operations that you do with our web client. Medal API is built using REST principles which ensures predictable URLs that make writing applications easy. This API follows HTTP rules, so a wide range of HTTP clients can be used to interact with the API. Every resource is exposed as a URL. The URL of each resource can be obtained by accessing the API Root Endpoint.

Api URL

https://www.medicalalgorithms.com/api/v1

HTTP Request method and Authentication

The API supports HTTP GET/POST & Authentication using the combination of user specific API-key and algorithm key (where required). This allows you to protect your API URLs on your web server so that only you can access them. You may provide a API-key and Algorithm key by setting headers as show below.

copy

curl_setopt($curl, CURLOPT_POST, true);
curl_setopt($curl, CURLOPT_HTTPHEADER,
 array(
 "Content-type: application/json",
 "X-Api-Key:API-KEY",
 "X-Algo-Key:ALGORITHM-KEY",
 )
 );

API Endpoints:

Endpoint : algorithmsList

Request Method : GET

Purpose : To get the assigned algorithms list

API Request using PHP cURL - an example

copy

 
	$url = "http://medicalalgorithms.com/api/v1/algorithmsList";
	$curl = curl_init($url);
	curl_setopt($curl, CURLOPT_HEADER, false);
	curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
	curl_setopt($curl, CURLOPT_HTTPHEADER,
	array(
	"Content-type: application/json",
	"X-Api-Key:API-KEY"
	)
	);
	$json_response = curl_exec($curl);
	$status = curl_getinfo($curl, CURLINFO_HTTP_CODE);
	curl_close($curl);
	$response = json_decode($json_response, true);

API Response

The API provide results in JSON object containing the Assigned Algorithms List

A sample API response is shown as follows :

copy


{
 "code":1,
 "error":"No rrror",
 "algorithms":[
 {
	"title":"",
	"algorithm_key":"",
	"created":"",
	"purpose":"",
	"icd_codes":[
	{
		"code":"",
		"description":""
	},
	...
	]
 },
 ...
 ]
}

As shown in the above sample output, the api will provide assigned algorithms list with algorithm's title, key, purpose, icd10 codes i.e. if the code property returns 1 then its outputs will be given under its 'algorithms' property else error messages will be returned through its 'errors' property.

Endpoint : algorithmInfo

Request Method : GET

Purpose : To get the assigned algorithm info

API Request using PHP cURL - an example

copy

 
$url = "http://medicalalgorithms.com/api/v1/algorithmInfo";
$curl = curl_init($url);
curl_setopt($curl, CURLOPT_HEADER, false);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
curl_setopt($curl, CURLOPT_HTTPHEADER,
 array(
 "Content-type: application/json",
 "X-Api-Key:API-KEY",
 "X-Algo-Key:"
 )
 );
$json_response = curl_exec($curl);
 $status = curl_getinfo($curl, CURLINFO_HTTP_CODE);
 curl_close($curl);
$response = json_decode($json_response, true);

API Response

The API provide results in JSON object containing the Algorithm's basic Information, inputs, output variables

A sample API response is shown as follows :

copy


{
"code":1,
"error":"No rrror",
"algorithm":[
{
	"title":"",
	"algorithm_key":"",
	"created":"",
	"purpose":"",
	"icd_codes":[
	{
		"code":"",
		"description":""
	},
	...
	],
	"input_variables":[
	{
		"variable_name":"",
		"data_type":"",
		"option":[...],
		"option_info":"",
		"description":"",
		"absurd_range":[min, max],
		"extreme_range":[min, max],
		"ehr_codes":[...]
	},
	...
	],
	"output_variables":[
	{
		"variable_name":"",
		"description":"",
		"default_value":"",
		"possible_values":""
	},
	...
	]
},
...
]
}

As shown in the above sample output, the api will provide assigned algorithm basic info with algorithm input & output variables i.e. if the code property returns 1 then its outputs will be given under its 'algorithm' property else error messages will be returned through its 'errors' property.

Endpoint : process_algo

Request Method : POST

Purpose : To execute individual algorithm

API Request using PHP cURL - an example

copy

 
	$url = "http://medicalalgorithms.com/api/v1/process_algo";
	$input_variables = array(
	"ivar1"=>"value",
	"ivar2"=>"value",
	"ivar3"=>"value",
	"ivar4"=>"value",
	....
	);
	$content = json_encode($input_variables);
	$curl = curl_init($url);
	curl_setopt($curl, CURLOPT_HEADER, false);
	curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
	curl_setopt($curl, CURLOPT_HTTPHEADER,
	array(
	"Content-type: application/json",
	"X-Api-Key:API-KEY",
	"X-Algo-Key:",
	)
	);
	curl_setopt($curl, CURLOPT_POST, true);
	curl_setopt($curl, CURLOPT_POSTFIELDS, $content);
	$json_response = curl_exec($curl);
	$status = curl_getinfo($curl, CURLINFO_HTTP_CODE);
	curl_close($curl);
	$response = json_decode($json_response, true);

API Response

The API provide results in JSON object containing the Algorithm's basic Information, provided inputs, generated output variables & error messages if applicable.

A sample API response is shown as follows :

copy


{
"algorithm_info": {
"title": "Guidelines for When to Call Pediatrician About Febrile Child"
},
"inputs": {
"ivar1": "yes",
"ivar2": 1,
"ivar3": "no",
"ivar4": 38,
...
"ivar17": "mild"
},
"results": {
"status": "success",
"errors": null,
"outputs": {
"ovar1": "yes",
"ovar2": "yes",
"ovar3": "3",
"ovar4": "yes"
},
"links": [{
"label":"Document and References"
"url":"https://www.medicalalgorithms.com/..."
}],
"next_steps_algorithms":[
{
	"algorithm_key":"",
	"title":"",
	"purpose":"",
	"category":"",
	"sub_category":""
}
...
]
}
}

As shown in the above sample output, the api will provide algorithm's basic info, provided inputs and the algorithm's output details will find under results section depending upon the status property i.e. if the status property returns 'success' then its outputs will be given under its 'outputs' property else error messages will be returned through its 'errors' property.

Output for success response

copy


{
	"algorithm_info" : {
	"title" : Risk Factors of Calligaro et al for Pulmonary Complications Following Elective Surgery on the Abdominal Aorta
	},												
	"input" : {
    "ivar1": "value",
    "ivar2": "value",
    "ivar3": "value",
    "cf_ivar3": "value",
    "ivar4": "value",
    "cf_ivar4": "value",
    "ivar5": "value",
    "ivar6": "value",
    "ivar7": "value",
    "ivar8": "value",
    "ivar9": "value"
},
	"results": {
		"error": "No error",
		"code": 1,
		"outputs": {
				"ovar1": {
				"value": "value",
				"unit_label": "unit",
				"description": "data complete?"
			}
		"ovar2": {
				"value": "value",
				"unit_label": "unit",
				"description": "evaluation appropriate?"
			}
		"ovar3": {
				"value": "value",
				"unit_label": "unit",
				"description": "number of risk factors for pulmonary complications in a patient undergoing elective surgery on the abdominal aorta"
			}
		"ovar4": {
				"value": "value",
				"unit_label": "unit",
				"description": "The patient may be at"
			}
		},
		"links": [{
			"label":"Document and References"
			"url":"https://www.medicalalgorithms.com/..."
		}],
		"next_steps_algorithms":[
		{
			"algorithm_key":"",
			"title":"",
			"purpose":"",
			"category":"",
			"sub_category":""
		}
		...
		]
	}
}

Output for failure response

copy


{
	"algorithm_info" : {
	"title" : Risk Factors of Calligaro et al for Pulmonary Complications Following Elective Surgery on the Abdominal Aorta
	},												
	"input" : {
    "ivar1": "value",
    "ivar2": "wrong value",
    "ivar3": "value",
    "cf_ivar3": "value",
    "ivar4": "value",
    "cf_ivar4": "value",
    "ivar5": "value",
    "ivar6": "value",
    "ivar7": "value",
    "ivar8": "value",
    "ivar9": "value"
},
	"results": {
		"error": {
			"ivar2" : "error message"
		},
		"code": 0,
		"outputs": {
				"ovar1": {
				"value": "complete data",
				"unit_label": "",
			}
			"ovar2": {
				"value": "complete data",
				"unit_label": "",
			}
			"ovar3": {
				"value": "complete data",
				"unit_label": "",
			}
			"ovar4": {
				"value": "complete data",
				"unit_label": "",
			}
		}
	}
}

Errors

List of all the errors messages.

Type	Description	Example
Required	A value was not passed in on the request.	"error": {"ivar2" : "this field is required"}
Out of range	A value was passed is out of range	"error": {"ivar10" : "this field must be greater than '20' and less than '50'"}
Character (Maximum Length)	String length is out of range	"error": {"ivar2" : "this field can have maximum 20 character"}
Integer Or Numeric	A value was passed is not integer or numeric	"error": {"ivar2" : "this field must be a integer", "ivar4" : "this field must be a numeric"}
Not equal to	A value passed in did not meet validation requirements.	"error": {"ivar3" : "this field must not equal to Zero"}
Possible value	A value passed is not match with the possible values	"error": {"ivar7" : "this value is not in list"}
Date format	Invalid date format	"error": {"ivar6" : "this field must be in the format mm/dd/yyyy"}

HTTP response codes:

Status Code	Description
200	Ok
400	Bad Request. Possibly missing API-key or algorithm key
401	Unauthorized/Invalid API-key
500	Internal Server Error

API Documentation

Welcome to the Medal API Center

Introduction

Api URL

HTTP Request method and Authentication

API Endpoints:

Request Method : GET

Purpose : To get the assigned algorithms list

API Request using PHP cURL - an example

API Response

Request Method : GET

Purpose : To get the assigned algorithm info

API Request using PHP cURL - an example

API Response

Request Method : POST

Purpose : To execute individual algorithm

API Request using PHP cURL - an example

API Response

Output for success response

Output for failure response

Errors

HTTP response codes: