Skip to content

NCICTAPI User Manual

Jump to bottom
NCI Dose Team edited this page May 3, 2026 · 7 revisions

NCICT API 4.20260502

Endpoint:

POST https://ncict-xxxxx.xxxxx.xxx/param
Content-Type: application/json

The domain name and cloud server will be configured once the commercial licensing agreement is executed.

For local testing:

POST http://localhost:8080/param
Content-Type: application/json

JSON Input

The API accepts one JSON object per request. GUI Batch uses CSV format, but the calculation parameters are the same as the API JSON parameters. The input does not require a dose_target; NCICT infers it from age and height.

Recommended parameter order:

age, sex, height, weight, wed, start, end, kvp, tcm_strength, head_body, ctdivol, custom_ma
parameter required definition
age yes Patient age in years, or gestational age as week text: 8wk, 10wk, 15wk, 20wk, 25wk, 30wk, 35wk, or 38wk.
sex required for year-based age Patient sex. Use f or m.
height optional Patient height in cm. For week-based age, any supplied height value selects mother dose; blank height selects fetus dose.
weight optional Patient weight in kg. Used for closest patient phantom matching when available.
wed optional Water equivalent diameter in cm. Used for closest patient phantom matching when available.
start yes Scan start location from the top of the head in cm, or an anatomical landmark ID from 1001 to 1010.
end yes Scan end location from the top of the head in cm, or an anatomical landmark ID from 1001 to 1010.
kvp yes Tube potential in kVp.
tcm_strength yes Tube current modulation strength from 0 to 1. Use -1 when providing custom_ma.
head_body yes CTDI phantom selection. Use 1 for 16-cm CTDI phantom and 2 for 32-cm CTDI phantom.
ctdivol yes Volumetric CT dose index in mGy.
custom_ma required when tcm_strength = -1 Array of slice-specific mA values. Each value must be greater than 0.

Phantom Selection Rules

NCICT automatically determines the dose target and phantom group:

case input selection
1 age in years, sex Patient dose using age/sex reference matching
2 age in years, sex, wed Patient dose using WED-based body size matching
3 age in years, sex, height, weight Patient dose using height/weight body size matching
4 age in weeks, blank height Fetus dose
5 age in weeks, any height value Mother dose

Age < 20 is treated as pediatric for patient dose. Age >= 20 is treated as adult.

WED-based Phantom Matching

When age, sex, and wed are provided for patient dose, NCICT first determines the patient phantom group from age and sex:

  • age < 20 and sex = f: pediatric female
  • age < 20 and sex = m: pediatric male
  • age >= 20 and sex = f: adult female
  • age >= 20 and sex = m: adult male

For WED-based matching, NCICT uses the scan range to determine the anatomical region. WED-based matching is applied when start and end match one of the supported landmark ranges:

Region start end
Chest 1004 1007
Abdomen 1006 1008
Pelvis 1008 1009
AP 1006 1009
CAP 1004 1009

NCICT then estimates a target body weight from WED using region-, age-, and sex-specific regression equations. A fixed target height is assigned from the age/sex group:

Group Target height
age < 1 year 47 cm
1 <= age < 5 years 76 cm
5 <= age < 10 years 115 cm
10 <= age < 15 years 145 cm
15 <= pediatric age < 20 years 165 cm
adult female 165 cm
adult male 175 cm

The estimated target weight is limited to the available body size range, and NCICT selects the closest available size-dependent phantom within the same phantom group. The closest phantom is determined by minimizing:

|target height - phantom height| + |target weight - phantom weight|

If the scan range does not match one of the supported WED landmark ranges, NCICT falls back to age/sex-based matching using internally estimated reference height and weight.

Landmark IDs

start and end can be entered either as scan locations in cm or as anatomical landmark IDs, as shown below. If one value is a landmark ID, the other must also be a landmark ID.

Anatomical landmark IDs

Common protocol ranges can be entered using the following landmark ID pairs:

Protocol Start landmark ID End landmark ID
Head 1001 1003
Neck 1002 1005
Chest 1004 1007
Abdomen 1006 1008
Pelvis 1008 1009
Abdomen-pelvis 1006 1009
Chest-abdomen-pelvis 1004 1009
Whole body 1001 1010

After landmark conversion, the scan range must satisfy:

0 <= start < end <= 190

Example 1: Age and Sex

{
  "age": 10,
  "sex": "f",
  "start": 0,
  "end": 20,
  "kvp": 120,
  "tcm_strength": 0,
  "head_body": 1,
  "ctdivol": 20
}

Example 2: Age, Sex, and WED

{
  "age": 10,
  "sex": "f",
  "wed": 25,
  "start": 0,
  "end": 20,
  "kvp": 120,
  "tcm_strength": 0,
  "head_body": 1,
  "ctdivol": 20
}

Example 3: Age, Sex, Height, and Weight

{
  "age": 20,
  "sex": "m",
  "height": 175,
  "weight": 80,
  "start": 0,
  "end": 20,
  "kvp": 120,
  "tcm_strength": 0,
  "head_body": 2,
  "ctdivol": 20
}

Example 4: Fetus Dose

{
  "age": "38wk",
  "start": 1004,
  "end": 1009,
  "kvp": 120,
  "tcm_strength": 0,
  "head_body": 2,
  "ctdivol": 20
}

Example 5: Mother Dose

Any supplied height value with week-based age selects mother dose. The pregnant phantom library uses a matched height of 164 cm.

{
  "age": "30wk",
  "height": 164,
  "start": 1004,
  "end": 1009,
  "kvp": 120,
  "tcm_strength": 0,
  "head_body": 2,
  "ctdivol": 20
}

Custom mA Example

When tcm_strength is -1, custom_ma is required.

{
  "age": 10,
  "sex": "f",
  "wed": 25,
  "start": 0,
  "end": 20,
  "kvp": 120,
  "tcm_strength": -1,
  "head_body": 1,
  "ctdivol": 20,
  "custom_ma": [100, 200, 300, 400, 500, 600, 700]
}

JSON Output

Successful responses return HTTP 200 and a JSON object containing inferred dose target, matched phantom information, and organ doses.

metadata key definition
dose_target Inferred dose target: patient, fetus, or mother.
age Patient age in years, or gestational age such as 38wk.
sex Patient sex for patient dose.
phantom_group Matched phantom group.
wed_cm Input WED in cm, or -1 when WED was not provided.
matched_height_cm Matched phantom height in cm.
matched_weight_kg Matched phantom weight in kg for patient dose.
matched_fetal_age_weeks Matched gestational age in weeks for fetus or mother dose.

Dose values are returned as strings formatted to two decimal places. Output dose keys include organ doses in mGy and effective dose msv in mSv.

Error Responses

Invalid requests return HTTP 400 with an error message. Common validation errors include:

  • missing required input
  • missing or invalid sex for year-based age
  • invalid pregnant phantom age format
  • invalid kvp, tcm_strength, head_body, or ctdivol
  • mixed scan range format, such as one landmark ID and one cm location
  • invalid scan range after landmark conversion
  • missing or invalid custom_ma when tcm_strength = -1

Server-side calculation or installation problems return HTTP 500 with an error message.

Clone this wiki locally