{
  "openapi": "3.1.0",
  "info": {
    "title": "Gozatu! – Daten zu Donostia-San Sebastián",
    "version": "1.6.0",
    "summary": "Offene Datenfeeds des deutschsprachigen Genussguides Gozatu! (donostiasansebastian.de).",
    "description": "Lokale (Restaurants, Pintxos-Bars, Cafés, Weingüter) mit Koordinaten und Öffnungszeiten, Betriebsferien von Spitzenrestaurants (täglich mit deren Websites abgeglichen) , ein Frage-Antwort-Index aus allen Beiträgen und ein Reise-Check, der für einen Reisezeitraum Feste, Ruhetage, Betriebsferien, Txotx-Saison und Saisonprodukte zusammenführt, sowie planmäßige Abfahrten von Bus und Bahn ab Donostia (Flughafen Bilbao, Orte im Umland). Alle Angaben beruhen auf eigenen Besuchen des Autors Christian Fenske. Bitte bei Verwendung Gozatu! mit Link auf den jeweiligen Beitrag als Quelle nennen. Zeitangaben in spanischer Ortszeit (Europe/Madrid). Dieselben Daten stehen KI-Assistenten auch als MCP-Server zur Verfügung: https://donostiasansebastian.de/mcp (Model Context Protocol, Streamable HTTP, ohne Anmeldung).",
    "contact": { "name": "Gozatu!", "url": "https://donostiasansebastian.de/kontakt/" }
  },
  "servers": [ { "url": "https://donostiasansebastian.de/wp-json/gozatu/v1" } ],
  "externalDocs": { "description": "MCP-Server (Model Context Protocol) mit den Werkzeugen search, fetch, find_places, next_departures, trip_check, ask_gozatu", "url": "https://donostiasansebastian.de/mcp" },
  "paths": {
    "/karte": {
      "get": {
        "operationId": "lokale",
        "summary": "Alle besprochenen Lokale mit Typ, Koordinaten, Öffnungszeiten und Link zum Beitrag",
        "description": "Grundlage der Karte und der Listen „… geöffnet“. Lokale in Betriebsferien werden ohne Öffnungszeiten (ohs = null) und mit betriebsferien_bis ausgeliefert; dauerhaft geschlossene Lokale fehlen.",
        "responses": {
          "200": {
            "description": "Liste der Lokale",
            "content": { "application/json": { "schema": {
              "type": "object",
              "properties": {
                "generated": { "type": "string", "description": "Zeitpunkt der Erzeugung (ISO 8601)" },
                "count": { "type": "integer" },
                "items": { "type": "array", "items": { "$ref": "#/components/schemas/Lokal" } }
              }
            } } }
          }
        }
      }
    },
    "/betriebsferien": {
      "get": {
        "operationId": "betriebsferien",
        "summary": "Laufende und kommende Betriebsferien von Spitzenrestaurants in und um San Sebastián",
        "description": "Täglich mit den Websites der Restaurants abgeglichen. Lesbare Fassung: https://donostiasansebastian.de/betriebsferien-restaurants-san-sebastian/",
        "responses": {
          "200": {
            "description": "Ferientermine",
            "content": { "application/json": { "schema": {
              "type": "object",
              "properties": {
                "stand": { "type": "string", "format": "date" },
                "hinweis": { "type": "string" },
                "ferien": { "type": "array", "items": { "$ref": "#/components/schemas/Ferien" } }
              }
            } } }
          }
        }
      }
    },
    "/reise": {
      "get": {
        "operationId": "reiseCheck",
        "summary": "Reise-Check: Was ist in San Sebastián los, wenn du da bist?",
        "description": "Für einen Zeitraum von bis zu 14 Tagen: Feste aus dem Gozatu!-Festkalender, Ruhetage der Lokale nach Wochentag, Betriebsferien der Spitzenrestaurants, Txotx-Saison (Turismo Euskadi) mit Zahl der geöffneten Sidrerías pro Tag (Verband Sagardoaren Lurraldea) und Saisonprodukte laut Saisonkalender. Gezeiten nicht enthalten, siehe https://donostiasansebastian.de/gezeiten-san-sebastian/. Lesbare Fassung: https://donostiasansebastian.de/reise-check-san-sebastian/",
        "parameters": [
          { "name": "von", "in": "query", "required": true, "description": "Anreisetag", "schema": { "type": "string", "format": "date" } },
          { "name": "bis", "in": "query", "required": true, "description": "Abreisetag, höchstens 13 Tage nach von", "schema": { "type": "string", "format": "date" } }
        ],
        "responses": {
          "200": {
            "description": "Ergebnis für den Zeitraum",
            "content": { "application/json": { "schema": {
              "type": "object",
              "properties": {
                "von": { "type": "string", "format": "date" },
                "bis": { "type": "string", "format": "date" },
                "anzahl_tage": { "type": "integer" },
                "feste": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "von": { "type": "string", "format": "date" }, "bis": { "type": "string", "format": "date" }, "info": { "type": "string" }, "link": { "type": "string", "format": "uri" } } } },
                "betriebsferien": { "type": "array", "items": { "$ref": "#/components/schemas/Ferien" } },
                "txotx": { "type": ["object", "null"], "properties": { "status": { "type": "string", "enum": ["laeuft", "ausserhalb", "termin_offen"] }, "text": { "type": "string" } } },
                "lokale_mit_zeiten": { "type": "integer" },
                "an_allen_tagen_offen": { "type": "integer" },
                "ruhetage": { "type": "array", "items": { "type": "object", "properties": { "wochentag": { "type": "string" }, "geschlossen": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "link": { "type": "string", "format": "uri" } } } } } } },
                "saison": { "type": "object", "properties": { "jahreszeiten": { "type": "array", "items": { "type": "string" } }, "produkte": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "hoehepunkt": { "type": "boolean" } } } } } },
                "tage": { "type": "array", "items": { "type": "object", "properties": { "datum": { "type": "string", "format": "date" }, "wochentag": { "type": "string" }, "feste": { "type": "array", "items": { "type": "string" } }, "betriebsferien": { "type": "array", "items": { "type": "string" } }, "ruhetag_anzahl": { "type": "integer" }, "txotx_sidrerias": { "type": ["object", "null"], "properties": { "mittags": { "type": "integer" }, "abends": { "type": "integer" } } } } } },
                "hinweis": { "type": "string" }
              }
            } } }
          },
          "400": { "description": "Ungültiger Zeitraum", "content": { "application/json": { "schema": { "type": "object", "properties": { "fehler": { "type": "string" } } } } } }
        }
      }
    },
    "/abfahrt": {
      "get": {
        "operationId": "abfahrten",
        "summary": "Planmäßige Abfahrten von Bus und Bahn zwischen Donostia-San Sebastián und einem Ziel (z. B. Flughafen Bilbao, Getaria, Zumaia)",
        "description": "Ohne Parameter: Liste der Ziele. Mit ziel: Fahrplan der Direktverbindungen in beide Richtungen aus den offenen Fahrplandaten der Baskischen Regierung (Moveuskadi; Lurraldebus und Euskotren), täglich aktualisiert. Keine Echtzeit; Feiertage sind in den Busfahrplänen nicht berücksichtigt. Zeiten in Ortszeit Europe/Madrid. Bei Bussen nur Fahrten über zentrale Haltestellen in Donostia. Lesbare Fassung: https://donostiasansebastian.de/naechster-bus-flughafen-bilbao-san-sebastian/",
        "parameters": [
          { "name": "ziel", "in": "query", "required": false, "description": "Schlüssel des Ziels", "schema": { "type": "string", "enum": ["flughafen", "hendaye", "getaria", "zarautz", "zumaia", "orio", "deba", "hondarribia", "pasaia", "astigarraga", "hernani", "tolosa", "bilbao", "vitoria"] } }
        ],
        "responses": {
          "200": {
            "description": "Zielliste (ohne ziel) oder Fahrplan (mit ziel)",
            "content": { "application/json": { "schema": {
              "type": "object",
              "properties": {
                "ziele": { "type": "array", "description": "Nur ohne Parameter", "items": { "type": "object", "properties": { "ziel": { "type": "string" }, "name": { "type": "string" }, "beitrag": { "type": "string", "format": "uri" }, "fahrplan": { "type": "string", "format": "uri" } } } },
                "ziel": { "type": "string" },
                "name": { "type": "string" },
                "beitrag": { "type": "string", "format": "uri" },
                "stand": { "type": "string", "format": "date", "description": "Tag des letzten Datenabrufs" },
                "bis": { "type": "string", "format": "date", "description": "Letzter Tag mit veröffentlichtem Fahrplan" },
                "tage": { "type": "object", "description": "Datum (JJJJ-MM-TT) => Schlüssel eines Plans in plaene", "additionalProperties": { "type": "string" } },
                "plaene": { "type": "object", "description": "Tagespläne. hin = ab Donostia, rueck = nach Donostia. Jede Fahrt: [Abfahrt HH:MM, Ankunft HH:MM, Linie, Bus oder Zug, Abfahrtshalt, Ankunftshalt]", "additionalProperties": { "type": "object", "properties": { "hin": { "type": "array", "items": { "type": "array", "items": { "type": "string" } } }, "rueck": { "type": "array", "items": { "type": "array", "items": { "type": "string" } } } } } },
                "hinweis": { "type": "string" }
              }
            } } }
          },
          "404": { "description": "Unbekanntes Ziel" },
          "503": { "description": "Fahrplan vorübergehend nicht verfügbar" }
        }
      }
    },
    "/zahlen": {
      "get": {
        "operationId": "zahlen",
        "summary": "San Sebastián in Zahlen: eigene Statistik zu Ruhetagen, Öffnungszeiten, Betriebsferien, Sidrerías und Fahrplänen",
        "description": "Täglich neu berechnet aus den Daten von Gozatu!. Basis sind alle besprochenen Bars, Restaurants und Cafés mit Öffnungszeiten (reguläre Öffnungszeiten, Betriebsferien nicht abgezogen; Öffnungs-, nicht Küchenzeiten) – keine amtliche Statistik aller Betriebe. Wochentage 0 = Montag bis 6 = Sonntag. saetze enthält je Thema einen zitierbaren Kernsatz und eine Ergänzung. Bitte mit Quelle Gozatu! zitieren. Lesbare Fassung: https://donostiasansebastian.de/san-sebastian-in-zahlen/",
        "responses": {
          "200": {
            "description": "Kennzahlen",
            "content": { "application/json": { "schema": {
              "type": "object",
              "properties": {
                "stand": { "type": "string", "format": "date" },
                "lokale": { "type": "object", "description": "n = Zahl der Lokale; zu = geschlossene Lokale je Wochentag; alle7 = an sieben Tagen geöffnet; stunden und heat = geöffnete Lokale je Wochentag zur halben Stunde; zeiten = Durchschnittswerte zu typischen Uhrzeiten", "properties": { "n": { "type": "integer" }, "zu": { "type": "array", "items": { "type": "integer" } }, "alle7": { "type": "integer" }, "stunden": { "type": "array", "items": { "type": "integer" } }, "heat": { "type": "array", "items": { "type": "array", "items": { "type": "integer" } } }, "zeiten": { "type": "object", "additionalProperties": { "type": "integer" } } } },
                "ferien": { "type": "object", "description": "Spitzenrestaurants mit Betriebsferien je Monat (12 Monate ab heute)", "properties": { "haeuser": { "type": "integer" }, "monate": { "type": "array", "items": { "type": "object", "properties": { "monat": { "type": "string" }, "anzahl": { "type": "integer" }, "haeuser": { "type": "array", "items": { "type": "string" } } } } } } },
                "sidrerias": { "type": "object", "description": "Geöffnete Sidrerías je Wochentag in der Txotx-Saison", "properties": { "n": { "type": "integer" }, "mittags": { "type": "array", "items": { "type": "integer" } }, "abends": { "type": "array", "items": { "type": "integer" } } } },
                "verkehr": { "type": "array", "description": "Direktfahrten ab Donostia je Ziel an einem Mittwoch und einem Sonntag", "items": { "type": "object", "properties": { "ziel": { "type": "string" }, "name": { "type": "string" }, "werktag": { "type": "integer" }, "sonntag": { "type": ["integer", "null"] }, "schnellste": { "type": "integer", "description": "Minuten" }, "erste": { "type": "string" }, "letzte": { "type": "string" } } } },
                "saetze": { "type": "object", "description": "Zitierbare Sätze je Thema: [Kernsatz, Ergänzung]", "additionalProperties": { "type": "array", "items": { "type": "string" } } },
                "hinweis": { "type": "string" }
              }
            } } }
          }
        }
      }
    },
    "/kultur": {
      "get": {
        "operationId": "kulturTermine",
        "summary": "Kulturtermine in Donostia-San Sebastián (Konzerte, Theater, Kino, Vorträge, Bertsolaritza)",
        "description": "Täglich aus Kulturklik (Agenda cultural de Euskadi, Baskische Regierung, Open Data Euskadi) übernommen; Titel und Angaben im Original (meist Spanisch). Mehrtägige Termine (Ausstellungen) haben start ungleich ende. lat/lng = Spielstätte, wenn bekannt. Quelle bei Weiterverwendung nennen.",
        "parameters": [
          { "name": "von", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Erster Tag (Standard: heute, Zeitzone Europe/Madrid)" },
          { "name": "bis", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Letzter Tag (Standard: von + 13 Tage; Daten reichen bis heute + 31 Tage)" }
        ],
        "responses": {
          "200": {
            "description": "Termine im Zeitraum",
            "content": { "application/json": { "schema": { "type": "object", "properties": {
              "stand": { "type": "string", "format": "date-time" },
              "von": { "type": "string", "format": "date" },
              "bis": { "type": "string", "format": "date" },
              "anzahl": { "type": "integer" },
              "quelle": { "type": "string" },
              "items": { "type": "array", "items": { "type": "object", "properties": {
                "id": { "type": "string" }, "name": { "type": "string" },
                "typ": { "type": "string", "description": "Art laut Kulturklik, z. B. Concierto, Teatro, Cine y audiovisuales, Conferencia, Bertsolarismo, Exposición" },
                "start": { "type": "string", "format": "date" }, "ende": { "type": "string", "format": "date" },
                "zeit": { "type": "string", "description": "Uhrzeit(en) als Text, z. B. 19:30 oder 18:30-20:00" },
                "preis": { "type": "string" }, "ort": { "type": "string" }, "url": { "type": "string", "format": "uri" },
                "lat": { "type": "number" }, "lng": { "type": "number" }
              } } }
            } } } }
          }
        }
      }
    },
    "/verkehr": {
      "get": {
        "operationId": "verkehrslage",
        "summary": "Verkehrsmeldungen Gipuzkoa (Straßen) und Baustellen/Sperrungen in Donostia",
        "description": "Aus Tráfico Euskadi (Baskische Regierung, Open Data Euskadi), höchstens 15 Minuten alt. strassen: nach Warnstufe sortiert (Negro, Rojo, Amarillo …). Angaben im Original (Spanisch).",
        "responses": {
          "200": {
            "description": "Aktuelle Meldungen",
            "content": { "application/json": { "schema": { "type": "object", "properties": {
              "stand": { "type": "string", "format": "date-time" },
              "quelle": { "type": "string" },
              "strassen": { "type": "array", "items": { "$ref": "#/components/schemas/Verkehrsmeldung" } },
              "stadt": { "type": "array", "items": { "$ref": "#/components/schemas/Verkehrsmeldung" } }
            } } } }
          }
        }
      }
    },
    "/frag-index": {
      "get": {
        "operationId": "fragAntwortIndex",
        "summary": "Frage-Antwort-Index aus allen Beiträgen (FAQ und Glossar) plus Lokale mit Wochen-Öffnungszeiten",
        "description": "Kompakte Arrays. docs: [Titel, URL]. faq: [Frage, Antwort, Index in docs]. lok: [Name, URL, Typ (bar|restaurant|cafe|weingut), Woche (7 Einträge Mo–So, je Liste [öffnet, schließt] in Minuten ab Mitternacht; schließt < öffnet = über Mitternacht) oder null, Index in dist oder -1]. dist: [Stadtteil, URL].",
        "responses": {
          "200": {
            "description": "Index",
            "content": { "application/json": { "schema": {
              "type": "object",
              "properties": {
                "stand": { "type": "string", "format": "date" },
                "docs": { "type": "array", "items": { "type": "array" } },
                "faq": { "type": "array", "items": { "type": "array" } },
                "lok": { "type": "array", "items": { "type": "array" } },
                "dist": { "type": "array", "items": { "type": "array" } }
              }
            } } }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Verkehrsmeldung": { "type": "object", "properties": {
        "typ": { "type": "string" }, "grund": { "type": "string" }, "ort": { "type": "string" }, "strasse": { "type": "string" },
        "km": { "type": "string" }, "richtung": { "type": "string" }, "stufe": { "type": "string" },
        "seit": { "type": "string" }, "bis": { "type": "string" }, "lat": { "type": "number" }, "lng": { "type": "number" } } },
      "Lokal": {
        "type": "object",
        "properties": {
          "name": { "type": "string" },
          "title": { "type": "string", "description": "Titel des Gozatu-Beitrags" },
          "link": { "type": "string", "format": "uri", "description": "Gozatu-Beitrag zum Lokal" },
          "typ": { "type": "string", "enum": [ "bar", "restaurant", "cafe", "weingut", "sonstige" ] },
          "type": { "description": "schema.org-Typ(en)" },
          "lat": { "type": "number" },
          "lng": { "type": "number" },
          "image": { "type": "string" },
          "ohs": { "description": "schema.org OpeningHoursSpecification (Liste) oder null", "type": [ "array", "null" ] },
          "oh": { "description": "schema.org openingHours (Text) oder null" },
          "betriebsferien_bis": { "type": "string", "format": "date", "description": "Nur gesetzt, wenn das Lokal gerade Betriebsferien hat" }
        }
      },
      "Ferien": {
        "type": "object",
        "properties": {
          "restaurant": { "type": "string" },
          "ort": { "type": "string" },
          "beitrag": { "type": "string", "format": "uri" },
          "quelle": { "type": "string", "format": "uri", "description": "Seite des Restaurants mit den Ferienangaben" },
          "geschlossen_von": { "type": [ "string", "null" ], "format": "date", "description": "null, wenn nur das Ende bekannt ist" },
          "geschlossen_bis": { "type": "string", "format": "date" },
          "ohne_jahresangabe": { "type": "boolean", "description": "Die Website nennt die Termine ohne Jahreszahl" }
        }
      }
    }
  }
}