ECG Basic API

The Basic tier provides core ECG signal analysis capabilities, supporting both single-lead and 12-lead ECG analysis.

Use cases

• Wearable device ECG monitoring
• Health management apps
• Preliminary ECG screening
• Development & test validation

Signal quality guidance

All analysis endpoints return a sqGrade field to indicate signal quality. It is recommended to use results when sqGrade >= 0.7. View detailed signal quality guidance →

---

Single-lead ECG analysis

POST /api/v1/basic/ecg/1-lead/analyze

Analyze a single-lead ECG signal and return diagnosis conclusions and ECG parameters.

Request parameters

Parameter	Type	Required	Description
ecgData	array	✅	ECG signal data array (ADC values)
ecgSampleRate	number	✅	Sampling rate (Hz, recommended 250–500)
adcGain	number	❌	Gain coefficient (default: 1.0)
adcZero	number	❌	Zero/baseline voltage (default: 0.0)

Request example

curl -X POST "https://api.heartvoice.com.cn/api/v1/basic/ecg/1-lead/analyze" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "ecgData": [512, 515, 520, 518, 525, ...],
    "ecgSampleRate": 500,
    "adcGain": 1.0,
    "adcZero": 0.0
  }'

Response example

{
  "errorCode": "0",
  "msg": "success",
  "data": {
    "isAbnormal": false,
    "isReverse": false,
    "sqGrade": "0.95",
    "diagnosis": [
      "SN"
    ],
    "possibleDiags": [],
    "pacCount": 0,
    "pvcCount": 0,
    "avgHr": 73,
    "avgQrs": 94,
    "prInterval": 152,
    "avgQt": 348,
    "avgP": 104,
    "avgQtc": 384
  }
}

---

12-lead ECG analysis

POST /api/v1/basic/ecg/12-lead/analyze

Analyze a standard 12-lead ECG signal to provide more comprehensive ECG diagnosis.

Request parameters

Parameter	Type	Required	Description
dataI	array	✅	Lead I data
dataII	array	✅	Lead II data
dataIII	array	✅	Lead III data
dataAVR	array	✅	Lead aVR data
dataAVL	array	✅	Lead aVL data
dataAVF	array	✅	Lead aVF data
dataV1	array	✅	Lead V1 data
dataV2	array	✅	Lead V2 data
dataV3	array	✅	Lead V3 data
dataV4	array	✅	Lead V4 data
dataV5	array	✅	Lead V5 data
dataV6	array	✅	Lead V6 data
ecgSampleRate	number	✅	Sampling rate (Hz)
adcGain	number	✅	Gain coefficient
adcZero	number	❌	Zero/baseline voltage (default: 0.0)

Request example format

{
  "dataI": [512, 515, 520, ...],
  "dataII": [510, 518, 522, ...],
  "dataIII": [508, 512, 515, ...],
  "dataAVR": [520, 518, 515, ...],
  "dataAVL": [515, 520, 518, ...],
  "dataAVF": [510, 515, 520, ...],
  "dataV1": [512, 518, 525, ...],
  "dataV2": [515, 520, 528, ...],
  "dataV3": [518, 525, 530, ...],
  "dataV4": [520, 528, 535, ...],
  "dataV5": [522, 530, 538, ...],
  "dataV6": [525, 532, 540, ...],
  "ecgSampleRate": 500,
  "adcGain": 1000.0,
  "adcZero": 0.0
}

Request example

curl -X POST "https://api.heartvoice.com.cn/api/v1/basic/ecg/12-lead/analyze" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d @ecg_12lead_data.json

Response example

{
  "errorCode": "0",
  "msg": "success",
  "data": {
    "id": "2008115544300990464",
    "analysisState": true,
    "diagnoses": [
      {
        "label": "SN",
        "result": "Sinus rhythm",
        "description": "P wave: I & II upright, aVR inverted, V5 & V6 upright"
      }
    ],
    "riskLevel": 0,
    "HR": 73,
    "QRSaxis": 240,
    "P": 90,
    "PR": 125,
    "QRS": 126,
    "QT": 377,
    "QTc": 416,
    "T": 163,
    "SV1": -0.86,
    "SV2": -0.86,
    "SV5": -0.86,
    "RV1": 0.59,
    "RV2": 0.59,
    "RV5": 0.59,
    "RV6": 0.59,
    "Paxis": 60,
    "Taxis": 60,
    "AtrialRate": 74,
    "VentricularRate": 72
  }
}

12-lead diagnosis label guidance

• The label field is the diagnosis label code. Convert it using the Diagnosis label reference table.
• The result field is the diagnosis result label (NORMAL/ABNORMAL/BORDERLINE).
• The description field is a detailed description text.

---

Response field descriptions

Single-lead response fields

Field	Type	Description
isAbnormal	boolean	Whether it is abnormal
isReverse	boolean	Whether the lead is reversed/miswired
sqGrade	string	Signal quality grade (numeric string) View detailed guidance
diagnosis	array	List of diagnosis result label codes (codes need mapping)
possibleDiags	array	List of possible diagnosis label codes (candidate codes)
pacCount	number	PAC count (premature atrial contractions)
pvcCount	number	PVC count (premature ventricular contractions)
avgHr	number	Average heart rate (bpm)
avgQrs	number	Average QRS width (ms)
prInterval	number	PR interval (ms)
avgQt	number	Average QT interval (ms)
avgP	number	Average P-wave width (ms)
avgQtc	number	Average QTc interval (ms)

Diagnosis label guidance

The diagnosis and possibleDiags fields return diagnosis label codes. Convert them using the mapping table below (Diagnosis label reference table).

12-lead response fields

Field	Type	Description
id	string	Data ID
analysisState	boolean	Analysis status
diagnoses	array	Array of diagnosis result objects
HR	number	Heart rate (bpm)
QRSaxis	number	QRS electrical axis (degrees)
P	number	P-wave width (ms)
PR	number	PR interval (ms)
QRS	number	QRS width (ms)
QT	number	QT interval (ms)
QTc	number	QTc interval (ms)
T	number	T-wave width (ms)
SV1/SV2/SV5	number	S-wave voltage
RV1/RV2/RV5/RV6	number	R-wave voltage
Paxis	number	P-wave electrical axis (degrees)
Taxis	number	T-wave electrical axis (degrees)
AtrialRate	number	Atrial rate (bpm)
VentricularRate	number	Ventricular rate (bpm)
riskLevel	number	Risk level: 0 none, 1 low, 2 medium, 3 high

diagnoses object structure (12-lead)

Field	Type	Description
label	string	Diagnosis label code (see Diagnosis label reference table)
result	string	Diagnosis result label (corresponding Chinese label in the original doc)
description	string	Detailed description text

Reference ranges for ECG parameters

Parameter	Normal range	Description
HR (heart rate)	60–100 bpm	Heart rate
QRS width	80–120 ms	QRS width
QTc interval	350–440 ms	Corrected QT interval
PR interval	120–200 ms	PR interval
QRS electrical axis	-30°–90°	Electrical axis

---

Diagnosis label reference table

Single-lead diagnosis labels

The labels returned by the diagnosis and possibleDiags fields correspond to the following descriptions:

Label code	English description	Notes
SN	Sinus rhythm	Normal rhythm originating from the sinoatrial node
N	Normal ECG	ECG without obvious abnormality
SNA	Irregular sinus rhythm	Sinus rhythm with irregular rhythm, often related to respiration
SNT	Sinus tachycardia	Sinus rhythm with heart rate above the normal range
SNB	Sinus bradycardia	Sinus rhythm with heart rate below the normal range
AF	Atrial fibrillation	Disordered rapid atrial activation with an absolutely irregular rhythm
AFL	Atrial flutter	Regular rapid re-entrant atrial activation
VT	Ventricular tachycardia	Fast rhythm originating from the ventricles; potentially dangerous
SVT	Supraventricular tachycardia	Fast rhythm originating above the ventricles
PVC	Premature ventricular contraction	Premature beats originating in the ventricles
PJC	Junctional premature beat	Premature beat from the AV junction region
PAC	Premature atrial contraction	Premature beat originating in the atrium
AVBI	First-degree atrioventricular block	AV conduction delay, but every impulse is conducted
AVBII	Second-degree atrioventricular block	Not all atrial impulses are conducted to the ventricles
AVBIII	Third-degree atrioventricular block	Complete AV block; atrial and ventricular activity are independent
AE	Atrial escape beat	Protective escape beat appearing with delayed atrial pacing site
IVB	Intraventricular conduction block	Delayed or blocked intraventricular conduction
LBBB	Left bundle branch block	Left bundle branch conduction block causing abnormal ventricular activation
RBBB	Right bundle branch block	Right bundle branch conduction block causing abnormal ventricular activation
LAFB	Left anterior fascicular block	Conduction block in the left anterior fascicle
JE	Junctional escape beat	Escape rhythm originating from the AV junction area
VE	Ventricular escape beat	Escape rhythm originating from the ventricles
LVH	Left ventricular hypertrophy	ECG pattern suggestive of left ventricular hypertrophy
PACED	Paced rhythm	Rhythm generated by an artificial pacemaker
WPW	WPW	Pre-excitation syndrome with an accessory pathway
SINGLE_PAC	Single PAC	Isolated premature atrial contraction
PAIRED_PAC	Paired PAC	Two consecutive premature atrial contractions
BIGEMINY_PAC	Bigeminy PAC	Premature atrial contractions alternate with normal beats
TRIAD_PAC	Trigeminy PAC	One premature atrial contraction appears in every three beats
SINGLE_PVC	Single PVC	Isolated premature ventricular contraction
PAIRED_PVC	Paired PVC	Two consecutive premature ventricular contractions
BIGEMINY_PVC	Bigeminy PVC	Premature ventricular contractions alternate with normal beats
TRIAD_PVC	Trigeminy PVC	One premature ventricular contraction appears in every three beats

12-lead diagnosis labels

Label code	English description	Notes
SN	Sinus rhythm	Normal rhythm originating from the sinoatrial node
N	Sinus rhythm (normal ECG)	Overall ECG presentation is normal
SNA	Irregular sinus rhythm	Sinus rhythm with irregularity, often associated with respiration
SNT	Sinus tachycardia	Sinus rhythm with heart rate above normal range
SNB	Sinus bradycardia	Sinus rhythm with heart rate below normal range
AF	Atrial fibrillation	Disordered rapid atrial activation with absolutely irregular rhythm
PVC	Premature ventricular contraction	Premature beats from the ventricles
PAC	Premature atrial contraction	Premature beats from the atria
AFL	Atrial flutter	Regular rapid re-entrant atrial activation
LVH	Left ventricular high voltage	ECG suggests possible left ventricular hypertrophy
LBBB	Left bundle branch block	Left bundle conduction block causing abnormal ventricular activation
RBBB	Right bundle branch block	Right bundle conduction block causing abnormal ventricular activation
IVB	Intraventricular conduction block	Delayed or blocked conduction inside the ventricles
RBBB_C	Complete right bundle branch block	Complete conduction block
RBBB_I	Incomplete right bundle branch block	Partial conduction block
LAFB	Left anterior fascicular block	Conduction block in the left anterior fascicle
WPW	WPW	Pre-excitation due to an accessory pathway causing early ventricular activation
LGL	LGL syndrome	Pre-excitation syndrome with short PR interval and no delta wave
AVBI	First-degree AV block	AV conduction delay but every impulse is conducted
AVBII	Second-degree AV block	Some atrial impulses cannot conduct to ventricles
AVBIII	Third-degree AV block	Complete AV block; atrial and ventricular activity independent
ST	ST-segment abnormality	Abnormal ST elevation or depression
T	T-wave abnormality	Abnormal T-wave morphology or direction
STT	ST-T abnormality	Abnormalities in both ST segment and T wave
PACED	Paced rhythm	Rhythm generated by an artificial pacemaker
CW	Clockwise rotation	Cardiac electrical axis or waveform rotates clockwise
CCW	Counter-clockwise rotation	Cardiac electrical axis or waveform rotates counter-clockwise
LAD	Left axis deviation	Electrical axis shifts to the left
RAD	Right axis deviation	Electrical axis shifts to the right
ERAD	Marked right axis deviation	Prominent rightward electrical axis shift
BLV	Low limb-lead voltage	Reduced QRS amplitude in limb leads
CLV	Low chest-lead voltage	Reduced QRS amplitude in precordial leads
VT	Ventricular tachycardia	Fast rhythm originating from the ventricles; dangerous
SVT	Supraventricular tachycardia	Fast rhythm originating above the ventricles
Q	Abnormal Q waves	Abnormal Q waves, possibly indicating myocardial necrosis
QT_L	Prolonged Q-Tc interval	Corrected QT prolongation with arrhythmia risk
QRS_L	QRS widening	Prolonged ventricular depolarization time
JE	Junctional escape beat	Escape rhythm from the AV junction
VE	Ventricular escape beat	Escape rhythm from the ventricles
AE	Atrial escape beat	Escape rhythm from the atria
PJC	Junctional premature beat	Early beats from the AV junction region
PAUSE	Asystole	Temporarily interrupted cardiac beats
ALLFALL	Lead loss	Multiple leads are missing or abnormal
LIMBFALL	Limb lead loss	Limb lead signal is missing
CHESTFALL	Chest lead loss	Precordial lead signal is missing

Label guidance

• The label lists above will be continuously updated based on the actual model capability.
• A single analysis may return multiple labels.
• possibleDiags includes possible diagnoses with lower confidence.
• The actual label content is subject to what the API returns.

---

12-lead

---

Next steps

• ECG Advanced API - HRV, heart age and other advanced features
• Authentication - Get API Key
• Usage examples - Complete integration example