# Datenkarte – Vision {#datovamapa-vize}

Datum: 2026-10-06 (ersetzt den ursprünglichen Kontext von 2026-08, dieser liegt in `docs/archiv/`)

## Was ist die Datenkarte {#co-je-datovamapa}

Die Datenkarte ist eine **offene Schnittstelle zur Visualisierung von Daten auf der Karte**. Sie definiert ein offenes Schema (Protokoll), über das jede und jeder beliebige Daten auf der Karte darstellen kann – Punkte, Linien, Flächen, Dichten, Rasterebenen.

Das Prinzip:

1. Der Datenanbieter veröffentlicht ein **Manifest** (Beschreibung seiner selbst und seiner Datensätze) und einen **Datenendpunkt** nach dem Protokoll der Datenkarte.
2. Der Anbieter registriert das Manifest; nach der Freigabe durch den Betreiber erscheinen die Datensätze im Katalog.
3. Schaltet eine Nutzerin oder ein Nutzer einen Datensatz ein, fragt das Portal die Quelle ab (für den aktuellen Kartenausschnitt und die gesetzten Filter), prüft die Antwort, legt sie im Cache ab und stellt sie gemäß der Beschreibung im Manifest dar.

Das Portal besitzt die Daten nicht; es vermittelt sie und nennt immer die Quelle. Betreiber des Portals ist [vrealmatic.com](https://vrealmatic.com/web).

## Nutzen {#prinos}

**Für Nutzerinnen und Nutzer:** Auf einer einzigen Karte lassen sich Daten aus beliebigen Quellen kombinieren – ohne zwischen Dutzenden Kartenportalen zu wechseln.

**Für Datenanbieter:**

- Sie müssen sich weder um die Karte noch um Stile oder einen Kartenserver kümmern – ein JSON-Endpunkt genügt,
- sie sind Teil eines offenen Datenportals, ihre Daten treffen auf die Daten anderer,
- sie werden sichtbar als Quelle genannt (bei den Daten auf der Karte, im Objektdetail und in der Quellenübersicht).

## Daten bereiten KI-Agenten vor {#data-pripravuji-ai-agenti}

Wir gehen davon aus, dass die Daten bei den Anbietern vor allem KI-Agenten vorbereiten (im Auftrag des Menschen, dem die Daten gehören). Deshalb ist das gesamte Portal „KI-freundlich“ aufgebaut:

- **Alles liegt in Markdown vor.** Jede Seite der Dokumentation hat eine Markdown-Version (`/dokumentation/{slug}.md`), die Startseite `/index.md`, der Katalog `/quellen.md`; dazu der Wegweiser `/llms.txt` und die gesamte Dokumentation in einer Datei `/llms-full.txt`. Quelle der Wahrheit sind die Dateien in `docs/`, das HTML wird daraus erzeugt.
- **Anleitung für Agenten** mit Vorgehen, Entscheidungstabellen, Codevorlagen, Regeln (personenbezogene Daten, Lizenzen) und Kriterien für eine fertige Arbeit.
- **Maschinenlesbare Schemas**, aus einer einzigen Quelle erzeugt: JSON Schema für Manifest und Daten, OpenAPI-Vertrag des Anbieters (daraus erzeugt der Agent den Server) und OpenAPI des Portals.
- **Validator mit Rückmeldung**: stabile Fundcodes, genaue Pfade und Hinweise, wie der Fehler zu beheben ist; Live-Test des gesamten Anbieters. Der Agent iteriert, bis `valid: true` gilt.
- **MCP-Server** `/mcp`: Dokumentation, Schemas, Beispiele, Validierung, Katalog und Daten als Werkzeuge.
- **Geprüfte Beispiele**: Jedes Beispiel in der Dokumentation durchläuft den Validator (`npm run check:docs`), damit der Agent keinen Fehler kopiert.
- **Felder für die Auffindbarkeit**: `keywords`, `useCases`, `description`, `fields` – danach finden Menschen wie auch der Assistent des Portals die Daten.

Die Daten im Portal lesen auch KI-Assistenten von Privatpersonen und Unternehmen. Über den MCP-Server oder die HTTP-API finden sie einen Ort (Adressverzeichnis), fragen ausgewählte Datensätze, was sich an einem Punkt und in seiner Umgebung befindet (auch Rasterkarten wie Hochwasser, Radon oder Lärm), und erhalten eine Zusammenfassung für eine Gemeinde. Die Daten interpretieren sie selbst und nennen die Quelle. Anleitung: [Daten für KI-Assistenten](https://datenkarte.at/dokumentation/ki-assistenten.md).

## Prinzipien {#principy}

- **Offenes Protokoll.** Das Schema ist öffentlich (`/schema/0.1/manifest.json`, `/schema/0.1/data.json`) und basiert auf GeoJSON (RFC 7946). Fast alles ist optional, verpflichtend ist nur ein kleines Minimum.
- **Absicht statt Bibliothek.** Der Anbieter beschreibt, *was* er zeigen will (Punkte nach Kategorie, Kartogramm nach Wert …), nicht die konkrete Einstellung einer Kartenbibliothek. Das Portal kann die Darstellung ändern, ohne dass der Anbieter betroffen ist.
- **Vorwärtskompatibilität.** Unbekannte Felder werden ignoriert, ein unbekannter Visualisierungstyp wird im Standardstil dargestellt. So kann das Protokoll wachsen, ohne bestehende Quellen zu brechen.
- **Schlichte Startseite.** Nur Karte und Logo. Beim Überfahren mit der Maus bzw. per Klick öffnet sich die Datenauswahl. Keine weiteren Panels.
- **Einstiegsseiten für konkrete Daten.** Wer eine bestimmte Kennzahl sucht, kommt aus der Suchmaschine auf die Seite eines Datensatzes (`/karte/{provider}/{dataset}`), eines Datensatzes für eine Gemeinde oder einer zusammengestellten Karte (`/karten/{slug}`): dieselbe Karte mit voreingestellten Daten und einer Beschreibung samt Zusammenfassung der Daten. Weitere Ebenen lassen sich wie auf der Startseite hinzufügen.
- **Sicherheit.** Daten der Anbieter werden nie als HTML eingefügt, der Proxy fragt nur registrierte Quellen ab, mit Zeit- und Größenlimits.

## Startseite {#hlavni-stranka}

- Vollflächige Karte und Logo links oben. Die Karte öffnet sich über ganz Österreich.
- **Einstieg.** Wer ohne Auswahl und ohne Link auf einen Ort kommt, wird beim Laden der Karte im Browser nach dem Standort gefragt, in seine Umgebung versetzt, und neben der Karte öffnet sich das Einstiegsfenster „Ihre Umgebung in Daten“ – ein Schnellstart: der Assistent (in Vorbereitung) mit Schnellauswahlen, also zusammengestellten Karten mit einem Klick, und Links zu gerade aktuellen Daten. Einzelne Ebenen werden im Katalog („Gesamter Katalog“) eingeschaltet. Wer den Standort nicht freigibt oder sich außerhalb Österreichs befindet, erhält den Einstieg für ganz Österreich. Ein Link mit Auswahl überspringt den Einstieg; dieser kehrt aber zurück, sobald auf der Karte nichts angezeigt wird.
- Den genauen Standort zeigt man mit der Schaltfläche „Meine Umgebung“ rechts oben neben der Kartensteuerung an – der Browser fragt erst nach dem Klick; wer den Standort schon früher freigegeben hat, sieht die Karte gleich in seiner Umgebung (und der Einstieg verwendet diesen Standort).
- Das Überfahren des Logos mit der Maus (oder Klick / Tippen) öffnet ein großes Auswahlfenster (über 80 % der Breite): links der **Katalog** als Karten nach Kategorien mit Suche, rechts **Auf der Karte** – eingeschaltete Ebenen mit Status, Legende und Filtern. Oben ist eine Vorschau des künftigen Assistenten – vorerst inaktiv. Ein Klick oder die Arbeit im Fenster heftet es an; geschlossen wird es mit dem Kreuz, der Taste Esc oder einem Klick daneben.
- Die Auswahl wird in der URL gespeichert, der Link lässt sich teilen.

### Eingabe in natürlicher Sprache (Zukunft) {#zadani-v-prirozenem-jazyce-budoucnost}

Ziel: Die Nutzerin schreibt etwa *„Ich möchte in der Gemeinde Neustift bauen, zeig mir alle relevanten Daten, die du für meinen Zweck hast“*, und das Portal

1. versteht den Ort (Geokodierung von Gemeinde / Adresse / Grundstück) und verschiebt die Karte,
2. versteht den Zweck (Bauen) und wählt passende Datensätze nach `useCases`, `keywords` und den Beschreibungen in den Manifesten,
3. setzt gegebenenfalls Filter und fasst zusammen, was es in den Daten sieht.

Im Fenster gibt es vorerst nur eine inaktive Vorschau. Die Schritte 1–3 beherrscht ein fremder KI-Assistent aber bereits über MCP: `find_place` (Geokodierung über das Adressverzeichnis), `nearby` (Auswahl der Datensätze nach Zweck oder Text und Abfrage an einem Punkt) und `summary`. Die Auswahl der Datensätze nach Schlüsselwörtern und Zwecken (`src/lib/search.ts`) nutzen auch die Katalogsuche und das MCP-Werkzeug `catalog`. Deshalb haben Manifeste die Felder `keywords` und `useCases` – sie bereiten die Daten für den Assistenten vor.

## Cache und eigene Datenschicht {#cache-a-vlastni-datova-vrstva}

Am Anfang sind die externen APIs der Anbieter die Datenquelle. Das Portal hält die Antworten im Cache (gemäß `cache.ttl`), damit die Quellen nicht belastet werden und die Karte schnell ist; fällt eine Quelle aus, kann es kurzzeitig die zuletzt bekannten Daten zeigen.

In den Bedingungen für Anbieter behalten wir uns vor, die Daten im Interesse von **Beschleunigung, Entlastung der Quellen, Nachhaltigkeit, besserer Kombinierbarkeit, dem Verknüpfen von Zusammenhängen und der Arbeit mit großen Datenmengen** in einem eigenen Cache / einer eigenen Datenschicht zu halten. Der Anbieter kann das beim Datensatz abschalten (`cache.store: false`).

## Bewertungen von Autorinnen und Autoren (nächste Version) {#autorska-hodnoceni-dalsi-verze}

Entwurf, noch nicht umgesetzt. Eine Ebene für Menschen mit eigener Meinung und eigenem Publikum – Bloggerinnen, Rezensenten, Vereine –, die Bewertungen von Orten zeigen wollen: „Kaffeehäuser laut …“, „Radwege laut …“, „Spielplätze laut …“. Jeder Ort hat eine Bewertung, ein kurzes Urteil und einen Link auf den Artikel.

Heute geht das nur allgemein: Die Autorin stellt ein eigenes Manifest und ein GeoJSON mit einem Zahlenfeld bereit und färbt die Punkte nach dem Wert ein. Das Portal weiß aber nicht, dass es sich um eine Bewertung handelt, und die Autorin muss die Daten selbst hosten.

Entwurf:

- **Wir hosten.** Die Autorin lädt CSV oder GeoJSON hoch oder klickt die Punkte auf der Karte an. Die Daten speichert das Portal (D1 / R2), eine eigene Website ist nicht nötig.
- **Bewertung als Begriff des Protokolls.** Visualisierungstyp `rating` und die Objektfelder `rating`, `ratingMax` (Standard 5), `review` (kurzes Urteil), `url` (Artikel) und `visited` (Datum des Besuchs). Das Portal zeigt Sterne im Detail, bietet einen Filter „ab N Sternen“ an und leitet die Legende selbst ab. Den Typ kann auch ein Anbieter mit eigenem Manifest verwenden.
- **Die Autorin ist sichtbar.** Eine Bewertung ist die Meinung eines konkreten Menschen, keine Angabe des Portals. Name und Link der Autorin stehen bei der Ebene und im Detail jedes Ortes.
- **Freigabe.** Die Ebene ist nicht im Katalog, bis der Betreiber sie freigibt – genauso wie bei der [Selbstregistrierung](https://datenkarte.at/dokumentation/fuer-datenanbieter.md#5-registrace).

Offene Fragen:

- **Konten.** Das Portal hat heute keine Benutzerkonten. Das Hochladen braucht eine Anmeldung (z. B. einen Link per E-Mail) und Schutz vor Missbrauch.
- **Freigabe von Änderungen.** Die Autorin wird die Daten laufend ergänzen. Einmal die Autorin freigeben oder jede Änderung?
- **Freie Punkte oder bestehende Orte?** Die Bindung an einen bestehenden Ort (z. B. einen Betrieb aus OpenStreetMap) erlaubt es, mehrere Autorinnen und Autoren bei einem Ort zu vergleichen, ist aber deutlich aufwendiger.
- **Zusammenfassungen.** Ein Durchschnitt mehrerer Autorinnen und Autoren nähert sich Bewertungsplattformen an und öffnet das Risiko der Manipulation (erfundene Autoren). Zu Beginn nur Ebenen nebeneinander.
- **Recht.** Eine negative Bewertung eines namentlich genannten Betriebs kann mit dem Schutz vor Kreditschädigung (§ 1330 ABGB) kollidieren. Nötig sind Bedingungen „die Autorin bzw. der Autor haftet für die eigenen Inhalte“, eine Meldefunktion für Orte und rasches Entfernen. Bewertet werden Orte, keine Privatpersonen.

## Plan {#plan}

1. **v0.1 (fertig):** Protokoll (Manifest + GeoJSON-Antwort), Katalog, Proxy mit Cache, Visualisierungen circle / heatmap / line / fill / raster / auto, Filter, Objektdetail, Quellenübersicht, Beispielanbieter; Dokumentation in Markdown, llms.txt, Validator, MCP-Server, OpenAPI.
2. **Registrierung von Anbietern:** Die Selbstregistrierung mit Freigabe ist fertig (Formular, API, MCP); offen ist das Monitoring der Verfügbarkeit der Quellen.
3. **Assistent:** für fremde KI-Assistenten fertig (MCP und API: Geokodierung über das Adressverzeichnis, Abfrage an Punkt und Umgebung einschließlich Rasterdatensätzen, Zusammenfassung für eine Gemeinde); offen ist ein eigener Assistent im Auswahlfenster (LLM über dem Katalog).
4. **Weitere Visualisierungen und Quellen:** Icons/Symbole, 3D-Extrusion von Flächen, Zeitachse, Ströme, Vektorkacheln (MVT/PMTiles), OGC API Features und WFS als Quelltyp.
5. **Eigene Datenschicht:** dauerhafte Speicherung der Daten (Cloudflare D1/R2, gegebenenfalls PostGIS), räumliche Abfragen über mehrere Quellen, vorberechnete Aggregationen für große Datenmengen.
6. **Bewertungen von Autorinnen und Autoren:** Bewertungsebenen von Bloggerinnen und Rezensenten, vom Portal gehostet, Visualisierungstyp `rating` (siehe [Entwurf](https://datenkarte.at/dokumentation/ueber-das-projekt.md#autorska-hodnoceni-dalsi-verze)).