Endpunkte

Jeder öffentliche Endpunkt der Kaleidr-Plattform-API wird in einem eigenen Abschnitt beschrieben.

Basis-URL: https://api.kaleidr.com/inference-api/b2b/v1
Zugangsdaten: Authorization: Bearer … oder X-Api-Key: …. Vom Backend aus ein Server-Schlüssel (kld_sk_live_…), im Browser ein Sitzungstoken (kld_sess_live_…). Ein veröffentlichbarer Schlüssel wird ausschließlich beim Sitzungsaustausch akzeptiert. Siehe Authentifizierung und Scopes.
Anfragekörper: JSON, UTF-8. Senden Sie bei jedem POST Content-Type: application/json. Der Anfragekörper darf 2 MiB groß sein, bei Endpunkten unter /design/* 5 MiB. Größere Anfragen werden mit 413 request_too_large abgelehnt.
Fehler: 4xx oder 5xx mit JSON-Körper, beschrieben unter Fehler. Ein Endpunkt meldet Fehler mit 200: siehe Routenplanung.

Die Beispiele verwenden einen Serverschlüssel aus einer Umgebungsvariablen:

export KALEIDR_KEY="kld_sk_live_…"

Zusammenfassung

Endpunkt	Zweck	Scope	Berechnung
`POST /sdk/sessions`	Veröffentlichbaren Schlüssel gegen Sitzung austauschen	Scope des Produkts	Eine Kartenladung bei `tile`, sonst nichts
`POST /sdk/share-sessions`	ID einer veröffentlichten Karte gegen Chat-Sitzung austauschen	keiner	Keine
`POST /chat/control/stream`	Frage stellen und Antwort samt Orten, Aktionen und Routen streamen	`ai`	KI-Credits nach verbrauchten Tokens
`POST /chat/control/route`	Route zwischen bekannten Koordinaten berechnen	`ai`	Keine
`GET /retrieval/geocode/forward`	Texteingabe in Orte und Adressen umwandeln	`ai`	KI-Credits, Pauschalgebühr
`POST /spot`	Was an einem Punkt liegt: Ort, Adresse, Regionen und optional Inhalte	`ai`	KI-Credits, Pauschalgebühr
`POST /spot/overview/stream`	Kurze Übersicht über ein von `/spot` zurückgegebenes Objekt streamen	`ai`	KI-Credits nach verbrauchten Tokens
`GET /retrieval/poi/enrich`	Veraltet, `/spot` verwenden. Details und Fotos eines Ortes	`ai`	KI-Credits, Pauschalgebühr
`POST /chat/summary/stream`	Veraltet, `/spot/overview/stream` verwenden. Kurzen Orts- oder Gebäudeüberblick streamen	`ai`	KI-Credits nach verbrauchten Tokens
`POST /chat/button/stream`	Antwort auf eine Frage zu einem Ort streamen	`ai`	KI-Credits nach verbrauchten Tokens
`POST /design/analyze`	Kartendesign für eine Datentabelle empfehlen	`design`	KI-Credits, Pauschalgebühr
`POST /design/apply-direct`	Kartenebene aus Tabelle und gewähltem Stil erstellen	`design`	Keine
`GET /design/styles`, `/design/samples`, `/design/themes`	Designkataloge	`design`	Keine

Wie Gebühren, Reservierungen und Limits funktionieren, erfahren Sie unter Kontingente und Ratenlimits.

Jeder Laufzeit-Endpunkt kann die unter Gemeinsame Fehler aller Laufzeit-Endpunkte aufgeführten Fehler zurückgeben. Die folgenden Abschnitte nennen nur endpunktspezifische Fehler.

POST /sdk/sessions

Tauscht einen veröffentlichbaren Schlüssel gegen ein kurzlebiges Sitzungstoken aus, das an den aufrufenden Ursprung und ein Produkt gebunden ist. Das SDK führt dies bei jeder schlüsselbasierten Einbindung aus. Rufen Sie den Endpunkt selbst nur in Ihrem eigenen Browserclient auf.

Authentifizierung: veröffentlichbarer Schlüssel. Erforderlich: Origin-Header (vom Browser hinzugefügt). Kosten: ein Kartenaufruf, wenn product gleich tile ist; sonst keine.

Feld	Typ	Erforderlich	Hinweise
`product`	Zeichenfolge	Ja	`chat`, `editor`, `viewer` oder `tile`.

curl -s https://api.kaleidr.com/inference-api/b2b/v1/sdk/sessions \
  -H "X-Api-Key: kld_pk_live_…" \
  -H "Origin: https://www.example.com" \
  -H "Content-Type: application/json" \
  -d '{"product":"chat"}'

{
  "session_token": "kld_sess_live_eyJhbGciOi…",
  "expires_in": 900,
  "product": "chat",
  "basemap_style_id": null
}

basemap_style_id ist die Standard-Basiskarte Ihrer Organisation oder null, wenn keine festgelegt wurde.

Status	Code	Wann
401	`Invalid or missing API key`	Der Schlüssel ist unbekannt, widerrufen oder abgelaufen.
403	`publishable_key_required`	Es wurde ein Server- oder Legacy-Schlüssel verwendet.
403	`origin_required`	Der Header `Origin` fehlt.
403	`origin_not_allowed`	Der Ursprung steht nicht in der Liste der erlaubten Ursprünge des Schlüssels.
403	`product_not_allowed`	Die erlaubten Produkte des Schlüssels enthalten `product` nicht.
403	`tier_capability_not_allowed`	Ihr Tarif umfasst das Produkt oder dessen Scope nicht.
403	`insufficient_scope`	Der Schlüssel wurde ohne den Scope des Produkts erstellt.
422	Validierung	`product` fehlt oder ist keiner der vier gültigen Werte.
429	`rate_limited`	Zu viele Sitzungsaustausche für diesen Schlüssel. `Retry-After: 5`.
429	`map_load_quota_exceeded`	Nur `tile`: Das Kartenladungs-Kontingent ist verbraucht.
404	`sessions_disabled`	Sitzungen sind auf der Plattform deaktiviert. Kontaktieren Sie den Support.
503	`sessions_not_configured`	Plattformfehler. Wiederholen Sie den Versuch und kontaktieren Sie bei anhaltendem Fehler den Support.

Gültigkeitsdauer, Erneuerungsregeln und Prüfreihenfolge stehen unter Authentifizierung und Berechtigungen: Sitzungsaustausch.

Tauscht die ID einer veröffentlichten Karte gegen eine Chat-Sitzung aus. So können Kartenbesucher ohne Schlüssel im Seitencode chatten. Die Kachel Kaleidr AI der Karte in Studio muss die angeforderte Funktion aktivieren.

Authentifizierung: keine. Erforderlich: Origin-Header. Kosten: keine; Chat-Aufrufe dieser Sitzung werden der Organisation des Kartenbesitzers berechnet.

Feld	Typ	Erforderlich	Hinweise
`share_id`	Zeichenfolge	Ja	1 bis 128 Zeichen: Buchstaben, Ziffern, `_` und `-`.
`feature`	Zeichenfolge	Nein	`control_tower` (Standard), das Panel Ask Kaleidr der Karte, oder `popups`, der AI-Chat in ihren Popups. Jede Funktion wird nur gewährt, solange ihr Schalter aktiviert ist.

curl -s https://api.kaleidr.com/inference-api/b2b/v1/sdk/share-sessions \
  -H "Origin: https://www.example.com" \
  -H "Content-Type: application/json" \
  -d '{"share_id":"your-map-id","feature":"control_tower"}'

{ "session_token": "kld_sess_live_eyJhbGciOi…", "expires_in": 300, "product": "chat" }

Status	Code	Wann
403	`origin_required`	Der Header `Origin` fehlt.
404	`not_found`	Keine veröffentlichte Karte und kein Freigabelink besitzt diese ID, oder die Karte des Freigabelinks ist nicht veröffentlicht.
403	`chat_disabled`	Die Kaleidr AI der Karte aktiviert die angeforderte Funktion nicht.
403	`origin_not_allowed`	Die Seite gehört nicht zu den erlaubten Domains der Karte.
403	`owner_has_no_organization`	Der Karteninhaber gehört keiner Organisation an.
403	`tier_capability_not_allowed`	Der Tarif des Inhabers umfasst Chat nicht.
422	Validierung	`share_id` fehlt oder enthält andere Zeichen, oder `feature` hat keinen der beiden Werte.
429	`rate_limited`	Zu viele Austauschvorgänge für diese Karte oder von dieser Adresse. `Retry-After: 5`.
404	`sessions_disabled`	Sitzungen sind plattformweit ausgeschaltet.
503	`share_grant_unavailable`, `sessions_not_configured`	Plattformfehler. Erneut versuchen.

Siehe Kaleidr AI auf einer veröffentlichten Karte.

POST /chat/control/stream

Stellt eine Frage und streamt die Antwort: fortlaufend geschriebenen Text, erwähnte Orte mit Koordinaten, Kartenaktionen und Routen. Dieser Endpunkt ist die Grundlage von Kaleidr Chat.

Authentifizierung: Server-, Sitzungs- oder Legacy-Schlüssel. Berechtigung: ai. Kosten: AI-Credits, entsprechend den Tokens der Antwort. Antwort: text/event-stream, beschrieben im SSE-Protokollvertrag.

Feld	Typ	Erforderlich	Standard	Hinweise
`messages`	Array aus `{ role, content }`	Nein	`[]`	Die bisherige Unterhaltung in zeitlicher Reihenfolge, zuletzt die neue Nutzerfrage. `role` ist `user` oder `assistant`. Nachrichten mit anderen Rollen, auch `system`, werden ignoriert, ebenso Nachrichten mit leerem `content`. Beantwortet wird die letzte `user`-Nachricht. Größenlimits stehen unten.
`session_id`	Zeichenfolge	Nein	generiert	Unterhaltungs-ID mit 1 bis 128 Zeichen aus Buchstaben, Ziffern, `_`, `.`, `:` und `-`. Nutzen Sie eine eigene dauerhafte ID und senden Sie diese in jeder Runde erneut. Ohne Angabe erzeugt der Server eine ID für die Anfrage und gibt sie in den Ereignissen `phase` und `start` zurück.
`location`	Objekt `{ lat, lng }`	Nein	keines	Ort, auf den der Nutzer blickt: Kartenmittelpunkt. Hilft bei Formulierungen wie „hier in der Nähe“.
`map_zoom`	Zahl	Nein	keiner	Zoomstufe der Karte.
`lang`	Zeichenfolge	Nein	`"en"`	Sprache der Antwort als BCP-47-Tag, etwa `fr` oder `pt-BR`. Höchstens 35 Zeichen.
`layout`	Zeichenfolge	Nein	keines	Das Viewer-Layout, in dem das Gespräch läuft: `"guide"`, solange der eingebettete Viewer sein Guide-Layout zeigt; sonst weglassen. Höchstens 16 Zeichen.
`app_snapshot`	Objekt	Nein	keines	Wird akzeptiert, ist aber nicht erforderlich; weglassen.
`auto_actions`	boolescher Wert	Nein	keiner	Wird akzeptiert, ist aber nicht erforderlich; weglassen.

Unbekannte Felder werden akzeptiert und ignoriert. Es gibt kein Feld für Systemanweisungen, eine Persona, Werkzeuge oder eigenen Kontext. Die Anfrage enthält die Unterhaltung, einen Ort und eine Sprache.

Der Server speichert das Transkript nicht für Sie. Senden Sie frühere Gesprächsschritte bei jedem Aufruf in messages zusammen mit derselben session_id.

Eine session_id gehört allein Ihnen. Der kurzfristige Unterhaltungskontext ist pro Organisation getrennt; eine andere Organisation, die dieselbe ID sendet, kann Ihre Unterhaltung weder sehen noch verändern. Innerhalb Ihrer Organisation muss jede Nutzerunterhaltung eine eigene ID haben.

Anfragelimits

Anfragen über einem dieser Limits werden vor der Antwort mit 422 abgelehnt und nicht berechnet. Der Antwortkörper lautet {"detail": "<code>"}.

Grenze	Wert	Code
Nachrichten in `messages`	400	`too_many_messages`
Länge des `content` einer Nachricht	64.000 Zeichen	`message_too_long`
Gesamtlänge aller `content`-Werte	200.000 Zeichen	`conversation_too_long`
`session_id`	1 bis 128 Zeichen: Buchstaben, Ziffern, `_`, `.`, `:`, `-`	`invalid_session_id`
`lang`	35 Zeichen	`lang_too_long`
`layout`	16 Zeichen	`invalid_layout`

Jede Nachricht zählt zu diesen Grenzen, auch ignorierte Nachrichten. Lange Unterhaltungen erreichen das Gesamtlängenlimit meist vor dem Nachrichtenlimit. Senden Sie daher nur die jüngsten Gesprächsrunden und lassen Sie ältere weg: siehe Stream lesen.

curl -N https://api.kaleidr.com/inference-api/b2b/v1/chat/control/stream \
  -H "Authorization: Bearer $KALEIDR_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -d '{
    "session_id": "trip-42",
    "messages": [{"role": "user", "content": "Where is the Louvre, and what is next to it?"}],
    "location": {"lat": 48.8566, "lng": 2.3522},
    "map_zoom": 12,
    "lang": "en"
  }'

-N deaktiviert die Ausgabepufferung von curl, sodass Frames sofort angezeigt werden. Gekürzte Beispielantwort:

event: phase
data: {"type": "phase", "phase": "thinking", "session_id": "trip-42"}

: keep-alive

event: start
data: {"type": "start", "session_id": "trip-42", "purpose": "control"}

data: {"text": "The [[Louvre Museum]] is on the right bank of the Seine"}

event: place
data: {"name": "Louvre Museum", "coordinates": {"lat": 48.8606, "lng": 2.3376}, "category": "museum"}

data: {"text": ", with the [[Tuileries Garden]] directly to its west."}

event: place
data: {"name": "Tuileries Garden", "coordinates": {"lat": 48.8635, "lng": 2.3275}, "category": "park"}

event: early_actions
data: {"type": "early_actions", "actions": [{"type": "map.fitBounds", "payload": {"coordinates": [[2.3376, 48.8606], [2.3275, 48.8635]], "padding": 50, "maxZoom": 15, "duration": 1000}}], "places_count": 2, "is_partial": true}

event: end
data: {"type": "end", "full_text": "The [[Louvre Museum]] is on the right bank of the Seine, with the [[Tuileries Garden]] directly to its west.", "places": [{"name": "Louvre Museum", "coordinates": {"lat": 48.8606, "lng": 2.3376}, "category": "museum"}, {"name": "Tuileries Garden", "coordinates": {"lat": 48.8635, "lng": 2.3275}, "category": "park"}], "actions": [], "question_type": "…", "response_time": 6.4, "total_tokens": 3120}

event: quota
data: {"type": "quota", "product": "b2b", "meter": "b2b.tokens", "tier": "pro", "used": 184223, "limit": 5000000, "reset_at": "2026-11-01T04:00:00+00:00", "period": "month"}

Status	Code	Wann
413	`request_too_large`	Der Anfragekörper ist größer als 2 MiB.
422	Validierung	Der Körper ist kein gültiges JSON oder ein Feld hat den falschen Typ.
422	`too_many_messages`, `message_too_long`, `conversation_too_long`, `invalid_session_id`, `lang_too_long`, `invalid_layout`	Die Anfrage überschreitet ein Anfragelimit.
429	`quota_exceeded`	Das KI-Credit-Kontingent oder das Monatslimit dieses Schlüssels reicht für den Aufruf nicht.

Das Ereignis quota im Beispiel ist die Version für einen Server-Schlüssel. Beim Lesen des Streams mit einem Sitzungstoken ist es kürzer: siehe Ereignis quota.

Nach dem Start eines Streams wird ein Fehler als error-Ereignis und nicht als HTTP-Status übermittelt. Informationen zum Erstellen eines Clients finden Sie unter Stream lesen.

POST /chat/control/route

Plant eine Route zwischen bereits bekannten Koordinaten. Es wird keine Frage gestellt und kein Text erzeugt.

Authentifizierung: Server-, Sitzungs- oder Legacy-Schlüssel. Berechtigung: ai. Kosten: keine. Für die Zulassung des Aufrufs muss jedoch noch Spielraum im AI-Credit-Kontingent bestehen.

Feld	Typ	Erforderlich	Standard	Hinweise
`places`	Array von Objekten	Ja, mindestens zwei	`[]`	Jedes Element hat `{ lat, lng, name? }` mit numerischen `lat` und `lng` direkt im Objekt. Statt `name` wird auch `label` akzeptiert. Ein Eintrag ohne numerische `lat` und `lng` wird ohne Fehlermeldung übersprungen.
`profile`	Zeichenfolge	Nein	`"driving"`	`driving`, `walking`, `cycling` oder `transit`. Andere Werte verwenden `driving`.
`raw_query`	Zeichenfolge	Nein	`"Show directions"`	Gegebenenfalls der vom Nutzer eingegebene Wortlaut.

Der erste Ort ist der Startpunkt, der letzte das Ziel.

Die Form eines Orts unterscheidet sich von der im Stream

Ein place-Ereignis im Chat-Stream verschachtelt die Position: { "coordinates": { "lat": …, "lng": … } }. Dieser Endpunkt erwartet lat und lng direkt im Objekt. Wenn Sie einen Stream-Ort unverändert übernehmen, erhalten Sie eine error-Antwort, da kein Eintrag verwendbare Koordinaten hat.

curl -s https://api.kaleidr.com/inference-api/b2b/v1/chat/control/route \
  -H "Authorization: Bearer $KALEIDR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "places": [
      {"name": "Louvre Museum", "lat": 48.8606, "lng": 2.3376},
      {"name": "Tuileries Garden", "lat": 48.8635, "lng": 2.3275}
    ],
    "profile": "walking"
  }'

Ein Erfolg ist eine 200-Antwort mit action (Beispielwerte):

{
  "action": {
    "type": "map.showRoute",
    "payload": {
      "id": "control-directions",
      "label": "Directions",
      "profile": "walking",
      "coordinates": [[2.3376, 48.8606], [2.3352, 48.8619], [2.3275, 48.8635]],
      "distance_m": 870,
      "duration_s": 640,
      "turn_by_turn": [{ "text": "Walk west on Rue de Rivoli." }],
      "attribution": {
        "text": "© OpenStreetMap contributors",
        "url": "https://www.openstreetmap.org/copyright",
        "license": "https://opendatacommons.org/licenses/odbl/"
      }
    }
  },
  "route": { "…": "the full planning result the action was built from" }
}

Zeichnen Sie action.payload.coordinates als Liste von [lng, lat]-Paaren. distance_m gibt Meter und duration_s Sekunden an. Zeigen Sie beim Zeichnen der Route attribution.text als Link zu attribution.url an.

Für profile: "transit" enthält payload.transit eine Verbindung mit nur einem Verkehrsmittel: Fußweg, Fahrt, Fußweg. Im obersten Payload-Objekt gibt es kein attribution; der Betreiberhinweis steht unter payload.transit.attribution. Zeigen Sie diesen Hinweis überall dort an, wo Sie die Fahrt darstellen.

Dieser Endpunkt meldet Fehler mit HTTP 200

Eine nicht planbare Route ist kein 4xx-Fehler. Die Antwort ist 200 mit der Zeichenfolge error und ohne action:

{ "error": "Route planning failed." }

Dies passiert, wenn die Routenplanung die Orte nicht verbinden kann oder aus einem anderen Grund scheitert. Haben weniger als zwei Orte brauchbare Koordinaten, lautet die Meldung At least two resolved places are required to build a route.. Die Meldung ist zur direkten Anzeige vorgesehen; prüfen Sie deshalb, ob error vorhanden ist, nicht dessen Wortlaut. Auch wenn im ÖPNV keine direkte Verbindung existiert, antwortet der Endpunkt so, ergänzt um einen Grund und die drei Felder reason, covered und available.

Entscheiden Sie anhand des Antwortkörpers, nicht des Status:

const res = await fetch(`${API}/chat/control/route`, { method: 'POST', headers, body });
if (!res.ok) throw new Error(`route request refused: ${res.status}`); // 401, 403, 422, 429
const data = await res.json();
if (data.error) {
  showMessage(data.error); // a 200 that is a failure
} else {
  drawLine(data.action.payload.coordinates);
}

Fehler bei Authentifizierung, Berechtigungen, Validierung, Kontingenten und Ratenlimits bleiben normale Antworten mit 401, 403, 422 oder 429.

GET /retrieval/geocode/forward

Wandelt eingegebenen Text in passende Orte und Straßenadressen um. Der Endpunkt ist für Suchfelder sowie Von-/Nach-Felder gedacht.

Authentifizierung: Server-, Sitzungs- oder Legacy-Schlüssel. Berechtigung: ai. Kosten: AI-Credits, eine Pauschale pro Aufruf, auch wenn results leer ist.

Parameter	Typ	Erforderlich	Standard	Hinweise
`q`	Zeichenfolge	Ja		1 bis 200 Zeichen: Ortsname, Straßenadresse mit Hausnummer oder `lat,lng` als Texteingabe.
`near_lat`	Zahl	Nein		−90 bis 90. Bevorzugt nähere Treffer. Nur zusammen mit `near_lng`.
`near_lng`	Zahl	Nein		−180 bis 180. Nur zusammen mit `near_lat`.
`limit`	Ganzzahl	Nein	`5`	1 bis 20.
`mode`	Zeichenfolge	Nein		Verkehrsart (`driving`, `walking`, `cycling`, `transit`). Bei kurzen Strecken werden nahe Treffer höher eingestuft.

curl -s -G https://api.kaleidr.com/inference-api/b2b/v1/retrieval/geocode/forward \
  -H "Authorization: Bearer $KALEIDR_KEY" \
  --data-urlencode "q=20 W 34th St, New York" \
  --data-urlencode "limit=3"

{
  "query": "20 W 34th St, New York",
  "results": [
    {
      "lat": 40.7484,
      "lng": -73.9857,
      "display_name": "20 W 34th St, New York, NY 10001",
      "type": "address",
      "source": "…",
      "id": "…",
      "confidence": "exact",
      "attribution": {
        "dataset": "us/ny/city_of_new_york",
        "license": "…",
        "attribution": "Address data from the NYC Department of City Planning."
      }
    }
  ],
  "attribution": {
    "text": "Overture Maps Foundation, overturemaps.org",
    "licenses": [
      "https://cdla.dev/permissive-2-0/",
      "https://www.apache.org/licenses/LICENSE-2.0",
      "https://opensource.foursquare.com/places-notice-txt/",
      "https://docs.overturemaps.org/attribution/"
    ],
    "sources": [
      {
        "dataset": "us/ny/city_of_new_york",
        "license": "…",
        "attribution": "Address data from the NYC Department of City Planning."
      }
    ]
  }
}

Jedes Ergebnis enthält lat, lng, display_name, type und source. Weitere Felder sind vorhanden, sofern zutreffend:

Ergebnisfeld	Bedeutung
`id`	Bei Straßenadressen: Kaleidrs ID für diese Haustür. Sie bleibt über Datenaktualisierungen hinweg gleich und kann gespeichert und verglichen werden.
`confidence`	Art des Texttreffers (siehe folgende Tabelle). Fehlt bei eingegebenem `lat,lng`.
`approximate`, `method`, `matched_numbers`, `within_m`, `score`	Nur bei geschätzten Adressen (siehe unten).
`attribution`	Bedingungen des Datensatzes, aus dem das Ergebnis stammt: `dataset`, `license` sowie gegebenenfalls `license_url`, `attribution` (anzuzeigender Quellenhinweis) und `use_restriction`.

`confidence`	Bedeutung des Treffers
`exact`	Die eingegebene Hausnummer an der eingegebenen Straße im gesuchten Ort.
`fuzzy`	Dasselbe, jedoch über einen falsch geschriebenen Straßennamen.
`name_exact`	Ein Ort, dessen Name genau dem eingegebenen Text entspricht.
`locality`	Die im Text genannte Stadt, Region oder Nachbarschaft.
`interpolated`, `nearest`	Schätzung für eine Hausnummer, die in den Daten fehlt.
`partial`	Ein längerer Straßenname, der mit dem eingegebenen beginnt.
`name_partial`	Ein Ort, dessen Name teilweise mit Ihrer Eingabe übereinstimmt.
`ambiguous`	Eine Adresse ohne genannten Ort und ohne nahen Bezugspunkt: eine von mehreren Möglichkeiten.

Geschätzte Adressen. Fehlt die eingegebene Hausnummer in den Daten, wird sie entlang ihrer Straße verortet: zwischen den nächsten bekannten Nummern auf derselben Straßenseite, an der nächsten bekannten Nummer oder innerhalb des Straßenblocks, dessen Nummernbereich sie umfasst. Das Ergebnis enthält approximate: true und:

Feld	Bedeutung
`method`	`"interpolated"` (zwischen zwei bekannten Nummern), `"nearest"` (an der nächstgelegenen bekannten Nummer) oder `"range"` (entlang des Straßenblocks).
`matched_numbers`	Die Nummern, aus denen die Lage geschätzt wurde.
`within_m`	Abstand zwischen diesen Nummern in Metern oder Länge des Straßenblocks: maximale Abweichung der Schätzung bei geordneter Nummerierung. Fehlt bei `"nearest"`.
`score`	Wert von 0 bis 1 für die Sicherheit der Schätzung. Bei niedrigen Werten sollte die Lage nur als Straßenabschnitt, nicht als Haustür gelten.

Bei einer exakten Übereinstimmung sind diese Felder niemals enthalten.

Quellenangaben. Geben Sie attribution auf oberster Ebene mit den Ergebnissen weiter. text enthält die anzuzeigende Quellenangabe und licenses die mit den Daten weiterzugebenden Nutzungsbedingungen. Bei Straßenadressen listet attribution.sources alle verwendeten Adressdatensätze auf. Für diese Ergebnisse gilt die jeweilige use_restriction:

Datensatz	Anzuzeigende Quellenangabe	Nutzungsbeschränkung
`au/countrywide` (G-NAF)	G-NAF © Geoscape Australia, lizenziert vom Commonwealth of Australia gemäß Open Geo-coded National Address File (G-NAF) End User Licence Agreement.	Nicht zum Erstellen einer Adresse oder Adresssammlung für Postsendungen, es sei denn, die Zustellbarkeit jeder Adresse wurde anhand einer anderen Quelle als G-NAF überprüft; die Nutzung muss den Australian Privacy Principles entsprechen.
`ca/countrywide` (Statistics Canada)	Adaptiert aus Statistics Canada, National Address Register, 2025-07-29. Dies bedeutet keine Empfehlung dieses Produkts durch Statistics Canada.	Nicht zur Identifizierung einer Person, eines Unternehmens oder einer Organisation und nicht zur Behauptung einer Empfehlung durch Statistics Canada.
`us/ny/city_of_new_york`	Adressdaten des NYC Department of City Planning.	Keine.
`us/ma/statewide` (MassGIS)	MassGIS (Bureau of Geographic Information), Commonwealth of Massachusetts EOTSS	Keine (gemeinfrei).

Kein Treffer und interner Fehler sehen gleich aus. Eine Suche ohne Treffer gibt 200 mit "results": [] zurück. Dasselbe gilt für intern gescheiterte Suchvorgänge; diese werden nicht berechnet. Behandeln Sie eine leere Liste als „nichts anzuzeigen“, nicht als Fehler.

Status	Code	Wann
422	Validierung	`q` fehlt, ist leer oder länger als 200 Zeichen; `limit` oder Koordinaten liegen außerhalb des zulässigen Bereichs.
429	`quota_exceeded`	Das KI-Credit-Kontingent reicht für den Aufruf nicht aus.

POST /spot

Ermittelt, was an einem Punkt liegt: den angeklickten Ort, die nächste Straßenadresse und die Regionen, die den Punkt einschließen. Jeder Wert nennt die Quellenangabe, die angezeigt werden muss. Auf Wunsch werden die Beschreibung und Fotos des Ortes ergänzt.

Authentifizierung: Server-, Sitzungs- oder Legacy-Schlüssel. Berechtigung: ai. Kosten: AI-Credits, eine Pauschale pro Aufruf abhängig vom teuersten unter want angeforderten Element, unabhängig davon, ob etwas gefunden wird: content oder photos kosten die Gebühr von /retrieval/poi/enrich, wenn der Inhalt für diesen Aufruf abgerufen wird, andernfalls kostet address die Gebühr von /retrieval/geocode/forward. Bereits für eine frühere Anfrage abgerufene Inhalte kosten nichts; fragt ein solcher Aufruf auch address ab, wird daher die Geokodierungsgebühr berechnet. Aufrufe, die ausschließlich entities, regions, boundaries oder tenants abfragen, sind kostenlos. Das standardmäßige want enthält address; ohne want wird daher die Geokodierungsgebühr berechnet.

Feld	Typ	Erforderlich	Standard	Hinweise
`lat`	Zahl	Ja		−90 bis 90. Der Punkt.
`lng`	Zahl	Ja		−180 bis 180.
`zoom`	Zahl	Nein		0 bis 24. Zoomstufe der Karte.
`hint`	Objekt	Nein		Worauf der Nutzer geklickt hat (unten).
`want`	Array von Zeichenfolgen	Nein	`["entities", "address", "regions"]`	Zurückzugebende Teile (unten).
`lang`	Zeichenfolge	Nein	`"en"`	Sprache für `content`. Maximal 16 Zeichen.

Der Punkt entscheidet, der Hinweis wählt nur aus. Ein Hinweis wählt unter den Dingen am Punkt und verschiebt das Ergebnis niemals: Ein Ort, der mehr als 75 Meter von lat, lng entfernt ist, wird unabhängig vom Hinweis nicht zurückgegeben.

`hint`-Feld	Hinweise
`id`	Kaleidrs Kennung für den Ort: der Teil einer `poi:`-Referenz nach dem Doppelpunkt.
`name`	Der Name des Ortes, wie er auf der Kartenbeschriftung erscheint. Maximal 200 Zeichen. Er wird exakt mit den Orten am angegebenen Punkt abgeglichen und bezeichnet den Ort für `content`. Ist `region_level` auf `county`, `state` oder `country` gesetzt, wählt der Name außerdem die Region dieser Ebene aus, deren Name übereinstimmt. Dabei werden Groß-/Kleinschreibung und diakritische Zeichen ignoriert. Berücksichtigt werden die Regionen am Punkt (bei einem Bundesstaat oder Land auch diejenigen bis zu 5 km vom Punkt entfernt). Wenn der Name mit keiner Region übereinstimmt, ändert sich nichts.
`category`	Die Kategorie des Ortes. Maximal 100 Zeichen. Wird für `content` verwendet.
`region_level`	Mit `boundaries` wird nur der Umriss der Region auf dieser Ebene (`city`, `county`, `state` oder `country`) zurückgegeben; ohne diese Angabe die Umrisse aller Regionen. Bei Angabe von `name` wird die Region dieser Ebene sowohl in `regions` als auch in `boundaries` durch den Namen ausgewählt.
`layer`, `wiki_title`, `ta_location_id`, `yelp_business_id`, `data_source`	Akzeptiert. Wird von Kaleidrs eigenen Apps verwendet; lassen Sie diese Felder weg.

`want`-Wert	Fügt hinzu
`entities`	Den angeklickten Ort, sofern `hint` einen Ort an diesem Punkt benennt.
`address`	Die nächstgelegene Straßenadresse.
`regions`	Stadt und County (nur in den USA), Bundesstaat und Land, in denen der Punkt liegt. Bei einem Punkt bis zu 5 km vor der Küste werden der nächstgelegene Bundesstaat und das nächstgelegene Land zurückgegeben.
`boundaries`	`regions`, jeweils mit Umriss (bei `hint.region_level` nur für eine Ebene).
`content`	Beschreibende Inhalte zum Ort: eine Zusammenfassung, Fotos und einen Link. Erfordert einen Ortsnamen, entweder vom angeklickten Ort oder aus `hint.name`.
`photos`	Nur die Fotos des Ortes. Es fallen dieselben Kosten an wie für `content`.
`tenants`	Benannte Orte in der Nähe des Punkts, beginnend mit den nächstgelegenen: die Unternehmen in einem Gebäude. Ihre App behält diejenigen bei, die innerhalb des dargestellten Gebäudegrundrisses liegen.

curl -s https://api.kaleidr.com/inference-api/b2b/v1/spot \
  -H "Authorization: Bearer $KALEIDR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "lat": 40.7484,
    "lng": -73.9857,
    "zoom": 17,
    "hint": {"name": "Empire State Building", "category": "landmark"},
    "want": ["entities", "address", "regions"]
  }'

Eine gekürzte Antwort mit Beispielwerten:

{
  "spot": { "lat": 40.7484, "lng": -73.9857, "zoom": 17 },
  "entities": [
    {
      "ref": "poi:3f1c2a9e-…",
      "kind": "poi",
      "role": "clicked",
      "name": { "value": "Empire State Building", "license": "CDLA-Permissive-2.0", "attr": "a1" },
      "at": { "lat": 40.74844, "lng": -73.98566 },
      "facts": {
        "category": { "value": "landmark_and_historical_building", "license": "CDLA-Permissive-2.0", "attr": "a1" },
        "website": { "value": "https://www.esbnyc.com", "license": "CDLA-Permissive-2.0", "attr": "a1" }
      }
    }
  ],
  "address": {
    "ref": "address:ka1…",
    "line": { "value": "20 W 34th St, New York, NY 10001", "license": "CDLA-Permissive-2.0", "attr": "a2" },
    "at": { "lat": 40.7484, "lng": -73.9857 }
  },
  "regions": [
    {
      "ref": "region:tiger:3651000",
      "kind": "region",
      "level": "city",
      "name": { "value": "New York", "license": "LicenseRef-Public-Domain", "attr": "a3" },
      "label": { "lat": 40.6976, "lng": -73.9795 }
    },
    {
      "ref": "region:tiger:36",
      "kind": "region",
      "level": "state",
      "name": { "value": "New York", "license": "LicenseRef-Public-Domain", "attr": "a3" },
      "label": { "lat": 42.7559, "lng": -75.8099 }
    }
  ],
  "attributions": {
    "a1": { "text": "© Overture Maps Foundation", "license": "CDLA-Permissive-2.0" },
    "a2": { "text": "Address data from the NYC Department of City Planning.", "license": "CDLA-Permissive-2.0" },
    "a3": { "text": "U.S. Census Bureau, TIGER/Line", "license": "LicenseRef-Public-Domain" }
  },
  "withheld": ["building_facts"]
}

Feld	Bedeutung
`spot`	Der übermittelte Punkt: `{ lat, lng, zoom }`.
`entities`	Der angeklickte Ort und auf Anfrage die Mieter, sonst eine leere Liste. Jeder Eintrag hat `ref`, `kind` (`"poi"` für den angeklickten Ort, `"tenant"` für einen Mieter), `role` (`"clicked"` oder `"inside"`), `name`, `at` (eigene Position des Ortes, `{ lat, lng }`) und `facts` (`category` sowie bei Bekanntheit `website` des angeklickten Orts). Die `ref` eines Mieters ist eine `poi:`-Referenz, also kann dessen Übersicht ebenfalls gestreamt werden. Unbekannte `kind`-Werte ignorieren.
`address`	Nächste Straßenadresse oder `null`: `{ ref, line, at }`.
`regions`	Regionen, die den Punkt enthalten, kleinste zuerst. Jede besitzt `ref`, `kind` (`"region"`), `level` (`city`, `county`, `state` oder `country`), `name` und `label`: einen Punkt zur Beschriftung der Region, `{ lat, lng }`, oder `null`. Mit `want: ["boundaries"]` enthält sie zusätzlich `geometry`, den Umriss als GeoJSON-Geometrie.
`content`	Vorhanden, wenn `want` `content` oder `photos` enthält, ein Ortsname bekannt ist und Inhalte verfügbar sein dürfen. Entspricht dem Objekt von `/retrieval/poi/enrich` (Felder) bzw. bei nur `photos` dem Objekt `{ photos, source, cached }`, jeweils um `license` und `attr` ergänzt. Wenn keine Inhalte abrufbar waren, kann es `null` sein.
`attributions`	Quellenangaben der Antwort: `{ text, license }`, über das `attr` der Werte indiziert.
`withheld`	Nach Art aufgeschlüsselte Inhalte, die von der API nicht zurückgegeben werden dürfen; leere Liste, wenn nichts ausgelassen wurde.

Eine ref bezeichnet ein Objekt für /spot/overview/stream: poi:<id> für einen Ort, address:<id> für eine Adresse, region:<source>:<id> für eine Region (<source> ist tiger, nuts oder ne). Kaleidr-Apps verwenden auch building:<id>, was die API jedoch nicht zurückgibt. Behandeln Sie Referenzen als undurchsichtige Zeichenfolgen.

Quellenangabe für jeden Wert anzeigen

Jeder Datensatzwert ist ein Objekt { value, license, attr }: Wert, Lizenz und ein Schlüssel zu attributions. Zeigen Sie bei jeder Wertanzeige auch attributions[attr].text an, entweder daneben oder in einem erreichbaren Quellenbereich. Eine Antwort kann verschiedene Quellen mischen; eine einzige Quellenangabe für die gesamte Antwort reicht daher nicht. Speichern und übertragen Sie license und die Quellenangabe zusammen mit dem Wert.

content wird auf dieselbe Weise über sein eigenes attr zugeordnet. Ein Wert mit live_only: true darf nur dem aktuellen Nutzer angezeigt, niemals gespeichert oder weitergegeben werden.

Die Anforderungen der einzelnen Lizenzen finden Sie unter Datenlizenzen.

Was die API nicht zurückgibt

Die eigenen Kaleidr-Anwendungen zeigen an einem Punkt mehr Informationen als die API zurückgibt, da einige Daten nicht zur Nutzung auf anderen Websites lizenziert sind:

Werte unter der ODbL aus OpenStreetMap: Gebäudefakten wie Stockwerke, Höhe und Klasse. Gebäudeübersichten stehen ebenfalls nicht zur Verfügung.
Ergebnisse von Drittanbietern: Adressabfragen bei Geocoding-Diensten sowie Bewertungen, Rezensionen und Fotos von Yelp und Tripadvisor.

withheld unterscheidet zwischen „hier ist nichts bekannt“ und „nicht über die API verfügbar“. Es nennt nur Arten, keine Werte: building_facts, wenn der Punkt in einem Gebäude liegt; content, wenn der einzige verfügbare Ortsinhalt möglicherweise nicht weitergegeben werden darf. Weitere Einträge benennen andere ausgelassene Teile der Antwort.

Fehler von POST /spot:

Status	Code	Wann
413	`request_too_large`	Der Anfragekörper ist größer als 2 MiB.
422	Validierung	`lat` oder `lng` fehlt oder liegt außerhalb des Bereichs, `zoom` liegt nicht zwischen 0 und 24, `want` enthält einen unbekannten Wert oder ein Feld ist zu lang bzw. fehlerhaft.
429	`quota_exceeded`	Das KI-Credit-Kontingent reicht für den Aufruf nicht aus.

Ein Teil, der nicht abgefragt werden konnte, wird leer (null oder []) zurückgegeben. Der Aufruf wird trotzdem berechnet.

POST /spot/overview/stream

Streamt eine kurze schriftliche Übersicht über ein von /spot zurückgegebenes Objekt, das durch seinen ref bezeichnet wird.

Authentifizierung: Server-, Sitzungs- oder Legacy-Schlüssel. Berechtigung: ai. Kosten: AI-Credits, entsprechend den genutzten Tokens. Jede Übersicht wird für ihren Aufruf erstellt. Antwort: text/event-stream: in der Regel ein place-Frame mit dem vollständigen Namen des Orts, etwa "Springfield, Ohio, United States of America", danach die Frames einer Ortszusammenfassung. Siehe Zusammenfassungs- und Button-Streams.

Feld	Typ	Erforderlich	Standard	Hinweise
`ref`	Zeichenfolge	Ja		Eine `ref` aus der Antwort von `/spot`, bis 128 Zeichen, oder `place:` (unten).
`lat`, `lng`	Zahl	Ja		Der an `/spot` gesendete Punkt.
`lang`	Zeichenfolge	Nein	`"en"`	Sprache des Texts. Höchstens 16 Zeichen.
`hint`	Objekt	Nur für `place:`		`{ name, category? }`: zu beschreibende Bezeichnung.

`ref`	Übersicht
`poi:<id>`	Der Ort.
`region:<source>:<id>`	Die Region.
`place:`	Eine benannte Beschriftung, für die Kaleidr keinen Datensatz hat, etwa ein Ort ohne Entität in `/spot`. Namen unter `hint.name` angeben.
`address:<id>`, `building:<id>`	Über die API nicht verfügbar: Der Stream sendet einen `error`-Frame. Siehe Was die API nicht zurückgibt.

Das Objekt wird unter lat, lng erneut gesucht; keine Angabe in der Anfrage gilt daher als Tatsache darüber. Eine poi:-Referenz mehr als 75 Meter vom Punkt entfernt, eine region:-Referenz, deren Region den Punkt nicht umfasst, sowie place: ohne hint.name erhalten ebenfalls einen error-Frame.

curl -N https://api.kaleidr.com/inference-api/b2b/v1/spot/overview/stream \
  -H "Authorization: Bearer $KALEIDR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"ref": "poi:3f1c2a9e-…", "lat": 40.7484, "lng": -73.9857, "lang": "en"}'

Eine nicht beschreibbare Referenz wird mit diesem Frame statt mit einer Zusammenfassung beantwortet. Er enthält ref, aber kein partial_text:

event: error
data: {"type": "error", "message": "Nothing to describe here.", "ref": "address:ka1…"}

Status	Code	Wann
413	`request_too_large`	Der Anfragekörper ist größer als 2 MiB.
422	Validierung	`ref` hat nicht eines der oben genannten Formate, `lat` oder `lng` fehlt oder ist ungültig, oder `lang` ist länger als 16 Zeichen.
429	`quota_exceeded`	Das KI-Credit-Kontingent reicht für den Aufruf nicht aus.

Migration von veralteten Endpunkten

GET /retrieval/poi/enrich und POST /chat/summary/stream sind veraltet. Sie antworten bis einschließlich 2027-01-15 wie bisher und können danach jederzeit entfernt werden. Ihre Antwort-Header weisen darauf hin; Deprecation nennt als Unix-Zeit den Tag der Abkündigung, 2026-10-16:

Deprecation: @1792108800
Sunset: Fri, 15 Jan 2027 00:00:00 GMT
Link: </inference-api/b2b/v1/spot>; rel="successor-version"

Der Link-Header von /chat/summary/stream verweist auf /inference-api/b2b/v1/spot/overview/stream. Protokollieren Sie den Sunset-Header, um noch verwendete Aufrufe zu finden.

Von GET /retrieval/poi/enrich zu POST /spot:

Bisher	Danach
`lat`, `lon` (Abfrage)	`lat`, `lng` (Körper). Beachten Sie den Feldnamen.
`name`, `category`	`hint.name`, `hint.category`
`lang`	`lang`, bis 16 Zeichen
Vollständige Abfrage	`want: ["content"]`
`photos_only=true`	`want: ["photos"]`
`radius`, `dataSource`, `ta_location_id`, `regionLevel`	Weglassen.
Antwortkörper	`content`: dasselbe Objekt mit zusätzlichem `live_only`
`attribution`	`content.attribution`

Die Kosten bleiben gleich oder sinken: /spot berechnet nichts für Inhalte, die bereits für eine frühere Anfrage abgerufen wurden. Eine Abfrage kostet so viel wie das teuerste Element in want; wird der Inhalt für den Aufruf abgerufen, erhalten Sie entities, address oder regions daher ohne Aufpreis mit demselben Aufruf.

Von POST /chat/summary/stream zu POST /spot/overview/stream:

Bisher	Danach
Ein Ort: `location`, `building_properties.name`, `.category`	`/spot` mit dem Punkt und `hint: { name, category }` aufrufen, dann die Übersicht zur `ref` des Ortes aus `entities` mit demselben `lat` und `lng` streamen. Ist `entities` leer, `ref: "place:"` mit demselben `hint` senden.
`building_properties.pid`	`ref: "poi:<id>"`
`lang`	`lang`, bis 16 Zeichen
`max_tokens`	Weglassen.
Ein Gebäude: `type: "building"` und dessen Felder	Kein Nachfolger. Die Gebäudeübersicht ist nicht über die API verfügbar.
Die Frames	Frames einer Ortszusammenfassung, nach einem neuen `place`-Frame, der den Ort benennt.

GET /retrieval/poi/enrich

Veraltet

Dieser Endpunkt ist veraltet und kann nach 2027-01-15 entfernt werden. Verwenden Sie POST /spot mit want: ["content"]. Siehe Migration von veralteten Endpunkten.

Liefert beschreibende Inhalte zu einem Ort: Titel, Zusammenfassung, Fotos und Link.

Authentifizierung: Server-, Sitzungs- oder Legacy-Schlüssel. Berechtigung: ai. Kosten: AI-Credits, eine Pauschale pro Aufruf. Die Gebühr fällt auch an, wenn kein Inhalt gefunden wurde.

Parameter	Typ	Erforderlich	Standard	Hinweise
`lat`	Zahl	Ja		Breitengrad des Orts.
`lon`	Zahl	Ja		Längengrad des Orts. Beachten Sie den Feldnamen `lon`, nicht `lng`.
`name`	Zeichenfolge	Nein		Name des Orts. Empfohlen, da nur ein Punkt oft keine Treffer liefert.
`category`	Zeichenfolge	Nein		Ortskategorie aus einem `place`-Ereignis.
`radius`	Ganzzahl	Nein	`250`	Suchradius in Metern um den Punkt.
`lang`	Zeichenfolge	Nein	`"en"`	Sprache der Inhalte.
`photos_only`	boolescher Wert	Nein	`false`	Nur Fotos zurückgeben (kleinere Antwort, siehe unten).
`dataSource`, `ta_location_id`, `regionLevel`	Zeichenfolge	Nein		Werden akzeptiert. Hinweise für Kaleidrs Apps; weglassen.

curl -s -G https://api.kaleidr.com/inference-api/b2b/v1/retrieval/poi/enrich \
  -H "Authorization: Bearer $KALEIDR_KEY" \
  --data-urlencode "lat=48.8606" \
  --data-urlencode "lon=2.3376" \
  --data-urlencode "name=Louvre Museum" \
  --data-urlencode "category=museum"

{
  "source": "wikipedia",
  "found": true,
  "title": "Louvre",
  "photos": ["https://upload.wikimedia.org/…/Louvre_Museum.jpg"],
  "summary": "The Louvre is a national art museum in Paris, France…",
  "rating": null,
  "phone": null,
  "hours": null,
  "reviews": [],
  "url": "https://en.wikipedia.org/wiki/Louvre",
  "attribution": ["Wikipedia"]
}

Feld	Typ	Bedeutung
`source`	Zeichenfolge	Quelle der Inhalte. `"omitted"` bedeutet, dass Inhalte existieren, aber möglicherweise nicht über die API zurückgegeben werden dürfen (unten).
`found`	boolescher Wert	`false`, wenn nichts gefunden wurde. Die übrigen Felder sind dann leer.
`title`	Zeichenfolge	Titel des Orts in der Quelle.
`summary`	Zeichenfolge oder null	Kurze Beschreibung.
`photos`	Array von URLs	Kann leer sein.
`url`	Zeichenfolge oder null	Link zur Quellseite.
`attribution`	Array von Zeichenfolgen	Zu nennende Quellen, z. B. `["Wikipedia"]`. Mit den Inhalten anzeigen.
`rating`, `phone`, `hours`, `reviews`		Können `null` oder leer sein. Bewertungen und Rezensionen lizenzierter Anbieter werden nie über die API ausgegeben.
`unverified`	boolescher Wert	Optional; `true`, wenn die Übereinstimmung mit dem Ort unsicher ist.

Mit photos_only=true lautet die Antwort { "photos": […], "source": "…", "cached": false }.

Zurückgehaltene Inhalte. Manche Inhalte sind nur für die Kaleidr-Apps lizenziert. Wenn nur solche Inhalte zu einem Ort vorliegen, liefert der Aufruf 200 mit "source": "omitted", "found": false und ohne Inhalte. Die Abfrage wird trotzdem berechnet. Siehe Datenlizenzen.

Status	Code	Wann
422	Validierung	`lat` oder `lon` fehlt oder ist keine Zahl.
429	`quota_exceeded`	Das KI-Credit-Kontingent reicht für den Aufruf nicht aus.
500	`An internal error occurred. Please try again.`	Die Suche ist fehlgeschlagen. Der Aufruf wird trotzdem berechnet.

POST /chat/summary/stream

Veraltet

Dieser Endpunkt ist veraltet und kann nach 2027-01-15 entfernt werden. Verwenden Sie POST /spot/overview/stream. Für Gebäudezusammenfassungen gibt es keinen Nachfolger. Siehe Migration von veralteten Endpunkten.

Streamt eine kurze schriftliche Zusammenfassung eines Ortes oder Gebäudes. Dies ist die Grundlage der Ortskarte in Kaleidr Chat.

Authentifizierung: Server-, Sitzungs- oder Legacy-Schlüssel. Berechtigung: ai. Kosten: AI-Credits, entsprechend den genutzten Tokens. Jede Zusammenfassung wird für ihren Aufruf neu erstellt. Antwort: text/event-stream. Siehe Zusammenfassungs- und Button-Streams.

Das Feld type im Anfragetext bestimmt die Art der Zusammenfassung.

Ein Gebäude ("type": "building"):

Feld	Typ	Erforderlich	Hinweise
`type`	Zeichenfolge	Ja	`"building"`.
`address`	Zeichenfolge	Ja	Vollständige Gebäudeadresse. Maximal 500 Zeichen.
`lat`, `lng`	Zahl	Nein	Gebäudeposition.
`building_levels`	Ganzzahl	Nein	Anzahl der Geschosse, falls bekannt.
`building_height_m`	Zahl	Nein	Gebäudehöhe in Metern, falls bekannt.
`tenant_names`	Array von Zeichenfolgen	Nein	Unternehmen im Gebäude. Maximal 100 Namen mit jeweils höchstens 200 Zeichen.
`poi_count`	Ganzzahl	Nein	Anzahl der Orte im Gebäude.
`lang`	Zeichenfolge	Nein	Standard `"en"`. Bis 35 Zeichen.

curl -N https://api.kaleidr.com/inference-api/b2b/v1/chat/summary/stream \
  -H "Authorization: Bearer $KALEIDR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"type": "building", "address": "20 W 34th St, New York, NY 10001", "lat": 40.7484, "lng": -73.9857}'

event: start
data: {"type": "start", "address": "20 W 34th St, New York, NY 10001"}

data: {"text": "A landmark office tower in Midtown Manhattan"}

event: end
data: {"type": "end", "full_text": "A landmark office tower in Midtown Manhattan…", "parsed": {"…": "…"}, "total_tokens": 910}

event: quota
data: {"type": "quota", "product": "b2b", "meter": "b2b.tokens", "tier": "pro", "used": 185133, "limit": 5000000, "reset_at": "2026-11-01T04:00:00+00:00", "period": "month"}

Ein Ort (type fehlt oder ist "poi"). Der Anfragekörper akzeptiert location (Objekt { lat, lng }), building_properties (Objekt), lang und max_tokens (Ganzzahl). Diese Variante ist auf Kaleidrs eigenes Panel zugeschnitten; die genaue Bedeutung der Felder ist noch kein veröffentlichter Vertrag. Fragen Sie einen Ort aus eigenem Code bevorzugt über /chat/control/stream ab.

Ortsfeld	Grenze
`building_properties.name`, `.type`, `.category`, `.poi_type`	Jeweils 200 Zeichen
`building_properties.pid`	128 Zeichen
Jedes Textfeld von `building_properties.event`	4.000 Zeichen
`lang`	35 Zeichen
`max_tokens`	Werte oberhalb des Endpunkt-Standards werden auf diesen Standard reduziert. Eine längere Zusammenfassung ist nicht anforderbar.

Beide Varianten lesen nur die hier aufgeführten Felder. Weitere Felder im Anfragekörper werden ignoriert. Überschreitet ein Feld seine Längengrenze, wird die Anfrage vor Erstellung einer Zusammenfassung mit 422 field_too_long abgelehnt.

Status	Code	Wann
413	`request_too_large`	Der Anfragekörper ist größer als 2 MiB.
422	`field_too_long`	Ein Feld überschreitet seine Länge oder `tenant_names` hat mehr als 100 Einträge. Der Körper lautet `{"detail": "field_too_long"}`.
500	`Summary stream error`	Der Anfragekörper konnte nicht gelesen werden oder bei einer Gebäudeanfrage fehlt `address`. Für andere fehlerhafte Körper antwortet dieser Endpunkt mit 500 statt 422.
429	`quota_exceeded`	Das KI-Credit-Kontingent reicht für den Aufruf nicht aus.

POST /chat/button/stream

Streamt die Antwort auf eine einzelne Frage zu einem Ort, zum Beispiel „Wie sind die Öffnungszeiten?“. Der Endpunkt unterstützt die Frage-Schaltflächen auf der Ortskarte in Kaleidr Chat. Er führt keine Unterhaltung: Jeder Aufruf ist unabhängig.

Authentifizierung: Server-, Sitzungs- oder Legacy-Schlüssel. Berechtigung: ai. Kosten: AI-Credits, entsprechend der Anzahl genutzter Tokens. Antwort: text/event-stream. Siehe Zusammenfassungs- und Button-Streams.

Feld	Typ	Erforderlich	Standard	Hinweise
`query`	Zeichenfolge	Ja		Die Frage. Maximal 4.000 Zeichen.
`place_name`	Zeichenfolge	Nein		Name des gefragten Ortes. Maximal 200 Zeichen.
`place_type`	Zeichenfolge	Nein		Ortskategorie. Maximal 200 Zeichen.
`address`	Zeichenfolge	Nein		Adresse des Ortes. Maximal 500 Zeichen.
`location`	Objekt `{ lat, lng }`	Nein		Seine Position.
`lang`	Zeichenfolge	Nein	`"en"`	Sprache der Antwort. Maximal 35 Zeichen.
`description`	Zeichenfolge	Nein		Ihnen bereits bekannte Ortsbeschreibung. Maximal 4.000 Zeichen.
`website`	Zeichenfolge	Nein		Website des Ortes, falls bekannt. Maximal 2.048 Zeichen.
`stores_preview`	Array von Objekten `{ name }`	Nein		Bereits bekannte Unternehmen am Ort. Höchstens 50 Einträge; jeder `name` bis 200 Zeichen. Weitere Mitglieder eines Eintrags werden ignoriert.
`button_id`, `session_id`, `place_id`	Zeichenfolge	Nein		Eigene IDs zur Zuordnung. Jeweils bis 128 Zeichen.

Felder, die nicht in dieser Tabelle stehen, werden ignoriert. Überschreitet ein Feld seine Längenbegrenzung, wird die Anfrage vor der Antwort mit 422 field_too_long abgelehnt.

curl -N https://api.kaleidr.com/inference-api/b2b/v1/chat/button/stream \
  -H "Authorization: Bearer $KALEIDR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "What is this place known for?",
    "place_name": "Louvre Museum",
    "place_type": "museum",
    "location": {"lat": 48.8606, "lng": 2.3376}
  }'

event: start
data: {"type": "start", "query_type": "…"}

data: {"text": "The Louvre is best known for"}

event: end
data: {"type": "end", "full_text": "The Louvre is best known for…", "reply": "The Louvre is best known for…", "query_type": "…", "first_token_ms": 820, "total_ms": 3900, "total_tokens": 640}

Status	Code	Wann
413	`request_too_large`	Der Anfragekörper ist größer als 2 MiB.
422	`field_too_long`	Ein Feld ist zu lang oder `stores_preview` hat mehr als 50 Einträge. Der Körper lautet `{"detail": "field_too_long"}`.
500	`Button chat stream error`	Der Körper kann nicht gelesen werden oder `query` fehlt. Andere ungültige Körper ergeben hier 500 statt 422.
429	`quota_exceeded`	Das KI-Credit-Kontingent reicht für den Aufruf nicht aus.

POST /design/analyze

Untersucht die Spalten und eine Tabellenstichprobe und empfiehlt eine passende Kartendarstellung.

Das eingebettete Editor-Element ruft die Design-Endpunkte nicht auf. Diese bilden eine REST-Schnittstelle für eigene Werkzeuge.

Authentifizierung: Server-, Sitzungs- oder Legacy-Schlüssel. Berechtigung: design. Kosten: AI-Credits, eine Pauschale pro erfolgreichem Aufruf. Fehlerhafte Aufrufe werden nicht berechnet.

Feld	Typ	Erforderlich	Hinweise
`columns`	Array von Zeichenfolgen	Ja	1 bis 256 Spaltennamen, jeder eindeutig.
`sampleRows`	Array von Objekten	Nein	Bis zu 1.000 Zeilen, jedes Objekt mit Spaltennamen als Schlüsseln.
`datasetName`	Zeichenfolge	Nein	Maximal 512 Zeichen.
`rowCount`	Ganzzahl	Nein	Gesamtzahl der Zeilen in der Tabelle, mindestens 0.
`userGoal`	Zeichenfolge	Nein	Bis zu 1.000 Zeichen: Was die Karte zeigen soll.
`supportedStyles`	Array von Zeichenfolgen	Nein	Wählbare Stil-IDs, bestehend aus kleingeschriebenen Wörtern mit Bindestrichen.

Feldnamen verwenden camelCase. Unbekannte Felder werden ignoriert.

curl -s https://api.kaleidr.com/inference-api/b2b/v1/design/analyze \
  -H "Authorization: Bearer $KALEIDR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "datasetName": "stores.csv",
    "columns": ["name", "lat", "lng", "revenue"],
    "sampleRows": [
      {"name": "Downtown", "lat": 40.7128, "lng": -74.0060, "revenue": 120000},
      {"name": "Uptown", "lat": 40.7831, "lng": -73.9712, "revenue": 86000}
    ],
    "rowCount": 240,
    "userGoal": "Show which stores earn the most"
  }'

{
  "datasetProfile": { "…": "what was detected in each column" },
  "designPlan": { "…": "the recommended style, theme and reasoning" },
  "issues": [],
  "recommendation": { "…": "…" },
  "suggestedConfig": { "…": "…" },
  "explanation": "…"
}

Lesen Sie designPlan. Es kann null sein. recommendation, suggestedConfig und explanation sind ältere, nur zur Kompatibilität erhaltene Felder, die entfernt werden sollen; bauen Sie nicht darauf auf. issues nennt Probleme, die in den Daten gefunden wurden.

Status	Code	Wann
413	`request_too_large`	Der Körper ist größer als 5 MiB. Dasselbe Limit gilt für `/design/apply-direct`.
422	Validierung	`columns` fehlt, ist leer, zu lang oder enthält doppelte Werte; ein obiges Limit ist überschritten.
429	`quota_exceeded`	Das KI-Credit-Kontingent reicht für den Aufruf nicht aus.
500	`map_design_analyze_failed`	Analyse fehlgeschlagen. Keine Berechnung.

POST /design/apply-direct

Erstellt eine Kartenebene aus einer Tabelle und einem ausgewählten Stil, ohne Analyse.

Authentifizierung: Server-, Sitzungs- oder Legacy-Schlüssel. Berechtigung: design. Kosten: keine.

Feld	Typ	Erforderlich	Hinweise
`style`	Zeichenfolge	Ja	Stil-ID mit 1 bis 64 Zeichen. IDs stehen unter `/design/styles`.
`config`	Objekt	Ja	Objekt mit `location`, `metric` und `visual`. Erforderlich sind `location.mode` (`"coordinates"` oder `"region"`) und `visual.layerName`; die übrigen Unterfelder sind noch nicht dokumentiert.
`table`	Objekt	Ja	`{ fileName?, columns[], rows[] }`. Jede Zeile ist ein Objekt aus Spaltenname und Wert. Jeder Wert muss eine JSON-Zeichenfolge sein: `"120000"` senden, nicht `120000`. Eine Zeile mit einer Zahl oder `null` wird mit 422 abgelehnt.
`layerLabel`	Zeichenfolge	Ja	Sichtbarer Name der Ebene, 1 bis 512 Zeichen.
`themePackId`	Zeichenfolge	Nein	Themen-ID aus `/design/themes`. Unbekannte IDs werden ignoriert.
`datasetSource`	Objekt	Nein	`{ label, url? }`: Herausgeber der Daten für die Ebenenquellenangabe.
`datasetId`	Zeichenfolge	Nein	Bis zu 128 Zeichen. Wird als Ebenen-ID verwendet.
`year`	Ganzzahl	Nein	1800 bis 2100.

Die Antwort enthält immer ein status-Feld:

{ "status": "applied", "message": null, "spec": { "…": "a partial map specification" } }

`status`	Bedeutung
`applied`	`spec` enthält die Ebene.
`unsupported-style`	Der Stil lässt sich aus diesen Daten nicht erstellen. `message` nennt den Grund.
`insufficient-data`	Der Tabelle fehlen nötige Angaben, etwa Positionsspalten. `message` erklärt dies.

Alle drei Antworten haben den Status 200. Prüfen Sie status.

GET /design/styles, /design/samples, /design/themes

Drei schreibgeschützte Kataloge: verfügbare Kartenstile, ausgearbeitete Beispielkarten und Themenpakete.

Authentifizierung: Server-, Sitzungs- oder Legacy-Schlüssel. Berechtigung: design. Kosten: keine. Diese Aufrufe zählen zum Anfragelimit des Schlüssels pro Minute, nicht aber zur Parallelitätsgrenze.

curl -s https://api.kaleidr.com/inference-api/b2b/v1/design/styles \
  -H "Authorization: Bearer $KALEIDR_KEY"

Jede Antwort enthält ihre Liste unter einem einzigen Schlüssel:

{ "styles": [ { "…": "…" } ] }

/design/samples gibt { "samples": [ … ] } und /design/themes gibt { "themes": [ … ] } zurück.

Fehler aller Laufzeitendpunkte

Alle Endpunkte außer den beiden Sitzungsaustausch-Endpunkten können diese Fehler vor der endpunktspezifischen Verarbeitung zurückgeben. Sie werden in dieser Reihenfolge geprüft.

Reihenfolge	Status	Code	Wann
1	401	`Invalid or missing API key`	Kein Schlüssel oder unbekannter, widerrufener bzw. abgelaufener Schlüssel.
2	401	`publishable_requires_session`	Ein veröffentlichbarer Schlüssel wurde gesendet. Tauschen Sie ihn zunächst gegen eine Sitzung aus.
2	403	`server_key_in_browser`	Server-Schlüssel mit einem `Origin`-Header gesendet.
2	403	`session_origin_mismatch`	Sitzungstoken von einem anderen Ursprung verwendet.
2	403	`ip_not_allowed`	Server- oder Legacy-Schlüssel mit IP-Liste von außerhalb dieser Liste aufgerufen.
3	403	`insufficient_scope`	Dem Schlüssel fehlt der Scope des Endpunkts.
3	403	`tier_capability_not_allowed`	Der Schlüssel hat den Scope, Ihr Tarif umfasst ihn nicht mehr.
3	403	`product_not_allowed`	Ein auf bestimmte Produkte beschränkter Server- oder Legacy-Schlüssel ruft einen Endpunkt eines anderen Produkts auf. Siehe Schlüssel beschränken.
4	429	`quota_exceeded`	Nur kostenpflichtige Endpunkte: Pool oder Schlüsselobergrenze decken den Aufruf nicht.
5	429	`visitor_limit_reached`	Nur Sitzungen veröffentlichter Karten: Besucher hat zu viele Fragen gestellt.
6	429	`rate_limited`	Das Anfragelimit des Schlüssels pro Minute ist verbraucht.
7	429	`b2b_overloaded`, `org_overloaded`	Zu viele gleichzeitige Aufrufe.

Ein zu großer Anfragekörper wird mit 413 request_too_large abgelehnt: 2 MiB auf allen Endpunkten, 5 MiB unter /design/*. Wenn die Anfrage ihre Länge angibt, erfolgt diese Ablehnung vor allen oben genannten Prüfungen.

Antwortkörper und Behandlung der Fehler stehen unter Fehler und Kontingente und Ratenlimits.

Zusammenfassung​

POST /sdk/sessions​

POST /sdk/share-sessions​

POST /chat/control/stream​

Anfragelimits​

POST /chat/control/route​

Dieser Endpunkt meldet Fehler mit HTTP 200​

GET /retrieval/geocode/forward​

POST /spot​

Quellenangabe für jeden Wert anzeigen​

Was die API nicht zurückgibt​

POST /spot/overview/stream​

Migration von veralteten Endpunkten​

GET /retrieval/poi/enrich​

POST /chat/summary/stream​

POST /chat/button/stream​

POST /design/analyze​

POST /design/apply-direct​

GET /design/styles, /design/samples, /design/themes​

Fehler aller Laufzeitendpunkte​

Verwandte Themen​