MIRACLE is an open-source API that provides evidence-based reference values for cardiovascular magnetic resonance (CMR) measurements. It standardizes the interpretation of CMR studies by offering instant access to peer-reviewed normal ranges, z-scores, and percentiles across multiple clinical domains.
🔗 View and Test Full API Documentation: miracleapi.readme.io
-
Pediatric CMR Reference Calculator: miracle-app.surge.sh
-
Interactive Chatbot: miracle-chat.netlify.app
- 📊 Evidence-based reference values
- 🔓 Open-access API
- 🏥 Multiple clinical domains
- 🧮 Real-time z-score calculations
- 📈 Percentile computations
- 🤖 AI/LLM integration ready
- 📱 REST API with flexible endpoints
curl --request GET \
--url 'https://ref.miracle-api.workers.dev/exec?domain=Pediatric_Ventricle¶meter=LVEDV&gender=Male' \
--header 'accept: application/json'Python
import requests
url = "https://ref.miracle-api.workers.dev/exec?domain=Pediatric_Ventricle¶meter=LVEDV&gender=Male"
headers = {"accept": "application/json"}
response = requests.get(url, headers=headers)
print(response.text)JavaScript
const options = {method: 'GET', headers: {accept: 'application/json'}};
fetch('https://ref.miracle-api.workers.dev/exec?domain=Pediatric_Ventricle¶meter=LVEDV&gender=Male', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));| Left Ventricle | Volumetric | Volumetric by Age | Functional and Geometric | Myocardial Thickness |
|---|---|---|---|---|
| Global Strain | Fractal Dimension by BMI | Fractal Dimension by Ethnicity | ||
| Right Ventricle | Volumetric | Volumetric by Age | ||
| Left Atrium | Diameter & Area | Volume & Function | ||
| Right Atrium | Diameter & Area | Volume & Function | ||
| Other | Athletes | T1/ECV | T2 Relaxation | Myocardial Blood Flow |
| Aortic Root & Valve | Ascending Aorta | Thoraco-Abdominal Aorta | Aortic Elasticity | Pulmonary Artery |
|---|---|---|---|---|
| Aortic Root Diameter | Ascending Aortic Diameter | Thoraco-Abdominal Aorta Diameter | Aortic Distensibility by Age | Adult Pulmonary Artery Dimensions |
| Aortic Sinus Diameters and Area | Ascending Aorta Peak Velocity by Age | Aortic PWV by Age | ||
| Aortic Valve Peak Velocity |
| Cardiac | Vascular |
|---|---|
| Atrial Volumes | Aortic CSA |
| Ventricular Parameters | Ascending Aorta Distensibility |
| Pulse Wave Velocity | |
| Aortic Diameter | |
| Pulmonary Artery Diameters |
Full documentation available at miracleapi.readme.io
-
Pediatric CMR Z-score Calculator Web App
- React-based frontend with Material-UI components
- Real-time validation and calculation
- RESTful API integration with error handling
- Mobile-responsive design
- Print support
- Live Demo | Source Code
-
Virtual CMR Report Generator
- Batch processing of multiple parameters
- Customizable report templates using Handlebars
- Export options: PDF, DOCX, JSON
- Integration examples with clinical systems
// Example report generation const report = await miracleAPI.generateReport({ patient: { gender: "Male", height: 110, weight: 22 }, measurements: { LVEDV: 62, LVEF: 60, LVM: 45 }, template: "pediatric_standard" });
-
LLM-Powered Chatbot
- OpenAI/Groq function calling architecture
- Natural language parsing with structured output
- Context-aware conversation handling
- Error boundary implementation
- Live Demo | Source Code
// Example function calling schema { "name": "getPediatricVentricleZScore", "parameters": { "type": "object", "properties": { "gender": { "type": "string", "enum": ["Male", "Female"] }, "parameter": { "type": "string", "enum": ["LVEDV", "LVEF", "LVM"] }, "measured": { "type": "number" }, "ht_cm": { "type": "number" }, "wt_kg": { "type": "number" } } } }
- Structured markdown format at
/llms.txt - Automated updates via GitHub Actions
- Endpoint schemas in OpenAPI 3.0
curl https://miracleapi.readme.io/llms.txt
# Returns markdown-formatted documentation- OpenAPI specification at
/mcp - JSON Schema validation
- Rate limiting information
- Authentication requirements
- Read Documentation
curl https://miracleapi.readme.io/mcp
# Returns OpenAPI specification- OpenAI-compatible function definitions
- Anthropic Claude-ready schemas
- Groq API integration examples
- Error handling patterns
# Example function registration with OpenAI
tools = [{
"type": "function",
"function": {
"name": "getPediatricReferenceValues",
"description": "Get z-scores for pediatric CMR measurements",
"parameters": { ... }
}
}]# Example: Basic batch processing with current API
import pandas as pd
import requests
def process_cmr_data(data_df):
base_url = "https://ref.miracle-api.workers.dev/exec"
results = []
for _, row in data_df.iterrows():
params = {
"domain": "Pediatric_Ventricle",
"parameter": row["parameter"],
"gender": row["gender"],
"measured": row["value"],
"ht_cm": row["height"],
"wt_kg": row["weight"]
}
response = requests.get(base_url, params=params)
results.append(response.json())
return pd.DataFrame(results)
# Usage
df = pd.read_csv("measurements.csv")
results_df = process_cmr_data(df)
results_df.to_csv("results_with_zscores.csv")- DICOM SR templates
- REDCap integration
- Data validation suite
The official Python SDK is now available for batch processing and research workflows.
Installation:
pip install miracle-sdkUsage:
from miracle import Miracle, MiracleBatch
# Single request
client = Miracle()
result = client.pediatric_ventricle_reference_values(
parameter="LVEDV",
gender="Male",
measured=62.5,
ht_cm=110,
wt_kg=22
)
print(result)
# Batch processing (parallel, high-performance)
processor = MiracleBatch(max_workers=10)
df_results = processor.process_csv(
file_path="patients.csv",
domain="Pediatric_Ventricle",
mapping={"gender": "gender", "ht_cm": "height_cm", ...}
)
df_results.to_csv("results_with_zscores.csv")📦 PyPI: pypi.org/project/miracle-sdk | GitHub: github.com/drankush/MIRACLE-sdk
@software{Ankush_MIRACLE_2025,
author = {Ankush, Ankush},
title = {MIRACLE: MR Imaging Reference API for Cardiovascular Limits from Evidence},
year = {2025},
publisher = {GitHub},
url = {https://github.com/drankush/MIRACLE-API}
}MIT License - See LICENSE for details