API Documentation

Version 2.0 | 19.12.2025 | Author: Prof. Dr. Christoph A. Ramseier

The aim of this API is to make the online Periodontal Chart accessible from external applications (e.g., dental practice software). Via a generated link, which can be stored behind a button or a QR code, anonymized findings data are transferred and visualized directly in the viewer at www.periodontalchart-online.com/api/.

1. Base URL

The API can be reached via the following URL:

https://www.periodontalchart-online.com/api/

2. Query String Parameters

The query string is transmitted via the i parameter. This contains the anonymized and compressed data of the online Periodontal Chart.

A complete example of a URL is:

https://www.periodontalchart-online.com/api/?i=5051505050...

3. Data Structure

The API expects the data in a given order.

4. Initial Examination or Re-evaluation

For each Periodontal Chart, it is possible to mark the finding as an initial examination or as a re-evaluation:

Initial Examination

  • Parameter: initial_exam
  • Description: Initial examination
  • Value: Number (1 = initial examination, 0 = no initial examination or not specified)

Re-evaluation

  • Parameter: reevaluation
  • Description: Finding after a therapy
  • Value: Number (1 = re-evaluation, 0 = no re-evaluation or not specified)

5. Tooth Order

The data related to the teeth must be provided in the following order:

1. Upper jaw right to center

18, 17, 16, 15, 14, 13, 12, 11

2. Upper jaw left to center

28, 27, 26, 25, 24, 23, 22, 21

3. Lower jaw left to center

38, 37, 36, 35, 34, 33, 32, 31

4. Lower jaw right to center

48, 47, 46, 45, 44, 43, 42, 41

6. Parameters for Each Tooth

For each tooth, the following parameters are available:

1. Tooth Status

  • Parameter: tooth_<ToothNo>
  • Description: Status of the tooth
  • Value: Number (0 = missing, 1 = present)

2. Mobility

  • Parameter: mobility_<ToothNo>
  • Description: Degree of tooth mobility
  • Value: Number (0 = no mobility, 1 = slight, 2 = medium, 3 = severe)

3. Furcation Findings

  • Parameter: furcation_<ToothNo>_<Location> (e.g. furcation_18_dp)
  • Description: Furcation findings (involvement of the root bifurcation)
  • Sites for molars in the upper jaw:
    • b (buccal)
    • dp (distopalatal)
    • mp (mesiopalatal)
  • Sites for first premolars in the upper jaw:
    • dp (distopalatal)
    • mp (mesiopalatal)
  • Sites for molars in the lower jaw:
    • b (buccal)
    • l (lingual)
  • Value: Number (0 = no furcation, 1 = Grade I, 2 = Grade II, 3 = Grade III)

4. Implant Status

  • Parameter: implant_<ToothNo>
  • Description: Status of an implant
  • Value: Number (0 = no implant, 1 = implant present (gray), 2 = implant present (red), 3 = implant present (green))

5. Bleeding on Probing (BoP)

  • Parameter: bop_<ToothNo>_<Location> (e.g. bop_18_db, bop_18_b)
  • Description: Bleeding on probing at the following sites:
  • Upper Jaw:
    • db (distobuccal)
    • b (buccal)
    • mb (mesiobuccal)
    • dp (distopalatal)
    • p (palatal)
    • mp (mesiopalatal)
  • Lower Jaw:
    • db (distobuccal)
    • b (buccal)
    • mb (mesiobuccal)
    • dl (distolingual)
    • l (lingual)
    • ml (mesiolingual)
  • Value: Number (0 = no bleeding, 1 = bleeding)

6. Plaque Index (PI)

  • Parameter: pi_<ToothNo>_<Location> (e.g. pi_18_db, pi_18_b)
  • Description: Plaque index at the same sites as BoP
  • Value: Number (0 = no plaque, 1 = plaque)

7. Gingival Margin (Recession, GM)

  • Parameter: gm_<ToothNo>_<Location> (e.g. gm_18_db, gm_18_b)
  • Description: Distance of the gingiva to the reference (e.g., tooth neck)
  • Value: Number (in millimeters)

8. Probing Depths (PD)

  • Parameter: pd_<ToothNo>_<Location> (e.g. pd_18_db, pd_18_b)
  • Description: Probing depths at the same sites as GM
  • Value: Number (in millimeters)

7. Total Order of Parameters

Important: Furcation involvement is expected only for molars and teeth 14 and 24.

Example: Tooth 18

tooth_18
mobility_18
furcation_18_b
furcation_18_dp
furcation_18_mp
implant_18
bop_18_db
bop_18_b
bop_18_mb
bop_18_dp
bop_18_p
bop_18_mp
pi_18_db
pi_18_b
pi_18_mb
pi_18_dp
pi_18_p
pi_18_mp
gm_18_db
gm_18_b
gm_18_mb
pd_18_db
pd_18_b
pd_18_mb
gm_18_dp
gm_18_p
gm_18_mp
pd_18_dp
pd_18_p
pd_18_mp

Repeat for the further teeth in the same order.

8. Conversion to the numerical string

  1. Record all parameter values in the order defined above.
  2. Convert each value to a two-digit number (e.g. 1 → 01, 0 → 00).
  3. Add 50 to each value (offset).
  4. Join the values without separators into a single string.

Example Code (JavaScript)

function encodeValue(value) {
    // Add offset of 50
    const encodedValue = Math.round(value) + 50;
    
    // Pad to 2 digits
    return encodedValue.toString().padStart(2, '0');
}

// Example usage
const tooth_18 = 1;
const mobility_18 = 0;
const furcation_18_b = 2;

const encoded = encodeValue(tooth_18) + 
                encodeValue(mobility_18) + 
                encodeValue(furcation_18_b);

console.log(encoded); // Output: "515052"

9. Validation

✓ The entire string contains only digits 0 to 9.
✓ The entire string contains exactly 1800 digits.
✓ The offset of +50 was correctly applied.

10. Example

Assume the following values for tooth 18:

  • tooth_18 = 1
  • mobility_18 = 0
  • furcation_18_b = 2

After formatting and offset:

  • tooth_18 → 51
  • mobility_18 → 50
  • furcation_18_b → 52

Result:

https://www.periodontalchart-online.com/api/?i=515052...

11. Complete Example

Important: The first four digits 5150 mean 0100, i.e., initial examination.

Complete API link

https://www.periodontalchart-online.com/api/?i=515050505050505050505050505050505050505050505050505050505050505050505050505050505050505050505050505050505050505050505050505051505151515051505150505151515151515149505055535350495054535551505051515151515151515151515149505055525350505055535451505050505151515151515151515151515050515453555050505553565151505151515150505151515151515150515753535050515753545151505151515050505151515151515152515458535253535656565151505151515051515151515151515052505653565051515756575050505050505050505050505050505050505050505050505050505050505150515252505151515151515151515151515050505553545049496059545151515151505151515151515151515151514950505453565047505659565151505151515051515151515151515050505657535049505753555151505050515151515151515151515151505051595357504950565457515150515151515151515151515151505050585253504950585853515150515151515151515151515151505050535253505151545453515150515151505050515151515151515151535355505150535355505050505050505050505050505050505050505050505050505050505051505152505151515151515151515151515050505555595150505658575150515250515151515151515151515151505050605454495049615954515050515151515151515151515151505050535354495050535354515050515151515150515151515151505050555353505050565455515050515151505150515151515151505149535455504948555554515250515151515050515151515151454645555253454544535353515250515151505150515151515151474946535353454645535354505050505050505050505050505050505050505050505050505050505051505152505151515151515151515151515149495652534950495654545151515150515151515151515151515151495151575353495050575454515050515151515151515151515151505050535253505050545353515050515151505051515151515151505050535453505050545353515050515051515151515151515151515149535555495048555555515250515151505151515151515151475048555255474848555454515250515151505051515151515151484948555453474646555656

Live Example

Click on the link to open the example in the API viewer:

Open example in API viewer →

Scan the following QR code to open the example in the API viewer:

QR Code

Parameter Array (for illustration)

On the server side, this query string is transferred to these keys:

["initial_exam", "reevaluation",
"tooth_18", "mobility_18", "furcation_18_b", "furcation_18_dp", "furcation_18_mp", "implant_18",
"bop_18_db", "bop_18_b", "bop_18_mb", "pi_18_db", "pi_18_b", "pi_18_mb",
"bop_18_dp", "bop_18_p", "bop_18_mp", "pi_18_dp", "pi_18_p", "pi_18_mp",
"gm_18_db", "gm_18_b", "gm_18_mb", "pd_18_db", "pd_18_b", "pd_18_mb",
"gm_18_dp", "gm_18_p", "gm_18_mp", "pd_18_dp", "pd_18_p", "pd_18_mp",
"tooth_17", "mobility_17", "furcation_17_b", "furcation_17_dp", "furcation_17_mp", "implant_17",
...
"tooth_41", "mobility_41", "implant_41",
"bop_41_db", "bop_41_b", "bop_41_mb", "pi_41_db", "pi_41_b", "pi_41_mb",
"bop_41_dl", "bop_41_l", "bop_41_ml", "pi_41_dl", "pi_41_l", "pi_41_ml",
"gm_41_db", "gm_41_b", "gm_41_mb", "pd_41_db", "pd_41_b", "pd_41_mb",
"gm_41_dl", "gm_41_l", "gm_41_ml", "pd_41_dl", "pd_41_l", "pd_41_ml"]