openapi.yaml

openapi: "3.0.0"
info:
  description: >-
    Reisewarnungen OpenData Schnittstelle.
    Dies ist die Beschreibung für die Schnittstelle zum Zugriff auf die Daten
    des [Auswärtigen Amtes](https://www.auswaertiges-amt.de/de/) im Rahmen der
    [OpenData](https://www.auswaertiges-amt.de/de/open-data-schnittstelle/736118) Initiative.

    ## Deaktivierung

    Die Schnittstelle kann deaktiviert werden, in dem Fall wird ein leeres JSON-Objekt zurückgegeben.

    ## Fehlerfall
    
    Im Fehlerfall wird ein leeres JSON-Objekt zurückgegeben.

    ## Nutzungsbedingungen

    Die Nutzungsbedingungen sind auf der [OpenData-Schnittstelle](https://www.auswaertiges-amt.de/de/open-data-schnittstelle/736118)
     des Auswärtigen Amtes zu finden. 

    ## Änderungen [(offizielles Changelog)](https://www.auswaertiges-amt.de/de/-/2412916)

    ### version [1.2.7](https://www.auswaertiges-amt.de/de/-/2412916) - (02.08.2022)

    Dreistellige ISO-Ländercodes ([ISO 3166-1 alpha-3](https://de.wikipedia.org/wiki/ISO-3166-1-Kodierliste)) wurden als `iso3CountryCode` hinzugefügt.

    ### version [1.2.6](https://www.auswaertiges-amt.de/de/-/2412916) - (08.12.2021)

    Es werden zusätzlich zu jedem Land **Ländercodes** mit jeweils **zwei Buchstaben** mit ausgegeben.

    Die Länderkürzel werden bei [`/travelwarning`](#operations-default-getTravelwarning) und [`/travelwarning/{contentId}`](#operations-default-getSingleTravelwarning) in einem neuen Attribut ausgegeben z.B. in: [`/travelwarning/199124`](https://www.auswaertiges-amt.de/opendata/travelwarning/199124).

    ### version [1.2.5](https://www.auswaertiges-amt.de/de/-/2412916) (ursprünglich geplant für Ende September 2021)

    `content` (-> Details des Reise- und Sicherheitshinweis) wurde von [`/travelwarning`](#operations-default-getTravelwarning) entfernt -> bitte ab jetzt [`/travelwarning/{contentId}`](#operations-default-getSingleTravelwarning) nutzen um `content` abzufragen

    `flagURL` (-> Details des Reise- und Sicherheitshinweis) wurde entfernt -> es werden keine **Flaggen** mehr angeboten

  version: 1.2.6
  title: >-
    Auswärtiges Amt: Reisewarnungen OpenData Schnittstelle
  termsOfService: 'https://www.auswaertiges-amt.de/de/open-data-schnittstelle/736118'

servers:
  - url: 'https://www.auswaertiges-amt.de/opendata'

paths:
  /travelwarning:
    get:
      summary: Gibt alle Reise- und Sicherheitshinweise zurück
      description: ''
      operationId: getTravelwarning
      responses:
        '200':
          description: Erfolgreich
          content:
            text/json;charset=UTF-8:
              schema:
                $ref: '#/components/schemas/ResponseWarnings'
  '/travelwarning/{contentId}':
    get:
      summary: Gibt einen Reise- und Sicherheitshinweis zurück
      description: 'Gibt den vollständigen Datensatz eines Reise- und Sicherheitshinweises zurück. Benötigt die jeweilige ID siehe /travelwarning'
      operationId: getSingleTravelwarning
      parameters:
        - name: contentId
          description: 'Die ID des Reise- und Sicherheitshinweises, IDs siehe /travelwarning'
          in: path
          required: true
          schema:
            type: integer
            minimum: 1
      responses:
        '200':
          description: Erfolgreich
          content:
            text/json;charset=UTF-8:
              schema:
                $ref: '#/components/schemas/ResponseWarning'
        '404':
          description: Not Found
  /representativesInGermany:
    get:
      summary: Gibt eine Liste der ausländischen Vertretungen in Deutschland zurück
      description: ''
      operationId: getRepresentativesGermany
      responses:
        '200':
          description: Erfolgreich
          content:
            text/json;charset=UTF-8:
              schema:
                $ref: '#/components/schemas/ResponseAddress'
  /representativesInCountry:
    get:
      summary: Gibt eine Liste der deutschen Vertretungen im Ausland zurück
      description: ''
      operationId: getRepresentativesCountry
      responses:
        '200':
          description: Erfolgreich
          content:
            text/json;charset=UTF-8:
              schema:
                $ref: '#/components/schemas/ResponseAddress'
  /stateNames:
    get:
      summary: Gibt das Verzeichnis der Staatennamen zurück
      description: Verzeichnis der Staatennamen als Link auf eine XML- oder CSV-Datei. Eine PDF-Datei mit Nutzungshinweisen wird ebenfalls zurückgegeben.
      operationId: getStateNames
      responses:
        '200':
          description: Erfolgreich
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseDownload'
  /healthcare:
    get:
      summary: Gibt die Merkblätter des Gesundheitsdienstes zurück
      description: Merkblätter des Gesundheitsdienstes als Link auf ein PDF
      operationId: getHealthcare
      responses:
        '200':
          description: Erfolgreich
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseDownload'
components:
  schemas:
    Empty:
      title: Fehler/Leer
      type: object
      description: >-
        Wird zurückgegeben im Fehlerfall oder wenn die Schnittstelle deaktiviert
        wurde
    ResponseAddress:
      type: object
      title: Antwort mit Adressenliste
      properties:
        response:
          type: object
          properties:
            '12345':
              $ref: '#/components/schemas/AdressListe'
            contentList:
              type: array
              description: IDs der Objekte
              items:
                type: string
                example: '12345'
    ResponseWarnings:
      type: object
      title: Antwort mit Reise- und Sicherheitshinweisen
      properties:
        response:
          type: object
          properties:
            '12345':
              $ref: '#/components/schemas/ReisewarnungZusammenfassung'
            '23456':
              $ref: '#/components/schemas/ReisewarnungZusammenfassung'
            contentList:
              type: array
              description: IDs der Objekte
              items:
                type: string
              example:
                - '12345'
                - '23456'
    ResponseWarning:
      type: object
      title: Antwort mit Reise- und Sicherheitshinweis
      properties:
        response:
          type: object
          properties:
            '12345':
              $ref: '#/components/schemas/Reisewarnung'
            contentList:
              type: array
              description: IDs der Objekte
              items:
                type: string
                example: '12345'
    ResponseArtikel:
      type: object
      title: Antwort mit Artikeln
      properties:
        response:
          type: object
          properties:
            '12345':
              $ref: '#/components/schemas/Artikel'
            contentList:
              type: array
              description: IDs der Objekte
              items:
                type: string
                example: '12345'
    ResponseDownload:
      type: object
      title: Antwort mit Downloads
      properties:
        response:
          type: object
          properties:
            '12345':
              $ref: '#/components/schemas/Download'
            contentList:
              type: array
              description: IDs der Objekte
              items:
                type: string
                example: '12345'
    Reisewarnung:
      type: object
      properties:
        lastModified:
          type: number
          description: Zeitstempel der letzten Änderung
          example: 1499681492000
        effective:
          type: number
          description: 'Zeitstempel, seit wann der Reisehinweis gilt'
          example: 1499681492000
        title:
          type: string
          description: Titel des Landes
          example: >-
            Deutschland: Reise- und Sicherheitshinweise
        CountryCode:
          type: string
          description: Zweistelliger Ländercode
          example: DE
        iso3CountryCode:
          type: string
          description: Dreistelliger Ländercode ([*ISO-3166-1 alpha-3*](https://de.wikipedia.org/wiki/ISO-3166-1-Kodierliste))
          example: DEU
        CountryName:
          type: string
          description: (Deutscher) Name des Landes
          example: Deutschland
        warning:
          type: boolean
          description: Ob eine Reisewarnung ausgesprochen wurde
          example: true
        partialWarning:
          type: boolean
          description: Ob eine Teilreisewarnung ausgesprochen wurde
          example: false
        situationWarning:
          type: boolean
          description: >-
           Steht aktuell (Januar 2022) für *„COVID-19-bedingte Reisewarnung“* kann sich in Zukunft möglicherweise ändern.
          example: false
        situationPartWarning:
          type: boolean
          description: >-
           Steht aktuell (Januar 2022) für *„COVID-19-bedingte Teilreisewarnung“* kann sich in Zukunft möglicherweise ändern.
          example: false
        content:
          type: string
          description: Text der Länderseite
          example: <h3>Titel</h3><div>Inhalt</div>
    ReisewarnungZusammenfassung:
      type: object
      properties:
        lastModified:
          type: number
          description: Zeitstempel der letzten Änderung
          example: 1499681492000
        effective:
          type: number
          description: 'Zeitstempel, seit wann der Reisehinweis gilt'
          example: 1499681492000
        title:
          type: string
          description: Titel des Landes
          example: >-
            Deutschland: Reise- und Sicherheitshinweise
        CountryCode:
          type: string
          description: Zweistelliger Ländercode
          example: DE
        CountryName:
          type: string
          description: (Deutscher) Name des Landes
          example: Deutschland
        warning:
          type: boolean
          description: Ob eine Reisewarnung ausgesprochen wurde
          example: true
        partialWarning:
          type: boolean
          description: Ob eine Teilreisewarnung ausgesprochen wurde
          example: false
        situationWarning:
          type: boolean
          description: >-
           Steht aktuell (Januar 2022) für *„COVID-19-bedingte Reisewarnung“* kann sich in Zukunft möglicherweise ändern.
          example: false
        situationPartWarning:
          type: boolean
          description: >-
           Steht aktuell (Januar 2022) für *„COVID-19-bedingte Teilreisewarnung“* kann sich in Zukunft möglicherweise ändern.
          example: false
    AdressListe:
      type: object
      properties:
        '67890':
          $ref: '#/components/schemas/Adresse'
        lastModified:
          type: number
          description: Zeitstempel der letzten Änderung
          example: 1499681492000
        contentList:
          type: array
          description: IDs der enthaltenen Adressen
          items:
            type: string
            example: '67890'
    Artikel:
      type: object
      properties:
        lastModified:
          type: number
          description: Zeitstempel der letzten Änderung
          example: 1499681492000
        title:
          type: string
          description: Titel
          example: Zika-Virus-Infektion
        content:
          type: string
          description: Inhalt
          example: <div>Inhalt</div>
    Download:
      type: object
      properties:
        lastModified:
          type: number
          description: Zeitstempel der letzten Änderung
          example: 1499681492000
        name:
          type: string
          description: Name
          example: Merkblatt zum Thema
        url:
          type: string
          description: Link zum Download
          example: 'https://www.auswaertiges-amt.de/blob/1234.pdf'
    Adresse:
      type: object
      properties:
        lastModified:
          type: number
          description: Zeitstempel der letzten Änderung
          example: 1499681492000
        title:
          type: string
          description: Titel
          example: Botschaft der Musterstaaten
        leader:
          type: string
          description: Leiter
          example: Herr/Frau Mustermann/-frau
        locales:
          type: string
          description: Sprachen
          example: 'Deutsch, Englisch'
        country:
          type: string
          description: Land
          example: Deutschland
        zip:
          type: string
          description: Postleitzahl
          example: '12345'
        city:
          type: string
          description: Stadt
          example: Musterstadt
        region:
          type: string
          description: Region
          example: Musterregion
        street:
          type: string
          description: Straße
          example: Hauptstraße
        number:
          type: string
          description: Hausnummer
          example: '12'
        departments:
          type: string
          description: Abteilungen
          example: Handelsabteilung Tel. +49
        fax:
          type: string
          description: Faxnummer
          example: +49 123 456789
        telefone:
          type: string
          description: Telefonnummer
          example: +49 123 456789
        mail:
          type: string
          description: E-Mail
          example: extern@diplo.de
        misc:
          type: string
          description: Sonstiges
          example: Sonstige Anmerkungen
        url:
          type: string
          description: Externer Link
          example: 'https://extern.diplo.de'
        postal:
          type: string
          description: Postfach
          example: 'Hauptstraße 12, 12345 Musterstadt'
        type:
          type: string
          description: Adresstyp
          example: Botschaft
        remark:
          type: string
          description: Hinweis
          example: Sonntag geschlossen
        open:
          type: string
          description: Öffnungszeiten
          example: '10:00-18:00'