ArztAPI logo

ArztAPI API-Referenz

Willkommen bei ArztAPI! Diese Dokumentation bietet einen umfassenden Leitfaden, um unsere GraphQL-API effektiv zu nutzen und auf aktuelle, strukturierte Daten zu Gesundheitsdienstleistern und Einrichtungen in Deutschland zuzugreifen.

Erste Schritte

1. API-Schlüssel erhalten

Um die ArztAPI zu nutzen, benötigen Sie einen API-Schlüssel. API-Schlüssel werden verwendet, um Ihre Anfragen zu authentifizieren und Ihre Nutzung zu verfolgen.

Sie können einen API-Schlüssel erhalten, indem Sie sich auf unserer Plattform unter arztapi.de/signup anmelden (Hinweis: Der Link ist ein Platzhalter für die tatsächliche Anmeldeseite).

Nach der Registrierung finden Sie Ihren API-Schlüssel in Ihrem Konto-Dashboard. Bitte halten Sie Ihren API-Schlüssel vertraulich.

2. API-Endpunkt

Alle API-Anfragen müssen an den folgenden GraphQL-Endpunkt gesendet werden:

https://api.arztapi.com/functions/v1/api-gateway

3. Authentifizierung

Authentifizieren Sie Ihre API-Anfragen, indem Sie Ihren API-Schlüssel im x-api-key-HTTP-Header übermitteln.

Beispiel:

x-api-key: YOUR_API_KEY

Ersetzen Sie YOUR_API_KEY durch den tatsächlichen API-Schlüssel, den Sie erhalten haben.

Anfragen stellen

Die ArztAPI verwendet GraphQL. Alle Anfragen müssen als POST-Anfragen mit einem JSON-Body an den API-Endpunkt gesendet werden.

Der JSON-Body muss ein Feld query enthalten und kann optional ein Feld variables enthalten, wenn Ihre Abfrage Variablen verwendet.

Beispielanfrage mit cURL:


      curl --location 'https://api.arztapi.com/functions/v1/api-gateway' \
      --header 'x-api-key: YOUR_API_KEY' \
      --header 'Content-Type: application/json' \
      --data '{
        "query": "query GetFirstProfessional { professionalsCollection(first: 1) { edges { node { id first_name last_name title } } } }",
        "variables": {}
      }'

Denken Sie daran, YOUR_API_KEY durch Ihren tatsächlichen API-Schlüssel zu ersetzen.

GraphQL verstehen

Wenn Sie neu bei GraphQL sind, finden Sie hier einige grundlegende Konzepte:

  • Abfragen: Lesevorgänge zum Abrufen von Daten. Sie geben genau an, welche Daten Sie benötigen.
  • Felder: Die spezifischen Datenelemente, die Sie zu einem Objekt abrufen möchten (z. B. first_name, email).
  • Argumente: Parameter, die Sie an Felder übergeben können, um die zurückgegebenen Daten zu beeinflussen (z. B. eine id, um einen bestimmten Professional abzurufen, oder first: 5, um die Anzahl der Ergebnisse zu begrenzen).
  • Variablen: Eine Möglichkeit, dynamische Werte in Ihre Abfragen einzubringen.
  • Sammlungen: Dienen zum Abfragen von Listen von Elementen (z. B. professionalsCollection). Diese liefern normalerweise ein Array edges, wobei jeder Edge ein node (das tatsächliche Datenobjekt) und einen cursor (für die Paginierung) enthält. Sammlungen enthalten auch häufig totalCount.
  • Knoten: Einzelne Datenobjekte (z. B. ein bestimmter Professional oder eine Einrichtung).

Verfügbare Daten (Schemaübersicht)

Die ArztAPI bietet Zugriff auf verschiedene Arten von Gesundheitsdaten. Nachfolgend finden Sie eine Übersicht über die wichtigsten Datenentitäten und einige ihrer Schlüsselfelder. Sie können diese als Sammlungen (z.B. professionalsCollection) oder als einzelne Knoten abfragen, wenn eine ID bekannt ist (z.B. professional(id: "...")).

Hinweis zur Feldverfügbarkeit:

Die genauen verfügbaren Felder können mittels GraphQL-Introspektion ermittelt werden. Die nachstehenden Listen heben häufig verwendete Felder hervor. Nicht alle Felder sind für jeden Datensatz notwendigerweise gefüllt.

Professionals

Repräsentiert einzelne Fachkräfte im Gesundheitswesen (Ärzte, Zahnärzte, etc.).

  • Query Collection: professionalsCollection
  • Query Single: professional(id: "...")
  • Key Fields: id, provider_kind, first_name, last_name, title, gender, language (array), email, phone, tags (JSON), source_url.
  • Nested Collections: facilitiesCollection, specialisationsCollection.

Einrichtungen

Repräsentiert Gesundheitseinrichtungen wie Kliniken, Krankenhäuser und Praxen.

  • Query Collection: facilitiesCollection
  • Query Single: facility(id: "...")
  • Key Fields: id, facility_type, name, website, email, phone, fax, location_id.
  • Nested Objects/Collections: location (object), openingHoursCollection, professionalFacilityRolesCollection.

Standorte

Repräsentiert physische Adressen.

  • Query Collection: locationsCollection
  • Query Single: location(id: "...")
  • Key Fields: id, street, zip_code, city, state, country, latitude, longitude, wheelchair_accessible.

Öffnungszeiten

Repräsentiert die Öffnungszeiten von Einrichtungen.

  • Query Collection: openingHoursCollection (typischerweise unter einer Einrichtung verschachtelt)
  • Query Single: openingHour(id: "...")
  • Key Fields: id, weekday, open_time, close_time, notes.

Professional-Einrichtungs-Rollen

Verknüpft Professionals mit Einrichtungen und definiert deren Rolle oder Zugehörigkeit.

  • Query Collection: professionalFacilityRolesCollection (typischerweise verschachtelt)
  • Query Single: professionalFacilityRole(id: "...")
  • Key Fields: id, role, contact_email, contact_phone, opening_hours (JSON), krankenkassen (array).

Fachliche Spezialisierungen von Professionals

Verknüpft Professionals mit ihren medizinischen Spezialisierungen.

  • Query Collection: professionalSpecialisationsCollection (typischerweise verschachtelt)
  • Query Single: professionalSpecialisation(id: "...")
  • Key Fields: id, specialisation_id.
  • Nested Objects: specialisation (object).

Spezialisierungen

Repräsentiert medizinische Spezialisierungen.

  • Query Collection: specialisationsCollection
  • Query Single: specialisation(id: "...")
  • Key Fields: id, slug, name_de, name_en, synonyms_de (array), code.

Abfragen erstellen

Hier sind einige Beispiele, die Ihnen helfen, Ihre GraphQL-Abfragen zu erstellen.

1. Grundlegende Sammlungsabfrage

Rufen Sie die ersten 5 Professionals und deren Namen ab.


query GetProfessionals {
  professionalsCollection(first: 5) {
    edges {
      node {
        id
        first_name
        last_name
        title
      }
    }
    totalCount
  }
}

2. Abfragen spezifischer Felder

Sie entscheiden, welche Felder Sie benötigen. Um beispielsweise nur die E-Mail-Adresse und Telefonnummer des ersten Professionals abzurufen:


query GetProfessionalContact {
  professionalsCollection(first: 1) {
    edges {
      node {
        id
        email
        phone
      }
    }
  }
}

3. Abfragen eines einzelnen Knotens nach ID

Rufen Sie einen bestimmten Professional anhand seiner ID ab.


query GetProfessionalById {
  professional(id: "your-professional-id") {
    id
    first_name
    last_name
  }
}

Ersetzen Sie your-professional-id durch eine tatsächliche ID.

4. Verwendung von Argumenten und Filtern

Filtern Sie Professionals nach Nachnamen. (Die vollständigen Filterfunktionen finden Sie in der pg_graphql-Dokumentation).


query FilterProfessionals {
  professionalsCollection(filter: { last_name: { eq: "Mustermann" } }) {
    edges {
      node {
        id
        first_name
        last_name
      }
    }
  }
}

5. Abfragen verschachtelter Daten

Rufen Sie Professionals und die zugehörigen Spezialisierungen ab.


query GetProfessionalsWithSpecialisations {
  professionalsCollection(first: 2) {
    edges {
      node {
        id
        first_name
        last_name
        specialisationsCollection {
          edges {
            node {
              specialisation {
                id
                name_de
              }
            }
          }
        }
      }
    }
  }
}

6. Verwendung von Variablen

Gestalten Sie Ihre Abfragen dynamisch mithilfe von Variablen.

Abfrage:


query GetProfessionalByLastName($lastName: String!) {
  professionalsCollection(filter: { last_name: { eq: $lastName } }, first: 5) {
    edges {
      node {
        id
        first_name
        last_name
      }
    }
  }
}

JSON-Body für die Anfrage (einschließlich Variablen):


{
  "query": "query GetProfessionalByLastName($lastName: String!) { professionalsCollection(filter: { last_name: { eq: $lastName } }, first: 5) { edges { node { id first_name last_name } } } }",
  "variables": {
    "lastName": "Schmidt"
  }
}

Filterung & Paginierung

Filterung

Unsere API unterstützt leistungsstarke Filterfunktionen, die von pg_graphql bereitgestellt werden. Sie können die meisten Felder mithilfe verschiedener Operatoren filtern (z.B. eq, neq, gt, lt, in, like usw.).

Beispiel: Finden Sie Professionals in einer bestimmten Stadt.


query ProfessionalsInCity {
  professionalsCollection(
    filter: {
      facilitiesCollection: {
        some: {
          location: { city: { eq: "Berlin" } }
        }
      }
    }
  ) {
    edges {
      node {
        id
        first_name
        last_name
      }
    }
  }
}

Detaillierte Informationen zu allen verfügbaren Filteroptionen finden Sie in der pg_graphql-Dokumentation zu Filtern.

Paginierung

Sammlungen unterstützen cursor-basierte Paginierung mithilfe der Argumente first und after.

  • first: Int: Gibt die Anzahl der zurückzugebenden Elemente an.
  • after: String: Nimmt einen Cursor (erhalten von pageInfo.endCursor oder einem edge.cursor einer vorherigen Abfrage), um den nächsten Satz von Elementen abzurufen.

Um Paginierungsinformationen zu erhalten, fügen Sie pageInfo true in Ihre Sammlungsabfrage ein.


query PaginatedProfessionals {
  professionalsCollection(first: 10) {
    edges {
      node {
        id
        first_name
      }
      cursor
    }
    pageInfo {
      endCursor
      hasNextPage
    }
    totalCount
  }
}



# Um die nächste Seite abzurufen:
# professionalsCollection(first: 10, after: "WERT_DES_ENDCURSOR_AUS_VORHERIGER_ABFRAGE") { 
#   id
#   first_name
#   last_name
#   ...
# }

Ratenbegrenzung & Credits

Die API-Nutzung wird über ein Credit-System bemessen. Jede Abfrage verbraucht eine bestimmte Anzahl an Credits, abhängig von ihrer Komplexität und der angeforderten Datenmenge. Ihr API-Plan beinhaltet ein monatliches Credit-Kontingent.

Wenn Sie Ihr monatliches Credit-Limit überschreiten, erhalten Sie möglicherweise einen 429 Too Many Requests Fehler. Details zu Ihrer aktuellen Nutzung und Ihren Limits finden Sie in Ihrem Konto-Dashboard.

Die Kosten einer Abfrage werden basierend auf den angeforderten Datentypen und spezifischen Feldern berechnet. Im Allgemeinen verbrauchen Anfragen nach mehr Feldern oder komplexeren verschachtelten Daten mehr Credits. Felder, die leer oder null sind, werden nicht auf die Credit-Nutzung angerechnet.

Fehlerbehandlung

Die API verwendet Standard-HTTP-Statuscodes, um den Erfolg oder Misserfolg einer Anfrage anzuzeigen.

  • 200 OK: Anfrage war erfolgreich. Der Antwortkörper enthält die angeforderten Daten oder GraphQL-Fehler, falls die Abfrage ungültig war.
  • 400 Bad Request: Die Anfrage war fehlerhaft (z.B. ungültiges JSON, ungültige GraphQL-Abfragesyntax).
  • 401 Unauthorized: API-Schlüssel fehlt.
  • 403 Forbidden: API-Schlüssel ist ungültig, inaktiv, keinem Plan zugeordnet, der Plan ist inaktiv oder die Abfrage versucht, auf nicht zulässige Felder/Operationen zuzugreifen.
  • 429 Too Many Requests: Sie haben Ihr API-Credit-Limit überschritten.
  • 500 Internal Server Error: Auf unserem Server ist ein unerwarteter Fehler aufgetreten.

GraphQL-Fehler (auch bei einem HTTP-Status 200 OK) werden im errors-Array der JSON-Antwort enthalten sein:


{
  "errors": [
    {
      "message": "Cannot query field \"nonExistentField\" on type \"ProfessionalNode\".",
      "locations": [ { "line": 6, "column": 9 } ]
    }
  ]
}

Support

Wenn Sie Fragen haben, auf Probleme stoßen oder Unterstützung benötigen, kontaktieren Sie bitte unser Support-Team unter support@arztapi.de oder besuchen Sie unsere Kontaktseite unter arztapi.de/kontakt.