Points de terminaison

Chaque endpoint public de l’API Kaleidr fait l’objet de sa propre section.

• URL de base : https://api.kaleidr.com/inference-api/b2b/v1
• Identifiant : Authorization: Bearer … ou X-Api-Key: …. Sur le serveur, utilisez une clé serveur (kld_sk_live_…). Dans le navigateur, utilisez un jeton de session (kld_sess_live_…). Une clé publiable est acceptée uniquement lors de l'échange de session. Voir Authentification et autorisations.
• Corps des requêtes : JSON, UTF-8. Envoyez Content-Type: application/json pour chaque POST. La taille maximale est de 2 MiB, ou de 5 MiB pour les points de terminaison /design/*. Toute requête plus volumineuse reçoit 413 request_too_large.
• Erreurs : les réponses 4xx ou 5xx contiennent un corps JSON, décrit dans Erreurs. Un point de terminaison signale aussi un échec avec un statut 200 : voir Itinéraires.

Les exemples utilisent une clé serveur stockée dans une variable d’environnement :

export KALEIDR_KEY="kld_sk_live_…"

Récapitulatif

Point de terminaison	Fonction	Autorisation	Facturation
POST /sdk/sessions	Échanger une clé publiable contre une session	Autorisation du produit	Un chargement de carte pour tile ; gratuit sinon
POST /sdk/share-sessions	Échanger l'ID d'une carte publiée contre une session de discussion	aucune	Gratuit
POST /chat/control/stream	Poser une question et diffuser réponse, lieux, actions et itinéraires	ai	Crédits IA selon les jetons consommés
POST /chat/control/route	Calculer un itinéraire entre des coordonnées connues	ai	Gratuit
GET /retrieval/geocode/forward	Transformer un texte saisi en lieux et adresses	ai	Crédits IA, coût fixe
POST /spot	Identifier un lieu, une adresse, des régions et du contenu facultatif en un point	ai	Crédits IA, coût fixe
POST /spot/overview/stream	Diffuser une présentation brève d'un élément renvoyé par /spot	ai	Crédits IA selon les jetons consommés
GET /retrieval/poi/enrich	Obsolète, utiliser /spot. Détails et photos d'un lieu	ai	Crédits IA, coût fixe
POST /chat/summary/stream	Obsolète, utiliser /spot/overview/stream. Diffuser le résumé d'un lieu ou d'un bâtiment	ai	Crédits IA selon les jetons consommés
POST /chat/button/stream	Diffuser la réponse à une question sur un lieu	ai	Crédits IA selon les jetons consommés
POST /design/analyze	Recommander une conception de carte à partir d'un tableau	design	Crédits IA, coût fixe
POST /design/apply-direct	Créer une couche cartographique à partir d'un tableau et d'un style	design	Gratuit
GET /design/styles, /design/samples, /design/themes	Catalogues de conception	design	Gratuit

Le fonctionnement de la facturation, des réservations et des limites est expliqué dans Quotas et limites de débit.

Tous les endpoints d’exécution peuvent renvoyer les erreurs répertoriées dans Erreurs communes à tous les endpoints d’exécution. Les sections ci-dessous ne présentent que les erreurs propres à chacun.

---

POST /sdk/sessions

Échange une clé publiable contre un jeton de session de courte durée, lié à l'origine de l'appel et à un seul produit. Le SDK effectue cet échange pour chaque montage avec clé. N'appelez directement ce point de terminaison que depuis votre propre client de navigateur.

Authentification : clé publiable. Requis : en-tête Origin (ajouté par le navigateur). Coût : un chargement de carte lorsque product vaut tile ; aucun sinon.

Champ	Type	Obligatoire	Remarques
product	chaîne	Oui	chat, editor, viewer ou 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 est le fond de carte par défaut de votre organisation, ou null si aucun n’est défini.

Statut	Code	Circonstance
401	Invalid or missing API key	Clé inconnue, révoquée ou expirée.
403	publishable_key_required	La clé est une clé serveur ou héritée.
403	origin_required	En-tête Origin absent.
403	origin_not_allowed	L'origine ne figure pas dans les origines autorisées de la clé.
403	product_not_allowed	Les produits autorisés pour la clé excluent product.
403	tier_capability_not_allowed	L'offre ne comprend pas le produit ou son autorisation.
403	insufficient_scope	La clé a été créée sans l'autorisation requise par le produit.
422	validation	product est absent ou ne fait pas partie des quatre valeurs possibles.
429	rate_limited	Trop d'échanges pour cette clé. Retry-After: 5.
429	map_load_quota_exceeded	tile uniquement : le quota de chargements de carte est épuisé.
404	sessions_disabled	Les sessions sont désactivées sur la plateforme. Contacter l'assistance.
503	sessions_not_configured	Défaillance de la plateforme. Réessayer puis contacter l'assistance si elle persiste.

La durée de vie, la règle de renouvellement et l’ordre des vérifications figurent dans Authentification et portées : échange de session.

POST /sdk/share-sessions

Échange l'ID d'une carte publiée contre une session de discussion, afin que ses visiteurs puissent discuter sans clé dans la page. La tuile Kaleidr AI de la carte dans Studio doit activer la fonctionnalité demandée.

Authentification : aucune. Requis : en-tête Origin. Coût : aucun ; les appels de chat associés à cette session sont facturés à l’organisation propriétaire de la carte.

Champ	Type	Obligatoire	Remarques
share_id	chaîne	Oui	De 1 à 128 caractères : lettres, chiffres, _ et -.
feature	chaîne	Non	control_tower (par défaut), le panneau Ask Kaleidr de la carte, ou popups, le chat IA dans ses popups. Chacune n'est accordée que tant que son interrupteur est activé.

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" }

Statut	Code	Circonstance
403	origin_required	En-tête Origin absent.
404	not_found	Aucune carte publiée ni aucun lien de partage ne possède cet ID, ou la carte du lien de partage est dépubliée.
403	chat_disabled	La Kaleidr AI de la carte n'active pas la fonctionnalité demandée.
403	origin_not_allowed	La page ne fait pas partie des domaines autorisés.
403	owner_has_no_organization	Le propriétaire n'appartient à aucune organisation à facturer.
403	tier_capability_not_allowed	L'offre du propriétaire ne comprend pas le chat.
422	validation	share_id est absent ou contient des caractères non admis, ou feature ne correspond à aucune des deux valeurs.
429	rate_limited	Trop d'échanges pour cette carte ou depuis cette adresse. Retry-After: 5.
404	sessions_disabled	Les sessions sont désactivées sur la plateforme.
503	share_grant_unavailable, sessions_not_configured	Défaillance de la plateforme. Réessayer.

Voir Kaleidr AI sur une carte publiée.

---

POST /chat/control/stream

Pose une question et diffuse la réponse au fur et à mesure de sa rédaction, ainsi que les lieux mentionnés avec leurs coordonnées, les actions sur la carte et les itinéraires. Ce point de terminaison alimente Kaleidr Chat.

Authentification : clé serveur, jeton de session ou clé ancienne. Portée : ai. Coût : crédits IA correspondant aux tokens utilisés pour la réponse. Réponse : text/event-stream, décrit dans le contrat de flux SSE.

Champ	Type	Obligatoire	Valeur par défaut	Remarques
messages	tableau de { role, content }	Non	[]	Historique de la conversation, de la plus ancienne à la plus récente, terminé par le nouveau message de l'utilisateur. role vaut user ou assistant. Les autres rôles, dont system, et les messages dont content est vide sont ignorés. La réponse porte sur le dernier message user. Limites de taille ci-dessous.
session_id	chaîne	Non	généré	Identifiant de conversation de 1 à 128 caractères : lettres, chiffres, _, ., : et -. Fournissez un ID stable et répétez-le à chaque tour. Si vous l'omettez, le serveur en crée un pour la requête et le renvoie dans les événements phase et start.
location	objet { lat, lng }	Non	aucune	Endroit consulté par l'utilisateur : centre de la carte. Sert à interpréter « près d'ici ».
map_zoom	nombre	Non	aucune	Niveau de zoom de la carte.
lang	chaîne	Non	"en"	Langue de la réponse au format BCP 47, par exemple fr ou pt-BR. Au maximum 35 caractères.
layout	chaîne	Non	aucun	La mise en page du viewer dans laquelle se déroule la conversation : "guide" tant que le viewer intégré affiche sa mise en page guide ; omettez-le sinon. Au maximum 16 caractères.
app_snapshot	objet	Non	aucun	Accepté, mais inutile ; omettez-le.
auto_actions	booléen	Non	aucun	Accepté, mais inutile ; omettez-le.

Les champs inconnus sont acceptés puis ignorés. Aucun champ ne permet de transmettre des instructions système, une personnalité, des outils ou votre propre contexte : la requête porte uniquement sur la conversation, un emplacement et une langue.

Le serveur ne conserve pas la transcription à votre place. Envoyez à chaque fois les tours précédents dans messages, avec le même session_id.

Un session_id est propre à votre organisation. Le contexte de conversation à court terme est isolé par organisation : une autre organisation utilisant le même ID ne peut ni voir ni modifier votre conversation. Dans votre organisation, attribuez un ID distinct à la conversation de chaque utilisateur final.

Limites des requêtes

Une demande dépassant l’une de ces limites est refusée avec 422 avant toute réponse et n’est pas facturée. Le corps est {"detail": "<code>"}.

Limite	Valeur	Code
Nombre de messages dans messages	400	too_many_messages
Longueur du content d'un message	64 000 caractères	message_too_long
Longueur cumulée de tous les content	200 000 caractères	conversation_too_long
session_id	De 1 à 128 caractères : lettres, chiffres, _, ., :, -	invalid_session_id
lang	35 caractères	lang_too_long
layout	16 caractères	invalid_layout

Tous les messages sont comptabilisés, même ceux qui sont ignorés. Une longue conversation atteint généralement la limite de longueur totale avant celle du nombre de messages. Conservez les tours récents nécessaires et supprimez les plus anciens : voir Lecture du flux.

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 désactive la mise en mémoire tampon de curl, afin d’afficher les trames dès leur arrivée. Exemple de réponse abrégée :

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"}

Statut	Code	Circonstance
413	request_too_large	Le corps dépasse 2 MiB.
422	validation	Le corps n'est pas un JSON valide ou un champ possède un type incorrect.
422	too_many_messages, message_too_long, conversation_too_long, invalid_session_id, lang_too_long, invalid_layout	La requête dépasse une limite.
429	quota_exceeded	La réserve de crédits IA ou le plafond mensuel de la clé ne suffit pas.

L'événement quota de l'exemple correspond à ce que reçoit une clé serveur. Avec un jeton de session, le flux transmet une version plus courte : voir l'événement quota.

Après le démarrage du flux, les échecs sont envoyés sous forme d’événement error et non de code de statut. Pour créer un client, consultez Lecture du flux.

POST /chat/control/route

Calcule un itinéraire entre des coordonnées déjà connues. Aucune question n’est posée et aucun texte n’est généré.

Authentification : clé serveur, jeton de session ou clé ancienne. Portée : ai. Coût : aucun. Il faut toutefois disposer d’une marge suffisante dans les crédits IA pour que l’appel soit accepté.

Champ	Type	Obligatoire	Valeur par défaut	Remarques
places	tableau d'objets	Oui, au moins deux	[]	Chaque objet est { lat, lng, name? } avec lat et lng numériques directement à la racine de l'objet. label peut remplacer name. Une entrée dont lat ou lng ne sont pas numériques est ignorée sans erreur.
profile	chaîne	Non	"driving"	driving, walking, cycling ou transit. Toute autre valeur utilise driving.
raw_query	chaîne	Non	"Show directions"	Les mots saisis par l'utilisateur, s'ils existent.

Le premier lieu est le point de départ, le dernier est la destination.

La structure d'un lieu diffère de celle du flux

Un événement place du flux de discussion imbrique la position : { "coordinates": { "lat": …, "lng": … } }. Ce point de terminaison attend lat et lng directement à la racine de l'objet. Transmettre un lieu du flux sans modification produit une réponse error, car aucune entrée ne possède de coordonnées exploitables.

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"
  }'

Une réponse réussie est un 200 contenant action (valeurs données à titre d’exemple) :

{
  "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" }
}

Tracez action.payload.coordinates, une liste de paires [lng, lat]. distance_m est exprimé en mètres et duration_s en secondes. Affichez attribution.text, avec un lien vers attribution.url, partout où vous tracez l'itinéraire.

Avec profile: "transit", payload.transit représente un trajet sans correspondance : marche, un transport, puis marche. Le niveau supérieur ne contient pas attribution ; le crédit de l'exploitant est dans payload.transit.attribution. Présentez-le avec le trajet.

Ce point de terminaison signale les échecs avec HTTP 200

Une route impossible à calculer n’est pas une erreur 4xx. La réponse est 200 avec une chaîne error et sans action :

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

Cela arrive lorsque le planificateur ne peut pas relier les lieux ou échoue pour toute autre raison. Si moins de deux lieux possèdent des coordonnées utilisables, le texte est At least two resolved places are required to build a route.. Comme ce texte peut être affiché tel quel, vérifiez la présence de error plutôt que sa formulation. Un trajet sans ligne de transport directe renvoie la même forme, avec une explication et trois champs supplémentaires : reason, covered et available.

Testez le corps de la réponse, pas le statut :

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);
}

Les erreurs d’authentification, de portée, de validation, de quota et de débit restent des réponses HTTP ordinaires 401, 403, 422 et 429.

GET /retrieval/geocode/forward

Convertit du texte saisi en lieux et adresses correspondants. Conçu pour une zone de recherche ou des champs Départ/Arrivée.

Authentification : clé serveur, jeton de session ou clé ancienne. Portée : ai. Coût : crédits IA, forfait par appel, même lorsque results est vide.

Paramètre	Type	Obligatoire	Valeur par défaut	Remarques
q	chaîne	Oui		De 1 à 200 caractères : nom de lieu, adresse avec numéro de rue ou coordonnées lat,lng saisies.
near_lat	nombre	Non		De −90 à 90. Favorise les correspondances proches ; uniquement avec near_lng.
near_lng	nombre	Non		De −180 à 180. Uniquement avec near_lat.
limit	entier	Non	5	De 1 à 20.
mode	chaîne	Non		Mode de déplacement (driving, walking, cycling, transit). Un trajet court favorise les lieux proches.

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."
      }
    ]
  }
}

Chaque résultat comprend lat, lng, display_name, type et source. Les autres champs sont présents selon les cas :

Champ du résultat	Signification
id	Pour une adresse : identifiant Kaleidr de cette porte, stable entre les mises à jour des données, que vous pouvez conserver et comparer.
confidence	Comment le résultat correspond au texte (tableau suivant). Absent pour des coordonnées lat,lng saisies.
approximate, method, matched_numbers, within_m, score	Seulement pour une adresse estimée (ci-dessous).
attribution	Conditions du jeu de données d'origine : dataset, license et, selon le cas, license_url, attribution (crédit à afficher) et use_restriction.

confidence	Le résultat correspond à
exact	Le numéro demandé, dans la rue et la localité demandées.
fuzzy	Même adresse avec une faute dans le nom de la rue.
name_exact	Un lieu dont le nom correspond exactement au texte.
locality	Ville, région ou quartier nommé dans la requête.
interpolated, nearest	Une estimation d'un numéro absent des données.
partial	Une rue dont le nom complet commence par le texte saisi.
name_partial	Un lieu dont le nom partage certains mots saisis.
ambiguous	Une adresse sans localité indiquée ni repère proche : l'une de plusieurs possibilités.

Adresses estimées. Lorsque le numéro saisi n'existe pas dans les données, la réponse le place dans la rue : entre les numéros connus les plus proches du même côté, au numéro connu le plus proche ou le long de l'îlot auquel appartient la plage de numérotation. Le résultat contient approximate: true ainsi que :

Champ	Signification
method	"interpolated" (entre deux numéros connus), "nearest" (au numéro connu proche) ou "range" (le long de l'îlot).
matched_numbers	Numéros ayant servi à placer l'adresse.
within_m	Distance entre ces numéros, ou longueur de l'îlot, en mètres : erreur maximale si les numéros progressent dans l'ordre. Absent pour "nearest".
score	Confiance de 0 à 1. Une valeur faible indique une localisation au niveau de la rue, pas de la porte exacte.

Une correspondance exacte ne comporte jamais ces champs.

Attribution. Transmettez le champ attribution de premier niveau avec les résultats. Son text correspond au crédit à afficher, et licenses contient les conditions qui doivent accompagner les données. Lorsque des adresses sont présentes, attribution.sources énumère les jeux de données utilisés. Pour ces résultats, respectez la use_restriction propre à chacun :

Jeu de données	Crédit à afficher	Restriction d'utilisation
au/countrywide (G-NAF)	G-NAF © Geoscape Australia, concédé sous licence par le Commonwealth d'Australie selon l'Open Geo-coded National Address File (G-NAF) End User Licence Agreement.	Ne pas générer une adresse ou une liste d'adresses destinées à l'envoi postal sans vérifier, pour chaque adresse, sa capacité à recevoir du courrier auprès d'une source autre que G-NAF ; l'usage doit être conforme aux Australian Privacy Principles.
ca/countrywide (Statistics Canada)	Adapté de Statistics Canada, National Address Register, 2025-07-29. Cela ne constitue pas une approbation du produit par Statistique Canada.	Ne pas identifier une personne, une entreprise ou une organisation, ni laisser penser qu'elle approuve le produit.
us/ny/city_of_new_york	Données d'adresses du NYC Department of City Planning.	Aucune.
us/ma/statewide (MassGIS)	MassGIS (Bureau of Geographic Information), Commonwealth of Massachusetts EOTSS	Aucune (domaine public).

Aucun résultat et échec interne ont la même apparence. Une requête sans correspondance renvoie 200 avec "results": []. Une recherche qui échoue en interne peut produire la même réponse ; dans ce cas, elle n'est pas facturée. Interprétez un tableau vide comme « rien à afficher », pas comme une erreur.

Statut	Code	Circonstance
422	validation	q est absent, vide ou dépasse 200 caractères ; limit ou une coordonnée est hors limites.
429	quota_exceeded	Les crédits IA disponibles ne couvrent pas l'appel.

POST /spot

Indique ce qui se trouve à un point donné : le lieu sélectionné, l'adresse la plus proche et les régions qui contiennent le point. Chaque valeur précise le crédit à afficher. Sur demande, le résultat inclut aussi une description et des photos du lieu.

Authentification : clé serveur, jeton de session ou clé ancienne. Portée : ai. Coût : crédits IA, forfait par appel selon l’élément le plus coûteux demandé dans want, même si aucun résultat n’est trouvé. content ou photos coûtent le tarif de /retrieval/poi/enrich lorsque le contenu est récupéré pour cet appel ; sinon, address coûte le tarif de /retrieval/geocode/forward. Le contenu déjà récupéré pour une requête précédente ne coûte rien ; un tel appel qui demande aussi address est donc facturé au tarif du géocodage. Un appel ne demandant que entities, regions, boundaries ou tenants est gratuit. Par défaut, want inclut address ; l’omission de want entraîne donc la facturation du géocodage.

Champ	Type	Obligatoire	Valeur par défaut	Remarques
lat	nombre	Oui		De −90 à 90. Le point.
lng	nombre	Oui		De −180 à 180.
zoom	nombre	Non		De 0 à 24. Niveau de zoom de la carte.
hint	objet	Non		Élément sélectionné par l'utilisateur (ci-dessous).
want	tableau de chaînes	Non	["entities", "address", "regions"]	Parties à renvoyer (ci-dessous).
lang	chaîne	Non	"en"	Langue de content, au maximum 16 caractères.

Le point détermine la réponse ; l'indication ne fait que sélectionner. Une indication sert à choisir parmi ce qui se trouve à ce point ; elle ne déplace jamais le résultat. Un lieu à plus de 75 mètres de lat, lng n'est pas renvoyé, quelle que soit l'indication.

Champ hint	Remarques
id	Identifiant Kaleidr du lieu : la partie d'une référence poi: située après les deux-points.
name	Nom du lieu tel qu'il apparaît sur l'étiquette de la carte. 200 caractères maximum. Il doit correspondre exactement à l'un des lieux situés au point indiqué et sert à désigner le lieu pour content. Si region_level vaut county, state ou country, il sélectionne également la région de ce niveau dont le nom correspond, sans tenir compte de la casse ni des accents, parmi les régions présentes au point (pour un État ou un pays, également celles situées à 5 km au maximum de ce point). Si aucun nom ne correspond, rien ne change.
category	Catégorie du lieu. 100 caractères maximum. Utilisée pour content.
region_level	Avec boundaries, renvoie uniquement le contour de la région à ce niveau (city, county, state ou country) ; sans cette option, les contours de toutes les régions. Avec name, la région de ce niveau dans regions comme dans boundaries est celle sélectionnée par le nom.
layer, wiki_title, ta_location_id, yelp_business_id, data_source	Champs acceptés. Utilisés par les propres applications de Kaleidr ; omettez-les.

Valeur de want	Ajoute
entities	Le lieu sur lequel l'utilisateur a cliqué, si hint désigne un lieu situé à ce point.
address	L'adresse de voirie la plus proche.
regions	La ville et le comté (aux États-Unis uniquement), l'État et le pays contenant le point. Pour un point situé en mer, à 5 km au maximum de la côte, l'État et le pays les plus proches sont renvoyés.
boundaries	regions, chacune avec son contour (un seul niveau lorsque hint.region_level est spécifié).
content	Le contenu descriptif du lieu : un résumé, des photos et un lien. Nécessite un nom de lieu, issu du lieu sélectionné ou de hint.name.
photos	Uniquement les photos du lieu. Le coût est identique à celui de content.
tenants	Les lieux nommés proches du point, du plus proche au plus éloigné : les établissements d'un bâtiment. Votre application conserve ceux qui se trouvent à l'intérieur de l'emprise au sol du bâtiment affichée.

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"]
  }'

Réponse abrégée avec des valeurs illustratives :

{
  "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"]
}

Champ	Signification
spot	Point transmis : { lat, lng, zoom }.
entities	Lieu sélectionné, puis occupants du bâtiment si demandés, ou tableau vide. Chaque élément possède ref, kind ("poi" pour le lieu sélectionné, "tenant" pour un occupant), role ("clicked" ou "inside"), name, at (position du lieu { lat, lng }) et facts (category, ainsi que website du lieu sélectionné si connu). La ref d'un occupant est une référence poi:, permettant aussi de diffuser sa présentation. Ignorez les types kind inconnus.
address	Adresse la plus proche ou null : { ref, line, at }.
regions	Régions contenant le point, de la plus petite à la plus grande. Chacune comporte ref, kind ("region"), level (city, county, state ou country), name et label, point de placement du nom { lat, lng } ou null. Avec want: ["boundaries"], elles comprennent aussi geometry, leur contour en géométrie GeoJSON.
content	Présent si want contient content ou photos, si le nom du lieu est connu et si le contenu peut être restitué. C'est l'objet fourni par /retrieval/poi/enrich (champs) ou, pour photos seulement, { photos, source, cached }, avec license et attr ajoutés. Peut être null lorsqu'aucun contenu n'est accessible.
attributions	Crédits de la réponse : { text, license }, indexés par le attr des valeurs.
withheld	Informations non restituées en raison des restrictions de l'API, classées par type ; tableau vide si rien n'a été omis.

Une ref identifie un objet pour /spot/overview/stream : poi:<id> pour un lieu, address:<id> pour une adresse, region:<source>:<id> pour une région (<source> vaut tiger, nuts ou ne). Les applications Kaleidr utilisent aussi building:<id>, que l'API ne renvoie pas. Traitez les références comme des chaînes opaques.

Afficher l’attribution de chaque valeur

Chaque valeur issue d'un jeu de données est un objet { value, license, attr } : donnée, licence et clé dans attributions. Chaque fois que vous affichez une valeur, affichez aussi attributions[attr].text, à proximité ou dans une rubrique de crédits accessible. Une même réponse peut combiner plusieurs sources : une attribution unique pour toute la réponse ne suffit pas. Conservez license et le crédit avec la valeur lorsque vous la stockez ou la transmettez.

content est attribué de la même manière, via son propre attr. Une valeur portant live_only: true ne peut être montrée qu'à l'utilisateur actuel ; elle ne peut jamais être stockée ni transmise.

Consultez Licences des données pour connaître les obligations de chaque licence.

Données non renvoyées par l’API

Les applications Kaleidr affichent davantage d’informations sur un point que l’API, certaines données n’étant pas autorisées sur d’autres sites :

• Valeurs soumises à l'ODbL, dérivées d'OpenStreetMap : caractéristiques des bâtiments (étages, hauteur, catégorie). Les présentations de bâtiments ne sont pas disponibles non plus.
• Résultats de prestataires tiers : recherches d'adresses dans les services de géocodage, et notes, avis et photos de Yelp et Tripadvisor.

withheld permet de distinguer « aucune donnée connue ici » de « non disponible via l'API ». Il ne nomme que des catégories, jamais des valeurs : building_facts si le point est dans un bâtiment, ou content si le seul contenu connu pour le lieu ne peut pas être renvoyé. D'autres entrées désignent de la même manière les autres parties exclues.

Erreurs de POST /spot :

Statut	Code	Circonstance
413	request_too_large	Le corps dépasse 2 MiB.
422	validation	lat ou lng est absent ou hors limites, zoom est hors de 0 à 24, want contient une valeur inconnue ou un champ est trop long ou mal formé.
429	quota_exceeded	Les crédits IA disponibles ne couvrent pas l'appel.

Un élément introuvable est renvoyé vide (null ou []). L’appel reste facturé.

POST /spot/overview/stream

Diffuse une courte présentation écrite d’un élément renvoyé par /spot, identifié par son ref.

Authentification : clé serveur, jeton de session ou clé ancienne. Portée : ai. Coût : crédits IA selon les tokens utilisés. Chaque présentation est rédigée pour sa demande. Réponse : text/event-stream : en général une trame place portant le nom complet du lieu, par exemple "Springfield, Ohio, United States of America", puis les trames d’un résumé de lieu ; voir Flux de résumés et de boutons.

Champ	Type	Obligatoire	Valeur par défaut	Remarques
ref	chaîne	Oui		Une ref issue de /spot, au plus 128 caractères, ou place: (ci-dessous).
lat, lng	nombre	Oui		Point précédemment transmis à /spot.
lang	chaîne	Non	"en"	Langue de la présentation, au plus 16 caractères.
hint	objet	Pour place: uniquement		{ name, category? } : nom à décrire.

ref	Présentation
poi:<id>	Le lieu.
region:<source>:<id>	La région.
place:	Un nom sans fiche correspondante chez Kaleidr, par exemple un lieu pour lequel /spot n'a renvoyé aucune entité. Envoyez son nom dans hint.name.
address:<id>, building:<id>	Non disponible via l'API : le flux envoie une trame error. Voir Ce que l'API ne renvoie pas.

L'objet est de nouveau recherché aux coordonnées lat, lng ; aucun élément de la requête n'est considéré comme un fait établi à son sujet. Une référence poi: à plus de 75 mètres du point, une référence region: ne contenant pas le point ou place: sans hint.name reçoit aussi une trame error.

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"}'

Une référence impossible à décrire renvoie cette trame au lieu d’un résumé. Elle contient ref, mais pas partial_text :

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

Statut	Code	Circonstance
413	request_too_large	Le corps dépasse 2 MiB.
422	validation	ref ne correspond pas aux formats précédents, lat ou lng est absent ou hors limites, ou lang dépasse 16 caractères.
429	quota_exceeded	Les crédits IA disponibles ne couvrent pas l'appel.

Migration depuis les points de terminaison obsolètes

GET /retrieval/poi/enrich et POST /chat/summary/stream sont obsolètes. Ils continuent de répondre de la même manière jusqu'au 2027-01-15 et pourront être supprimés à tout moment après cette date. Leurs en-têtes de réponse signalent cette situation ; Deprecation indique la date de dépréciation, 2026-10-16, sous forme d'horodatage Unix :

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

L’en-tête Link de /chat/summary/stream désigne /inference-api/b2b/v1/spot/overview/stream. Journalisez l’en-tête Sunset afin d’identifier les appels encore utilisés.

De GET /retrieval/poi/enrich vers POST /spot :

Avant	Après
lat, lon (requête)	lat, lng (corps). Attention au nom du champ.
name, category	hint.name, hint.category
lang	lang, au plus 16 caractères
Recherche complète	want: ["content"]
photos_only=true	want: ["photos"]
radius, dataSource, ta_location_id, regionLevel	À omettre.
Corps de la réponse	content : le même objet, plus live_only
attribution	content.attribution

Le coût est le même ou inférieur : /spot ne facture pas le contenu déjà récupéré pour une requête précédente. Une recherche est facturée selon l’élément le plus coûteux de want ; lorsque le contenu est récupéré pour l’appel, ajouter entities, address ou regions permet donc de les obtenir sans frais supplémentaires lors du même appel.

De POST /chat/summary/stream vers POST /spot/overview/stream :

Avant	Après
Un lieu : location, building_properties.name, .category	Appeler /spot avec le point et hint: { name, category }, puis diffuser la présentation de la ref du lieu figurant dans entities, avec les mêmes lat et lng. Si entities est vide, envoyer ref: "place:" avec le même hint.
building_properties.pid	ref: "poi:<id>"
lang	lang, au plus 16 caractères
max_tokens	À omettre.
Un bâtiment : type: "building" et ses champs	Aucun successeur. La présentation d'un bâtiment est indisponible via l'API.
Les trames	Celles d'une présentation de lieu, précédées d'une nouvelle trame place qui nomme le lieu.

GET /retrieval/poi/enrich

Obsolète

Ce point de terminaison est obsolète et peut être supprimé après le 2027-01-15. Utilisez POST /spot avec want: ["content"]. Voir Migration des anciens points de terminaison.

Renvoie du contenu descriptif sur un lieu : titre, résumé, photos et lien.

Authentification : clé serveur, jeton de session ou clé ancienne. Portée : ai. Coût : crédits IA, forfait par appel. Le coût est facturé même si aucun contenu n’est trouvé.

Paramètre	Type	Obligatoire	Valeur par défaut	Remarques
lat	nombre	Oui		Latitude du lieu.
lon	nombre	Oui		Longitude du lieu. Attention au nom lon, et non lng.
name	chaîne	Non		Nom du lieu. Recommandé : un point seul ne donne souvent aucun résultat.
category	chaîne	Non		Catégorie du lieu issue d'un événement place.
radius	entier	Non	250	Rayon de recherche en mètres autour du point.
lang	chaîne	Non	"en"	Langue du contenu.
photos_only	booléen	Non	false	Renvoyer uniquement les photos (réponse plus courte, ci-dessous).
dataSource, ta_location_id, regionLevel	chaîne	Non		Acceptés, mais destinés aux applications Kaleidr ; omettez-les.

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"]
}

Champ	Type	Signification
source	chaîne	Origine du contenu. "omitted" signifie que du contenu existe mais ne peut pas être transmis via l'API (ci-dessous).
found	booléen	false si rien n'est trouvé. Les autres champs sont alors vides.
title	chaîne	Titre du lieu dans la source.
summary	chaîne ou null	Brève description.
photos	tableau d'URL	Peut être vide.
url	chaîne ou null	Lien vers la page source.
attribution	tableau de chaînes	Sources à créditer, par exemple ["Wikipedia"]. À afficher avec le contenu.
rating, phone, hours, reviews		Peuvent être null ou vides. L'API ne renvoie jamais les notes et avis de fournisseurs sous licence.
unverified	booléen	Facultatif ; true si la correspondance avec le lieu est incertaine.

Avec photos_only=true, la réponse est { "photos": […], "source": "…", "cached": false }.

Contenu non restitué. Certains contenus sont sous licence exclusive pour les applications Kaleidr. Si c'est le seul contenu disponible pour un lieu, la réponse est 200 avec "source": "omitted", "found": false et aucun contenu. L'appel est néanmoins facturé. Voir Licences des données.

Statut	Code	Circonstance
422	validation	lat ou lon est absent ou n'est pas un nombre.
429	quota_exceeded	Les crédits IA disponibles ne couvrent pas l'appel.
500	An internal error occurred. Please try again.	La recherche a échoué. L'appel reste facturé.

---

POST /chat/summary/stream

Obsolète

Ce point de terminaison est obsolète et peut être supprimé après le 2027-01-15. Utilisez POST /spot/overview/stream. Aucun point de terminaison ne remplace les résumés de bâtiments. Voir Migration des anciens points de terminaison.

Diffuse un bref résumé écrit d’un lieu ou d’un bâtiment. Ce contenu alimente la fiche de lieu de Kaleidr Chat.

Authentification : clé serveur, jeton de session ou clé ancienne. Portée : ai. Coût : crédits IA selon les tokens utilisés. Chaque résumé est rédigé pour sa demande. Réponse : text/event-stream. Voir Flux de résumés et de boutons.

Le champ type du corps sélectionne le type de résumé.

Un bâtiment ("type": "building") :

Champ	Type	Obligatoire	Remarques
type	chaîne	Oui	"building".
address	chaîne	Oui	Adresse complète du bâtiment, au plus 500 caractères.
lat, lng	nombre	Non	Coordonnées du bâtiment.
building_levels	entier	Non	Nombre d'étages, si connu.
building_height_m	nombre	Non	Hauteur du bâtiment en mètres, si connue.
tenant_names	tableau de chaînes	Non	Entreprises dans le bâtiment : au plus 100 noms de 200 caractères chacun.
poi_count	entier	Non	Nombre de lieux dans le bâtiment.
lang	chaîne	Non	Valeur par défaut "en", jusqu'à 35 caractères.

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"}

Un lieu (type absent ou "poi"). Le corps accepte location (objet { lat, lng }), building_properties (objet), lang et max_tokens (entier). Cette forme est conçue pour le panneau interne de Kaleidr et la signification précise des champs n'est pas encore un contrat publié. Préférez /chat/control/stream pour interroger un lieu depuis votre propre code.

Champ du lieu	Limite
building_properties.name, .type, .category, .poi_type	200 caractères chacun
building_properties.pid	128 caractères
Chaque champ textuel de building_properties.event	4 000 caractères
lang	35 caractères
max_tokens	Une valeur supérieure au plafond par défaut est ramenée à ce plafond. Vous ne pouvez pas demander un résumé plus long.

Les deux variantes ne lisent que les champs répertoriés ici. Tout autre champ du corps est ignoré. Un champ dépassant sa limite de longueur est refusé avec 422 field_too_long, avant toute production de résumé.

Statut	Code	Circonstance
413	request_too_large	Le corps dépasse 2 MiB.
422	field_too_long	Un champ dépasse sa limite ou tenant_names contient plus de 100 entrées. Le corps est {"detail": "field_too_long"}.
500	Summary stream error	Impossible de lire le corps, ou une requête sur un bâtiment ne contient pas address. Pour tout autre corps incorrect, ce point de terminaison renvoie 500 au lieu de 422.
429	quota_exceeded	Les crédits IA disponibles ne couvrent pas l'appel.

POST /chat/button/stream

Diffuse la réponse à une seule question sur un lieu, par exemple « Quels sont les horaires d'ouverture ? ». Il alimente les boutons de questions de la fiche de lieu de Kaleidr Chat. Il ne conserve pas de conversation : chaque appel est indépendant.

Authentification : clé serveur, jeton de session ou clé ancienne. Portée : ai. Coût : crédits IA correspondant aux tokens utilisés. Réponse : text/event-stream. Voir Flux de résumés et de boutons.

Champ	Type	Obligatoire	Valeur par défaut	Remarques
query	chaîne	Oui		Question, au plus 4 000 caractères.
place_name	chaîne	Non		Nom du lieu concerné, au plus 200 caractères.
place_type	chaîne	Non		Sa catégorie, au plus 200 caractères.
address	chaîne	Non		Adresse du lieu, au plus 500 caractères.
location	objet { lat, lng }	Non		Sa position.
lang	chaîne	Non	"en"	Langue de réponse, au plus 35 caractères.
description	chaîne	Non		Description du lieu dont vous disposez déjà, au plus 4 000 caractères.
website	chaîne	Non		Site Web du lieu, si connu, au plus 2 048 caractères.
stores_preview	tableau d'objets { name }	Non		Entreprises présentes au lieu et déjà connues. Au plus 50 entrées, avec 200 caractères maximum pour chaque name. Les autres membres sont ignorés.
button_id, session_id, place_id	chaîne	Non		Identifiants de corrélation personnalisés, au plus 128 caractères chacun.

Les champs absents de ce tableau sont ignorés. Si un champ dépasse sa limite de longueur, la demande est refusée avec 422 field_too_long avant toute réponse.

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}

Statut	Code	Circonstance
413	request_too_large	Le corps dépasse 2 MiB.
422	field_too_long	Un champ est trop long ou stores_preview comporte plus de 50 entrées. Le corps est {"detail": "field_too_long"}.
500	Button chat stream error	Le corps n'est pas lisible ou query est absent. Pour tout autre corps incorrect, ce point de terminaison renvoie 500 plutôt que 422.
429	quota_exceeded	Les crédits IA disponibles ne couvrent pas l'appel.

---

POST /design/analyze

Examine les colonnes et un échantillon du tableau, puis recommande une représentation cartographique.

L’éditeur intégré n’appelle pas les endpoints de conception : ils constituent une interface REST pour vos propres outils.

Authentification : clé serveur, jeton de session ou clé ancienne. Portée : design. Coût : crédits IA, forfait par appel réussi. Un appel ayant échoué n’est pas facturé.

Champ	Type	Obligatoire	Remarques
columns	tableau de chaînes	Oui	De 1 à 256 noms de colonnes, tous distincts.
sampleRows	tableau d'objets	Non	Jusqu'à 1 000 lignes, chaque objet portant les noms de colonnes comme clés.
datasetName	chaîne	Non	Au plus 512 caractères.
rowCount	entier	Non	Nombre total de lignes du tableau, au moins 0.
userGoal	chaîne	Non	Au plus 1 000 caractères : ce que la carte doit montrer.
supportedStyles	tableau de chaînes	Non	Identifiants de style parmi lesquels choisir, formés de mots minuscules reliés par des tirets.

Les noms de champs utilisent camelCase. Les champs inconnus sont ignorés.

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": "…"
}

Consultez designPlan ; sa valeur peut être null. recommendation, suggestedConfig et explanation sont d'anciens champs conservés pour compatibilité, destinés à être supprimés : ne vous appuyez pas dessus. issues énumère les problèmes détectés dans les données.

Statut	Code	Circonstance
413	request_too_large	Le corps dépasse 5 MiB. Même limite pour /design/apply-direct.
422	validation	columns est absent, vide, trop long ou contient des doublons ; ou une limite précédente est dépassée.
429	quota_exceeded	Les crédits IA disponibles ne couvrent pas l'appel.
500	map_design_analyze_failed	L'analyse a échoué. Aucun frais.

POST /design/apply-direct

Construit une couche cartographique à partir d’un tableau et d’un style choisi, sans analyse.

Authentification : clé serveur, jeton de session ou clé ancienne. Portée : design. Coût : aucun.

Champ	Type	Obligatoire	Remarques
style	chaîne	Oui	ID de style de 1 à 64 caractères. Les ID sont répertoriés dans /design/styles.
config	objet	Oui	Objet avec location, metric et visual. location.mode ("coordinates" ou "region") et visual.layerName sont obligatoires ; les autres sous-champs ne sont pas encore documentés.
table	objet	Oui	{ fileName?, columns[], rows[] }. Chaque ligne associe des noms de colonnes à des valeurs. Chaque valeur doit être une chaîne JSON : envoyez "120000", pas 120000. Une ligne contenant un nombre ou null est refusée avec 422.
layerLabel	chaîne	Oui	Nom affiché de la couche, de 1 à 512 caractères.
themePackId	chaîne	Non	ID de thème fourni par /design/themes. Les ID inconnus sont ignorés.
datasetSource	objet	Non	{ label, url? } : organisme ayant publié les données, pour le crédit de la couche.
datasetId	chaîne	Non	Jusqu'à 128 caractères, utilisé comme ID de couche.
year	entier	Non	De 1800 à 2100.

La réponse contient toujours un champ status :

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

status	Signification
applied	spec contient la couche.
unsupported-style	Ce style ne peut pas être créé à partir de ces données. message explique pourquoi.
insufficient-data	Le tableau ne possède pas les données requises, par exemple les colonnes de position. message précise lesquelles.

Les trois réponses portent le statut 200. Vérifiez status.

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

Trois catalogues en lecture seule : styles de carte disponibles, exemples de cartes et ensembles de thèmes.

Authentification : clé serveur, jeton de session ou clé ancienne. Portée : design. Coût : aucun. Ces appels comptent dans le nombre de requêtes par minute de la clé, mais pas dans la limite de concurrence.

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

Chaque réponse enveloppe sa liste dans une clé unique :

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

/design/samples renvoie { "samples": [ … ] } et /design/themes renvoie { "themes": [ … ] }.

---

Erreurs communes à tous les points de terminaison d’exécution

Tous les endpoints, sauf les deux échanges de session, peuvent renvoyer ces erreurs avant leur traitement propre. Elles sont vérifiées dans l’ordre suivant.

Ordre	Statut	Code	Circonstance
1	401	Invalid or missing API key	Aucune clé, ou clé inconnue, révoquée ou expirée.
2	401	publishable_requires_session	Une clé publiable a été envoyée directement. Échangez-la d'abord contre une session.
2	403	server_key_in_browser	Clé serveur envoyée avec un en-tête Origin.
2	403	session_origin_mismatch	Jeton de session utilisé depuis une autre origine.
2	403	ip_not_allowed	Clé serveur ou héritée avec une liste d'IP autorisées, appelée depuis une adresse absente de cette liste.
3	403	insufficient_scope	La clé ne dispose pas de l'autorisation requise par le point de terminaison.
3	403	tier_capability_not_allowed	La clé a l'autorisation, mais l'offre actuelle ne l'inclut plus.
3	403	product_not_allowed	Une clé serveur ou héritée limitée à certains produits appelle un point de terminaison d'un autre produit. Voir Restreindre une clé.
4	429	quota_exceeded	Points de terminaison facturés uniquement : le solde de crédits ou le plafond de la clé ne suffit pas.
5	429	visitor_limit_reached	Sessions de cartes publiées uniquement : le visiteur a effectué trop de demandes.
6	429	rate_limited	Limite de requêtes par minute de la clé atteinte.
7	429	b2b_overloaded, org_overloaded	Trop d'appels simultanés.

Un corps de requête trop volumineux est refusé avec 413 request_too_large : 2 MiB sur tous les points de terminaison, 5 MiB sur /design/*. Lorsque la longueur du corps est déclarée, ce refus intervient avant les contrôles énumérés ci-dessus.

Les corps des réponses et leur traitement sont détaillés dans Erreurs et Quotas et limites de débit.

Voir aussi

• Démarrage rapide côté serveur : premier appel pas à pas.
• Contrat de transmission SSE : tous les événements du flux.
• Lecture du flux : exemples complets de clients.
• Licences des données : crédits à afficher.