API Dokumentation

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

Ziel dieser API ist es, den online Parodontalstatus aus externen Anwendungen (z. B. Zahnarztpraxis-Software) heraus aufrufbar zu machen. Über einen generierten Link, der beispielsweise hinter einem Button oder einem QR-Code hinterlegt sein kann, werden anonymisierte Befunddaten übergeben und auf www.parodontalstatus.ch/api/ direkt im Viewer visualisiert.

1. Basis-URL

Die API ist über die folgende URL erreichbar:

https://www.parodontalstatus.ch/api/

2. Query-String-Parameter

Der Query-String wird über den Parameter i übermittelt. Dieser enthält die anonymisierten und komprimierten Daten des online Parodontalstatus.

Ein vollständiges Beispiel einer URL lautet:

https://www.parodontalstatus.ch/api/?i=5051505050...

3. Datenstruktur

Die API erwartet die Daten in einer vorgegebenen Reihenfolge.

4. Anfangsbefund oder Reevaluation

Für jeden Parodontalstatus gibt es die Möglichkeit, den Befund als Anfangsbefund oder als Reevaluationsbefund zu kennzeichnen:

Anfangsbefund

  • Parameter: initial_exam
  • Beschreibung: Anfangsbefund
  • Wert: Zahl (1 = Anfangsbefund, 0 = kein Anfangsbefund oder keine Angabe)

Reevaluationsbefund

  • Parameter: reevaluation
  • Beschreibung: Befund nach einer Therapie
  • Wert: Zahl (1 = Reevaluationsbefund, 0 = kein Reevaluationsbefund oder keine Angabe)

5. Zahnreihenfolge

Die auf die Zähne bezogenen Daten müssen in folgender Reihenfolge geliefert werden:

1. Oberkiefer rechts bis Mitte

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

2. Oberkiefer links bis Mitte

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

3. Unterkiefer links bis Mitte

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

4. Unterkiefer rechts bis Mitte

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

6. Parameter für jeden Zahn

Für jeden Zahn gibt es folgende Parameter:

1. Zahnstatus

  • Parameter: tooth_<Zahnnr>
  • Beschreibung: Status des Zahns
  • Wert: Zahl (0 = nicht vorhanden, 1 = vorhanden)

2. Mobilität

  • Parameter: mobility_<Zahnnr>
  • Beschreibung: Grad der Zahnbeweglichkeit
  • Wert: Zahl (0 = keine Mobilität, 1 = leicht, 2 = mittel, 3 = schwer)

3. Furkationsbefunde

  • Parameter: furcation_<Zahnnr>_<Ort> (z. B. furcation_18_dp)
  • Beschreibung: Furkationsbefunde (Betroffenheit der Wurzelgabelung)
  • Stellen für Molaren im Oberkiefer:
    • b (buccal)
    • dp (distopalatal)
    • mp (mesiopalatal)
  • Stellen für erste Prämolaren im Oberkiefer:
    • dp (distopalatal)
    • mp (mesiopalatal)
  • Stellen für Molaren im Unterkiefer:
    • b (buccal)
    • l (lingual)
  • Wert: Zahl (0 = keine Furkation, 1 = Grad I, 2 = Grad II, 3 = Grad III)

4. Implantatstatus

  • Parameter: implant_<Zahnnr>
  • Beschreibung: Status eines Implantats
  • Wert: Zahl (0 = kein Implantat, 1 = Implantat vorhanden (grau), 2 = Implantat vorhanden (rot), 3 = Implantat vorhanden (grün))

5. Blutung auf Sondierung (BoP)

  • Parameter: bop_<Zahnnr>_<Ort> (z. B. bop_18_db, bop_18_b)
  • Beschreibung: Blutung auf Sondierung an den Stellen:
  • Oberkiefer:
    • db (distobuccal)
    • b (buccal)
    • mb (mesiobuccal)
    • dp (distopalatal)
    • p (palatinal)
    • mp (mesiopalatal)
  • Unterkiefer:
    • db (distobuccal)
    • b (buccal)
    • mb (mesiobuccal)
    • dl (distolingual)
    • l (lingual)
    • ml (mesiolingual)
  • Wert: Zahl (0 = keine Blutung, 1 = Blutung)

6. Plaqueindex (PI)

  • Parameter: pi_<Zahnnr>_<Ort> (z. B. pi_18_db, pi_18_b)
  • Beschreibung: Plaqueindex an den gleichen Stellen wie bei BoP
  • Wert: Zahl (0 = kein Plaque, 1 = Plaque)

7. Gingivahöhe (Rezession, GM)

  • Parameter: gm_<Zahnnr>_<Ort> (z. B. gm_18_db, gm_18_b)
  • Beschreibung: Abstand der Gingiva zur Referenz (z. B. Zahnhals)
  • Wert: Zahl (in Millimetern)

8. Sondierungstiefen (PD)

  • Parameter: pd_<Zahnnr>_<Ort> (z. B. pd_18_db, pd_18_b)
  • Beschreibung: Sondierungstiefen an den gleichen Stellen wie GM
  • Wert: Zahl (in Millimetern)

7. Gesamt-Reihenfolge der Parameter

Wichtig: Die Furkationen werden nur bei den Molaren und den Zähnen 14 und 24 erwartet.

Beispiel: Zahn 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

Wiederholung für die weiteren Zähne in derselben Reihenfolge.

8. Konvertierung in den Zahlen-String

  1. Erfassen Sie alle Parameterwerte in der oben definierten Reihenfolge.
  2. Konvertieren Sie jeden Wert in eine zweistellige Zahl (z. B. 1 → 01, 0 → 00).
  3. Fügen Sie zu jedem Wert 50 hinzu (Offset).
  4. Verbinden Sie die Werte ohne Trennzeichen zu einer einzigen Zeichenkette.

Beispiel-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. Validierung

✓ Die gesamte Zeichenkette umfasst nur die Ziffern 0 bis 9.
✓ Die gesamte Zeichenkette umfasst genau 1800 Ziffern.
✓ Der Offset von +50 wurde korrekt angewendet.

10. Beispiel

Angenommen, die folgenden Werte für Zahn 18:

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

Nach Formatierung und Offset:

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

Ergebnis:

https://www.parodontalstatus.ch/api/?i=515052...

11. Vollständiges Beispiel

Wichtig: Die ersten vier Ziffern 5150 bedeuten 0100, d.h. Anfangsbefund.

Kompletter API-Link

https://www.parodontalstatus.ch/api/?i=515050505050505050505050505050505050505050505050505050505050505050505050505050505050505050505050505050505050505050505050505051505151515051505150505151515151515149505055535350495054535551505051515151515151515151515149505055525350505055535451505050505151515151515151515151515050515453555050505553565151505151515150505151515151515150515753535050515753545151505151515050505151515151515152515458535253535656565151505151515051515151515151515052505653565051515756575050505050505050505050505050505050505050505050505050505050505150515252505151515151515151515151515050505553545049496059545151515151505151515151515151515151514950505453565047505659565151505151515051515151515151515050505657535049505753555151505050515151515151515151515151505051595357504950565457515150515151515151515151515151505050585253504950585853515150515151515151515151515151505050535253505151545453515150515151505050515151515151515151535355505150535355505050505050505050505050505050505050505050505050505050505051505152505151515151515151515151515050505555595150505658575150515250515151515151515151515151505050605454495049615954515050515151515151515151515151505050535354495050535354515050515151515150515151515151505050555353505050565455515050515151505150515151515151505149535455504948555554515250515151515050515151515151454645555253454544535353515250515151505150515151515151474946535353454645535354505050505050505050505050505050505050505050505050505050505051505152505151515151515151515151515149495652534950495654545151515150515151515151515151515151495151575353495050575454515050515151515151515151515151505050535253505050545353515050515151505051515151515151505050535453505050545353515050515051515151515151515151515149535555495048555555515250515151505151515151515151475048555255474848555454515250515151505051515151515151484948555453474646555656

Live-Beispiel

Klicken Sie auf den Link, um das Beispiel im API-Viewer zu öffnen:

Beispiel im API-Viewer öffnen →

Scannen Sie den folgenden QR-Code, um das Beispiel im API-Viewer zu öffnen:

QR Code

Parameter-Array (zur Veranschaulichung)

Serverseitig wird dieser Query String in diese Schlüssel übertragen:

["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"]