Puntos de conexión

Cada endpoint público de la API de la plataforma Kaleidr tiene su propia sección.

• URL base: https://api.kaleidr.com/inference-api/b2b/v1
• Credencial: Authorization: Bearer … o X-Api-Key: …. Desde el backend, una clave de servidor (kld_sk_live_…). Desde el navegador, un token de sesión (kld_sess_live_…). Una clave publicable solo se acepta al intercambiarla por una sesión. Consulta Autenticación y ámbitos.
• Cuerpos: JSON, UTF-8. Envía Content-Type: application/json en cada POST. El cuerpo puede tener hasta 2 MiB, o 5 MiB en los endpoints /design/*. Se rechazan los mayores con 413 request_too_large.
• Errores: respuesta 4xx o 5xx con cuerpo JSON, descrita en Errores. Un endpoint comunica fallos mediante 200: consulta Indicaciones.

Los ejemplos utilizan una clave de servidor almacenada en una variable de entorno:

export KALEIDR_KEY="kld_sk_live_…"

Resumen

Endpoint	Finalidad	Ámbito	Cobro
POST /sdk/sessions	Intercambiar una clave publicable por una sesión	Ámbito del producto	Una carga de mapa para tile; nada en otros casos
POST /sdk/share-sessions	Intercambiar el ID de un mapa publicado por una sesión de chat	ninguno	Ninguno
POST /chat/control/stream	Hacer una pregunta y transmitir respuesta, lugares, acciones y rutas	ai	Créditos de IA por tokens utilizados
POST /chat/control/route	Indicaciones entre coordenadas conocidas	ai	Ninguno
GET /retrieval/geocode/forward	Convertir texto escrito en lugares y direcciones	ai	Créditos de IA, tarifa fija
POST /spot	Qué hay en un punto: lugar, dirección, regiones y contenido opcional	ai	Créditos de IA, tarifa fija
POST /spot/overview/stream	Transmitir una descripción breve de un elemento de /spot	ai	Créditos de IA por tokens utilizados
GET /retrieval/poi/enrich	Obsoleto, utiliza /spot. Detalles y fotos de un lugar	ai	Créditos de IA, tarifa fija
POST /chat/summary/stream	Obsoleto, utiliza /spot/overview/stream. Transmitir descripción de lugar o edificio	ai	Créditos de IA por tokens utilizados
POST /chat/button/stream	Transmitir la respuesta a una pregunta sobre un lugar	ai	Créditos de IA por tokens utilizados
POST /design/analyze	Recomendar diseño de mapa para una tabla de datos	design	Créditos de IA, tarifa fija
POST /design/apply-direct	Crear una capa de mapa a partir de una tabla y un estilo	design	Ninguno
GET /design/styles, /design/samples, /design/themes	Catálogos de diseño	design	Ninguno

La explicación de los cargos, las reservas y los límites está en Cuotas y límites de frecuencia.

Todos los endpoints de ejecución pueden devolver los errores de Errores comunes a todos los endpoints de ejecución. Las secciones siguientes enumeran únicamente los específicos de cada endpoint.

---

POST /sdk/sessions

Intercambia una clave publicable por un token de sesión temporal vinculado al origen que llama y a un producto. El SDK lo hace en todos los montajes con clave. Llámalo directamente solo desde tu propio cliente de navegador.

Autenticación: clave publicable. Requiere: encabezado Origin (el navegador lo añade). Cargo: una carga de mapa cuando product es tile; en los demás casos, ninguno.

Campo	Tipo	Obligatorio	Notas
product	cadena	Sí	chat, editor, viewer o 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 corresponde al mapa base predeterminado de tu organización, o a null si no hay ninguno configurado.

Estado	Código	Cuándo
401	Invalid or missing API key	Clave desconocida, revocada o caducada.
403	publishable_key_required	La clave es de servidor o heredada.
403	origin_required	Falta la cabecera Origin.
403	origin_not_allowed	El origen no figura entre los permitidos de la clave.
403	product_not_allowed	Los productos permitidos de la clave excluyen product.
403	tier_capability_not_allowed	El plan no incluye el producto ni su ámbito.
403	insufficient_scope	La clave se creó sin el ámbito del producto.
422	validación	Falta product o no coincide con uno de los cuatro valores.
429	rate_limited	Demasiados intercambios para esta clave. Retry-After: 5.
429	map_load_quota_exceeded	Solo tile: se agotó la asignación de cargas de mapas.
404	sessions_disabled	Las sesiones están desactivadas en la plataforma. Contacta con soporte.
503	sessions_not_configured	Fallo de la plataforma. Reintenta y contacta con soporte si persiste.

La duración, las reglas de renovación y el orden de estas comprobaciones se explican en Autenticación y ámbitos: intercambio de sesión.

POST /sdk/share-sessions

Intercambia el ID de un mapa publicado por una sesión de chat, para que los visitantes chateen sin incluir una clave en la página. El mosaico Kaleidr AI del mapa en Studio debe activar la función solicitada.

Autenticación: ninguna. Requiere: encabezado Origin. Cargo: ninguno; las llamadas de chat con esta sesión se cobran a la organización propietaria del mapa.

Campo	Tipo	Obligatorio	Notas
share_id	cadena	Sí	De 1 a 128 caracteres: letras, dígitos, _ y -.
feature	cadena	No	control_tower (valor predeterminado), el panel Ask Kaleidr del mapa, o popups, el chat con IA en sus ventanas emergentes. Cada uno se concede solo mientras su interruptor está activado.

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

Estado	Código	Cuándo
403	origin_required	Falta la cabecera Origin.
404	not_found	Ningún mapa publicado ni enlace compartido tiene este ID, o el mapa del enlace compartido no está publicado.
403	chat_disabled	La Kaleidr AI del mapa no activa la función solicitada.
403	origin_not_allowed	La página no está entre los dominios permitidos.
403	owner_has_no_organization	El propietario del mapa no pertenece a ninguna organización.
403	tier_capability_not_allowed	El plan del propietario no incluye chat.
422	validación	Falta share_id o contiene caracteres distintos, o feature no es ninguno de los dos valores.
429	rate_limited	Demasiados intercambios para este mapa o desde esta dirección. Retry-After: 5.
404	sessions_disabled	Las sesiones están desactivadas en la plataforma.
503	share_grant_unavailable, sessions_not_configured	Fallo de la plataforma. Reintenta.

Consulta Kaleidr AI en un mapa publicado.

---

POST /chat/control/stream

Recibe una pregunta y transmite la respuesta: texto mientras se redacta, lugares mencionados con coordenadas, acciones de mapa y rutas. Es el endpoint que utiliza Kaleidr Chat.

Autenticación: clave de servidor, token de sesión o clave heredada. Ámbito: ai. Cargo: créditos de IA según los tokens que utilizó la respuesta. Respuesta: text/event-stream, descrita en el contrato de transmisión SSE.

Campo	Tipo	Obligatorio	Predeterminado	Notas
messages	matriz de { role, content }	No	[]	Conversación hasta ahora, en orden cronológico, terminando en el nuevo mensaje del usuario. role es user o assistant. Se ignoran otros roles, incluido system, y mensajes con content vacío. Se responde al último mensaje user. Límites de tamaño a continuación.
session_id	cadena	No	generado	ID de conversación de 1 a 128 caracteres: letras, dígitos, _, ., : y -. Proporciona un ID estable y repítelo en cada turno. Si lo omites, el servidor genera uno para la solicitud y lo devuelve en los eventos phase y start.
location	objeto { lat, lng }	No	ninguno	Lugar que está mirando el usuario: centro del mapa. Se usa para interpretar «cerca de aquí».
map_zoom	número	No	ninguno	Nivel de zoom del mapa.
lang	cadena	No	"en"	Idioma de respuesta como etiqueta BCP 47, por ejemplo fr o pt-BR. Máximo 35 caracteres.
layout	cadena	No	ninguno	El diseño del viewer en el que transcurre la conversación: "guide" mientras el viewer incrustado muestra su diseño de guía; en otro caso, omítelo. Máximo 16 caracteres.
app_snapshot	objeto	No	ninguno	Aceptado, pero no necesario. Omítelo.
auto_actions	booleano	No	ninguno	Aceptado, pero no necesario. Omítelo.

Se aceptan e ignoran los campos desconocidos. No existe un campo para instrucciones de sistema, personalidad, herramientas ni contexto propio. La solicitud contiene la conversación, una ubicación y un idioma.

El servidor no conserva la transcripción por ti. Envía los turnos anteriores en messages cada vez, junto con el mismo session_id.

Un session_id es exclusivo de tu organización. El contexto temporal de conversación se guarda por organización, por lo que otra organización que envíe el mismo ID no puede ver ni modificar tu conversación. Dentro de tu organización, asigna un ID distinto a cada conversación de cada usuario.

Límites de solicitudes

Las solicitudes que superen cualquiera de estos límites se rechazan con 422 antes de generar la respuesta, sin cargo. El cuerpo es {"detail": "<code>"}.

Límite	Valor	Código
Mensajes en messages	400	too_many_messages
Longitud del content de un mensaje	64.000 caracteres	message_too_long
Longitud conjunta de todos los valores de content	200.000 caracteres	conversation_too_long
session_id	De 1 a 128 caracteres: letras, dígitos, _, ., :, -	invalid_session_id
lang	35 caracteres	lang_too_long
layout	16 caracteres	invalid_layout

Todos los mensajes cuentan para estos límites, incluso los ignorados. Una conversación larga suele alcanzar primero el límite de longitud total y no el número de mensajes; envía los turnos recientes y elimina los antiguos. Consulta Leer el flujo.

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 desactiva el búfer de salida de curl para mostrar los fotogramas al llegar. Ejemplo de respuesta abreviada:

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

Estado	Código	Cuándo
413	request_too_large	El cuerpo supera 2 MiB.
422	validación	El cuerpo no es JSON válido o un campo tiene tipo incorrecto.
422	too_many_messages, message_too_long, conversation_too_long, invalid_session_id, lang_too_long, invalid_layout	La solicitud supera un límite.
429	quota_exceeded	Los créditos de IA o el límite mensual de la clave no cubren la llamada.

El evento quota del ejemplo es el que recibe una clave de servidor. Un flujo leído con token de sesión contiene una versión más breve. Consulta el evento quota.

Una vez iniciado el flujo, los fallos llegan como eventos error, no como códigos de estado. Para crear un cliente, consulta Lectura del flujo.

POST /chat/control/route

Calcula una ruta entre coordenadas que ya conoces. No se formula ninguna pregunta ni se genera texto.

Autenticación: clave de servidor, token de sesión o clave heredada. Ámbito: ai. Cargo: ninguno. Aun así, es necesario disponer de saldo suficiente en los créditos de IA para admitir la llamada.

Campo	Tipo	Obligatorio	Predeterminado	Notas
places	matriz de objetos	Sí, al menos dos	[]	Cada elemento es { lat, lng, name? } con lat y lng numéricos en el nivel superior del objeto. Se admite label en lugar de name. Las entradas sin lat y lng numéricos se omiten sin error.
profile	cadena	No	"driving"	driving, walking, cycling o transit. Cualquier otro valor usa driving.
raw_query	cadena	No	"Show directions"	Texto que escribió el usuario, si existe.

El primer lugar es el origen y el último es el destino.

La forma de un lugar difiere de la del flujo

Un evento place del flujo de chat anida la posición: { "coordinates": { "lat": …, "lng": … } }. Este endpoint requiere lat y lng directamente en el objeto. Pasar un lugar del flujo sin cambios devuelve error, porque ninguna entrada contiene coordenadas utilizables.

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

Una respuesta correcta es un 200 con action (valores ilustrativos):

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

Dibuja action.payload.coordinates, una lista de pares [lng, lat]. distance_m está en metros y duration_s en segundos. Muestra attribution.text enlazado a attribution.url siempre que dibujes la ruta.

Con profile: "transit", payload.transit contiene un trayecto de un solo servicio: caminar, viajar y caminar. No incluye attribution en el nivel superior; el crédito del operador está en payload.transit.attribution. Muéstralo donde presentes el viaje.

Este endpoint informa de fallos con HTTP 200

No poder planificar una ruta no es un error 4xx. La respuesta es 200 con una cadena error y sin action:

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

Sucede cuando el planificador no puede conectar los lugares o falla por cualquier motivo. Si hay menos de dos lugares con coordenadas válidas, el texto es At least two resolved places are required to build a route.. Está pensado para mostrarse directamente, así que comprueba la existencia de error y no su redacción. Un trayecto en transporte público sin servicio directo responde de igual forma, explicando la causa y con tres campos adicionales: reason, covered y available.

Comprueba el cuerpo de la respuesta, no el estado:

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

Los fallos de autenticación, ámbitos, validación, cuota y límites de frecuencia siguen siendo respuestas normales 401, 403, 422 y 429.

GET /retrieval/geocode/forward

Convierte texto escrito en lugares y direcciones postales coincidentes. Está pensado para un campo de búsqueda o los campos Desde/Hasta.

Autenticación: clave de servidor, token de sesión o clave heredada. Ámbito: ai. Cargo: créditos de IA, tarifa fija por llamada, incluso cuando results está vacío.

Parámetro	Tipo	Obligatorio	Predeterminado	Notas
q	cadena	Sí		De 1 a 200 caracteres: nombre de lugar, dirección con número de portal o lat,lng escrito.
near_lat	número	No		De −90 a 90. Prioriza coincidencias cercanas. Solo con near_lng.
near_lng	número	No		De −180 a 180. Solo con near_lat.
limit	entero	No	5	De 1 a 20.
mode	cadena	No		Modo de desplazamiento (driving, walking, cycling, transit). Los trayectos cortos priorizan las coincidencias próximas.

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

Cada resultado tiene lat, lng, display_name, type y source. Los demás campos aparecen cuando corresponda:

Campo del resultado	Significado
id	Para una dirección: identificador Kaleidr del portal, estable al actualizar los datos; puede almacenarse y compararse.
confidence	Cómo coincidió el texto con el resultado (tabla siguiente). No aparece con lat,lng escrito.
approximate, method, matched_numbers, within_m, score	Solo para direcciones estimadas (más abajo).
attribution	Condiciones del conjunto de origen: dataset, license y, cuando corresponda, license_url, attribution (crédito que mostrar) y use_restriction.

confidence	El resultado es
exact	Número de portal introducido en la calle y localidad solicitadas.
fuzzy	Lo mismo, pese a un error ortográfico en la calle.
name_exact	Un lugar cuyo nombre coincide con tus palabras.
locality	Localidad, región o barrio mencionado.
interpolated, nearest	Estimación de un número de portal ausente en los datos.
partial	Calle más larga cuyo nombre empieza por lo que escribiste.
name_partial	Lugar cuyo nombre comparte parte de tus palabras.
ambiguous	Dirección sin localidad ni referencia cercana especificadas: una entre varias.

Direcciones estimadas. Si no existe el número de portal escrito, el sistema lo sitúa en la calle correspondiente: entre los números conocidos más cercanos del mismo lado, en el número conocido más cercano o a lo largo de la manzana cuyo rango de numeración lo incluye. El resultado lleva approximate: true y:

Campo	Significado
method	"interpolated" (entre dos números conocidos), "nearest" (en el número conocido cercano) o "range" (a lo largo de la manzana).
matched_numbers	Números utilizados para estimar la posición.
within_m	Distancia en metros entre dichos números o longitud de la manzana: máximo error posible si la numeración sigue un orden. Ausente con "nearest".
score	Grado de confianza de 0 a 1. Trata una puntuación baja como resultado a nivel de calle y no de portal exacto.

Una coincidencia exacta nunca incluye estos campos.

Atribución. Incluye el campo superior attribution con los resultados. Su text es el crédito que debe mostrarse y licenses son los términos que deben acompañar a los datos. Cuando hay direcciones, attribution.sources enumera los conjuntos de direcciones empleados. Para esos resultados debes cumplir la use_restriction de cada conjunto:

Conjunto de datos	Crédito que mostrar	Restricción de uso
au/countrywide (G-NAF)	G-NAF © Geoscape Australia, bajo licencia de la Commonwealth de Australia según el Open Geo-coded National Address File (G-NAF) End User Licence Agreement.	No usar para generar direcciones ni compilaciones destinadas a correo postal, salvo que se verifique la recepción de cada dirección con una fuente distinta de G-NAF; el uso debe cumplir los Australian Privacy Principles.
ca/countrywide (Statistics Canada)	Adaptado de Statistics Canada, National Address Register, 2025-07-29. Esto no implica respaldo del producto por parte de Statistics Canada.	No identificar personas, empresas u organizaciones ni insinuar respaldo por Statistics Canada.
us/ny/city_of_new_york	Datos de direcciones del NYC Department of City Planning.	Ninguna.
us/ma/statewide (MassGIS)	MassGIS (Bureau of Geographic Information), Commonwealth of Massachusetts EOTSS	Ninguna (dominio público).

Sin coincidencias y fallo interno parecen iguales. Una consulta sin resultados devuelve 200 con "results": []. También ocurre si la búsqueda falla internamente; ese caso no se cobra. Considera la lista vacía como «no hay nada que mostrar», no como un error.

Estado	Código	Cuándo
422	validación	Falta q, está vacío o supera 200 caracteres; limit o una coordenada quedan fuera de rango.
429	quota_exceeded	Los créditos de IA no cubren la solicitud.

POST /spot

Indica qué hay en un punto: el lugar seleccionado, la dirección postal más cercana y las regiones que contienen el punto. Cada valor identifica la atribución que debes mostrar. Si se solicita, añade contenido descriptivo y fotografías del lugar.

Autenticación: clave de servidor, token de sesión o clave heredada. Ámbito: ai. Cargo: créditos de IA, una tarifa fija por llamada determinada por el elemento más costoso solicitado en want, se haya encontrado algo o no. content o photos cobran la tarifa de /retrieval/poi/enrich cuando el contenido se obtiene para esta llamada; en su ausencia, address cobra la tarifa de /retrieval/geocode/forward. El contenido ya obtenido para una solicitud anterior no tiene coste, así que esa llamada, si también solicita address, cobra la tarifa de geocodificación. Una llamada que solo solicita entities, regions, boundaries o tenants es gratuita. El valor predeterminado de want incluye address, por lo que omitir want supone cobrar la tarifa de geocodificación.

Campo	Tipo	Obligatorio	Predeterminado	Notas
lat	número	Sí		De −90 a 90. El punto.
lng	número	Sí		De −180 a 180.
zoom	número	No		De 0 a 24. Nivel de zoom del mapa.
hint	objeto	No		Elemento en el que hizo clic el usuario (abajo).
want	matriz de cadenas	No	["entities", "address", "regions"]	Partes que se devolverán (abajo).
lang	cadena	No	"en"	Idioma de content. Máximo 16 caracteres.

El punto determina el resultado; la pista solo lo selecciona. La pista permite elegir entre lo que se encuentra en el punto, pero nunca mueve la respuesta: no se devuelve un lugar a más de 75 metros de lat, lng, independientemente de lo que indique la pista.

Campo hint	Notas
id	Identificador de Kaleidr para el lugar: la parte de una referencia poi: situada después de los dos puntos.
name	Nombre del lugar, tal como aparece en la etiqueta del mapa. Máximo de 200 caracteres. Se compara de forma exacta con los lugares situados en el punto y se usa para identificar el lugar en content. Si region_level es county, state o country, también selecciona la región de ese nivel cuyo nombre coincida, sin distinguir entre mayúsculas y minúsculas ni entre caracteres con y sin tildes, de entre las regiones presentes en el punto (para estados o países, también las situadas a un máximo de 5 km del punto). Si el nombre no coincide con ninguna, no cambia nada.
category	Categoría del lugar. Máximo de 100 caracteres. Se utiliza para content.
region_level	Con boundaries, devuelve únicamente el contorno de la región de este nivel (city, county, state o country); sin esa opción, devuelve los contornos de todas las regiones. Con name, la región de este nivel tanto en regions como en boundaries será la seleccionada por el nombre.
layer, wiki_title, ta_location_id, yelp_business_id, data_source	Se aceptan. Los utilizan las aplicaciones de Kaleidr; omítelos.

Valor de want	Añade
entities	El lugar en el que se ha hecho clic, cuando hint identifica uno situado en ese punto.
address	La dirección de calle más cercana.
regions	La ciudad y el condado (solo en Estados Unidos), el estado y el país que contienen el punto. Si el punto se encuentra mar adentro, a un máximo de 5 km de la costa, se devuelven el estado y el país más cercanos.
boundaries	regions, cada una con su contorno (solo un nivel si se indica hint.region_level).
content	Contenido descriptivo del lugar: resumen, fotos y enlace. Requiere el nombre de un lugar, obtenido del lugar seleccionado o de hint.name.
photos	Solo las fotos del lugar. Tiene el mismo coste que content.
tenants	Los lugares con nombre próximos al punto, ordenados del más cercano al más lejano: los negocios de un edificio. Tu aplicación conserva los que están dentro de la huella del edificio que muestra.

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

Respuesta abreviada con valores ilustrativos:

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

Campo	Significado
spot	Punto enviado: { lat, lng, zoom }.
entities	Lugar seleccionado y, si se solicitaron, negocios del edificio; de lo contrario, una lista vacía. Cada elemento contiene ref, kind ("poi" para el lugar seleccionado, "tenant" para un negocio), role ("clicked" o "inside"), name, at (posición propia del lugar, { lat, lng }) y facts (category y, si se conoce, website del lugar seleccionado). La ref de un negocio es una referencia poi:, por lo que también se puede transmitir su descripción. Ignora valores de kind desconocidos.
address	Dirección postal más cercana o null: { ref, line, at }.
regions	Regiones que contienen el punto, empezando por la más pequeña. Cada una tiene ref, kind ("region"), level (city, county, state o country), name y label: punto para mostrar el nombre, { lat, lng }, o null. Con want: ["boundaries"] también incluye geometry, el contorno como geometría GeoJSON.
content	Se incluye cuando want contiene content o photos, se conoce el nombre del lugar y se permite devolver contenido. Es el objeto de /retrieval/poi/enrich (campos), o { photos, source, cached } si solo se solicitan photos, con license y attr añadidos. Puede ser null si no se encontró contenido.
attributions	Atribuciones de la respuesta: { text, license }, indexadas por el attr de cada valor.
withheld	Información omitida por restricciones de la API, agrupada por tipo; lista vacía si nada se omitió.

Una ref identifica un elemento para /spot/overview/stream: poi:<id> para un lugar, address:<id> para una dirección y region:<source>:<id> para una región (<source> vale tiger, nuts o ne). Las aplicaciones de Kaleidr también utilizan building:<id>, que la API no devuelve. Trata cada referencia como una cadena opaca.

Mostrar la atribución de cada valor

Cada valor procedente de un conjunto de datos es un objeto { value, license, attr }: el dato, su licencia y una clave de attributions. Siempre que muestres un valor, muestra también attributions[attr].text, junto a él o en una sección accesible de créditos. Una respuesta puede mezclar diversas fuentes; no basta con atribuir la respuesta entera a una sola. Conserva license y el crédito con el valor cuando lo almacenes o compartas.

content recibe la misma atribución mediante su propio attr. Un valor con live_only: true solo puede mostrarse al usuario actual; nunca debe almacenarse ni compartirse.

Consulta Licencias de datos para conocer los requisitos de cada licencia.

Lo que la API no devuelve

Las aplicaciones propias de Kaleidr muestran más información sobre un punto que la API, ya que algunos datos no están autorizados para usarse en otros sitios web:

• Datos sujetos a la ODbL procedentes de OpenStreetMap: información de edificios (plantas, altura y clasificación). Tampoco se ofrecen descripciones de edificios.
• Respuestas de terceros: direcciones obtenidas de servicios de geocodificación, así como puntuaciones, reseñas y fotografías de Yelp y Tripadvisor.

withheld permite distinguir entre «no se conoce información de este lugar» y «no está disponible mediante la API». Solo identifica tipos, nunca valores: building_facts cuando el punto está dentro de un edificio, y content cuando el único contenido existente para ese lugar no puede devolverse. Otras entradas identifican del mismo modo distintas partes omitidas.

Errores de POST /spot:

Estado	Código	Cuándo
413	request_too_large	El cuerpo de la solicitud supera 2 MiB.
422	validación	Falta lat o lng, están fuera de rango, zoom no está entre 0 y 24, want contiene un valor desconocido o algún campo es demasiado largo o incorrecto.
429	quota_exceeded	Los créditos de IA no cubren la solicitud.

Una parte que no se pueda consultar se devuelve vacía (null o []). La llamada se cobra igualmente.

POST /spot/overview/stream

Transmite una descripción breve de un elemento devuelto por /spot, identificado por su ref.

Autenticación: clave de servidor, token de sesión o clave heredada. Ámbito: ai. Cargo: créditos de IA según los tokens utilizados. Cada descripción se redacta para su solicitud. Respuesta: text/event-stream: normalmente una trama place con el nombre completo del lugar, como "Springfield, Ohio, United States of America", y después las tramas de un resumen de lugar; consulta Flujos de resúmenes y botones.

Campo	Tipo	Obligatorio	Predeterminado	Notas
ref	cadena	Sí		Una ref devuelta por /spot, de hasta 128 caracteres, o place: (abajo).
lat, lng	número	Sí		El punto enviado a /spot.
lang	cadena	No	"en"	Idioma de la descripción. Máximo 16 caracteres.
hint	objeto	Solo para place:		{ name, category? }: nombre que debe describirse.

ref	Descripción
poi:<id>	El lugar.
region:<source>:<id>	La región.
place:	Un nombre para el que Kaleidr no tiene registro, como un lugar sin entidad en /spot. Envía su nombre en hint.name.
address:<id>, building:<id>	No disponible mediante la API: la transmisión envía una trama error. Consulta Lo que la API no devuelve.

El elemento se vuelve a localizar usando lat, lng, de modo que nada de lo incluido en la solicitud se toma como un hecho sobre él. Una referencia poi: a más de 75 metros del punto, una referencia region: que no contiene el punto o place: sin hint.name también generan una trama 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"}'

Una referencia que no puede describirse devuelve este fotograma en lugar de un resumen. Incluye ref, pero no partial_text:

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

Estado	Código	Cuándo
413	request_too_large	El cuerpo de la solicitud supera 2 MiB.
422	validación	ref no tiene uno de los formatos indicados, falta lat o lng o están fuera de rango, o lang supera los 16 caracteres.
429	quota_exceeded	Los créditos de IA no cubren la solicitud.

Migración desde endpoints obsoletos

GET /retrieval/poi/enrich y POST /chat/summary/stream están obsoletos. Seguirán respondiendo como antes hasta el 2027-01-15 y podrán eliminarse en cualquier momento posterior. Sus respuestas incluyen encabezados de obsolescencia; Deprecation indica el día de retirada del soporte, 2026-10-16, como marca de tiempo Unix:

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

El encabezado Link de /chat/summary/stream apunta a /inference-api/b2b/v1/spot/overview/stream. Registra el encabezado Sunset para identificar las llamadas que aún realizas.

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

Antes	Después
lat, lon (consulta)	lat, lng (cuerpo). Observa el cambio de nombre.
name, category	hint.name, hint.category
lang	lang, máximo 16 caracteres
Consulta completa	want: ["content"]
photos_only=true	want: ["photos"]
radius, dataSource, ta_location_id, regionLevel	Omítelos.
Cuerpo de la respuesta	content: el mismo objeto con el campo adicional live_only
attribution	content.attribution

El cargo es el mismo o menor: /spot no cobra el contenido ya obtenido para una solicitud anterior. Una consulta se cobra por el elemento más costoso de want, así que, cuando el contenido se obtiene para la llamada, añadir entities, address o regions los devuelve en la misma llamada sin coste adicional.

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

Antes	Después
Un lugar: location, building_properties.name, .category	Llama a /spot con el punto y hint: { name, category }; después transmite la descripción de la ref del lugar presente en entities usando los mismos lat y lng. Si entities está vacío, envía ref: "place:" con el mismo hint.
building_properties.pid	ref: "poi:<id>"
lang	lang, máximo 16 caracteres
max_tokens	Omítelo.
Un edificio: type: "building" y sus campos	No tiene sucesor. Las descripciones de edificios no están disponibles mediante la API.
Tramas	Las tramas de una descripción de lugar, tras una nueva trama place que nombra el lugar.

GET /retrieval/poi/enrich

Obsoleto

Este endpoint está obsoleto y puede eliminarse después del 2027-01-15. Utiliza POST /spot con want: ["content"]. Consulta Migración desde endpoints obsoletos.

Devuelve contenido descriptivo sobre un lugar: título, resumen, fotos y enlace.

Autenticación: clave de servidor, token de sesión o clave heredada. Ámbito: ai. Cargo: créditos de IA, tarifa fija por llamada. La tarifa se cobra tanto si se encuentra contenido como si no.

Parámetro	Tipo	Obligatorio	Predeterminado	Notas
lat	número	Sí		Latitud del lugar.
lon	número	Sí		Longitud del lugar. Ten en cuenta que se llama lon, no lng.
name	cadena	No		Nombre del lugar. Recomendado, porque un punto aislado a menudo no encuentra coincidencias.
category	cadena	No		Categoría del lugar según el evento place.
radius	entero	No	250	Radio de búsqueda alrededor del punto, en metros.
lang	cadena	No	"en"	Idioma del contenido.
photos_only	booleano	No	false	Devolver solo fotos (respuesta más pequeña, abajo).
dataSource, ta_location_id, regionLevel	cadena	No		Se aceptan como pistas internas de Kaleidr; omítelos.

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

Campo	Tipo	Significado
source	cadena	Procedencia del contenido. "omitted" significa que existe contenido, pero no se puede devolver mediante la API (abajo).
found	booleano	false si no se encontró nada; los demás campos aparecen vacíos.
title	cadena	Título del lugar en la fuente.
summary	cadena o null	Descripción breve.
photos	matriz de URL	Puede estar vacía.
url	cadena o null	Enlace a la página de origen.
attribution	matriz de cadenas	Fuentes que debes acreditar, por ejemplo ["Wikipedia"]. Muéstralas con el contenido.
rating, phone, hours, reviews		Pueden ser null o estar vacíos. La API nunca devuelve puntuaciones ni reseñas de proveedores bajo licencia.
unverified	booleano	Opcional. true cuando la correspondencia del lugar no es segura.

Con photos_only=true, la respuesta es { "photos": […], "source": "…", "cached": false }.

Contenido no disponible. Algunos contenidos solo cuentan con licencia para las aplicaciones de Kaleidr. Si es el único contenido disponible para un lugar, la respuesta es 200 con "source": "omitted", "found": false y sin contenido. La solicitud igualmente se cobra. Consulta Licencias de datos.

Estado	Código	Cuándo
422	validación	Falta lat o lon o no es un número.
429	quota_exceeded	Los créditos de IA no cubren la solicitud.
500	An internal error occurred. Please try again.	Falló la búsqueda. La llamada igualmente se cobra.

---

POST /chat/summary/stream

Obsoleto

Este endpoint está obsoleto y puede eliminarse después del 2027-01-15. Utiliza POST /spot/overview/stream. Las descripciones de edificios no tienen sucesor. Consulta Migración desde endpoints obsoletos.

Transmite un breve resumen escrito de un lugar o edificio. Sirve como contenido de la ficha de lugar de Kaleidr Chat.

Autenticación: clave de servidor, token de sesión o clave heredada. Ámbito: ai. Cargo: créditos de IA según los tokens utilizados. Cada resumen se genera específicamente para su solicitud. Respuesta: text/event-stream. Consulta Flujos de resúmenes y botones.

El campo type del cuerpo selecciona el tipo de resumen.

Un edificio ("type": "building"):

Campo	Tipo	Obligatorio	Notas
type	cadena	Sí	"building".
address	cadena	Sí	Dirección completa del edificio. Máximo 500 caracteres.
lat, lng	número	No	Ubicación del edificio.
building_levels	entero	No	Número de plantas, si se conoce.
building_height_m	número	No	Altura del edificio en metros, si se conoce.
tenant_names	matriz de cadenas	No	Negocios dentro del edificio. Hasta 100 nombres de 200 caracteres cada uno.
poi_count	entero	No	Número de lugares dentro del edificio.
lang	cadena	No	Valor predeterminado "en". Máximo 35 caracteres.

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 lugar (type ausente o "poi"). El cuerpo admite location (objeto { lat, lng }), building_properties (objeto), lang y max_tokens (entero). Esta variante está diseñada para el panel de Kaleidr; la semántica de sus campos todavía no constituye un contrato publicado. Si consultas lugares desde tu propio código, utiliza preferentemente /chat/control/stream.

Campo del lugar	Límite
building_properties.name, .type, .category, .poi_type	200 caracteres cada uno
building_properties.pid	128 caracteres
Cada campo de texto de building_properties.event	4.000 caracteres
lang	35 caracteres
max_tokens	Si se supera el límite predeterminado del endpoint, el valor se reduce a dicho límite. No puedes solicitar una descripción más larga.

Ambas variantes solo leen los campos enumerados aquí. Se ignoran los demás campos del cuerpo. Si alguno supera su límite de longitud, se rechaza con 422 field_too_long antes de generar la descripción.

Estado	Código	Cuándo
413	request_too_large	El cuerpo de la solicitud supera 2 MiB.
422	field_too_long	Un campo supera el límite o tenant_names tiene más de 100 entradas. El cuerpo es {"detail": "field_too_long"}.
500	Summary stream error	No se pudo leer el cuerpo o una solicitud sobre un edificio carece de address. Este endpoint responde 500, y no 422, a otros cuerpos incorrectos.
429	quota_exceeded	Los créditos de IA no cubren la solicitud.

POST /chat/button/stream

Transmite la respuesta a una pregunta independiente sobre un lugar, por ejemplo «¿Cuál es su horario de apertura?». Es el endpoint de los botones de preguntas de las fichas de Kaleidr Chat. No mantiene una conversación: cada solicitud es independiente.

Autenticación: clave de servidor, token de sesión o clave heredada. Ámbito: ai. Cargo: créditos de IA según los tokens utilizados. Respuesta: text/event-stream. Consulta Flujos de resúmenes y botones.

Campo	Tipo	Obligatorio	Predeterminado	Notas
query	cadena	Sí		La pregunta. Máximo 4.000 caracteres.
place_name	cadena	No		Nombre del lugar consultado. Máximo 200 caracteres.
place_type	cadena	No		Su categoría. Máximo 200 caracteres.
address	cadena	No		Dirección del lugar. Máximo 500 caracteres.
location	objeto { lat, lng }	No		Su posición.
lang	cadena	No	"en"	Idioma de respuesta. Máximo 35 caracteres.
description	cadena	No		Descripción del lugar de la que ya dispones. Máximo 4.000 caracteres.
website	cadena	No		Sitio web del lugar, si se conoce. Máximo 2.048 caracteres.
stores_preview	matriz de objetos { name }	No		Negocios del lugar que ya conoces. Hasta 50 elementos; cada name con máximo 200 caracteres. Se ignoran otros campos.
button_id, session_id, place_id	cadena	No		Identificadores propios para relacionar solicitudes. Máximo 128 caracteres cada uno.

Se ignoran los campos que no figuran en esta tabla. Si un campo supera su longitud máxima, se rechaza con 422 field_too_long antes de generar la respuesta.

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}

Estado	Código	Cuándo
413	request_too_large	El cuerpo supera 2 MiB.
422	field_too_long	Un campo es demasiado largo o stores_preview tiene más de 50 elementos. El cuerpo es {"detail": "field_too_long"}.
500	Button chat stream error	No se pudo leer el cuerpo o falta query. Otros cuerpos incorrectos generan 500, no 422.
429	quota_exceeded	Los créditos de IA no cubren la solicitud.

---

POST /design/analyze

Examina las columnas y una muestra de la tabla y recomienda cómo representarlas en el mapa.

El Editor insertado no llama a los endpoints de diseño. Son una interfaz REST para tus propias herramientas.

Autenticación: clave de servidor, token de sesión o clave heredada. Ámbito: design. Cargo: créditos de IA, tarifa fija por llamada completada correctamente. Las llamadas fallidas no se cobran.

Campo	Tipo	Obligatorio	Notas
columns	matriz de cadenas	Sí	Entre 1 y 256 nombres de columnas, todos únicos.
sampleRows	matriz de objetos	No	Hasta 1.000 filas; cada objeto utiliza los nombres de columnas como claves.
datasetName	cadena	No	Máximo 512 caracteres.
rowCount	entero	No	Cantidad total de filas de la tabla, igual o superior a 0.
userGoal	cadena	No	Hasta 1.000 caracteres: qué debe mostrar el mapa.
supportedStyles	matriz de cadenas	No	Identificadores de estilos disponibles, escritos con minúsculas y guiones.

Los nombres de campos usan camelCase. Se ignoran los campos desconocidos.

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

Consulta designPlan. Puede ser null. recommendation, suggestedConfig y explanation son campos antiguos que se conservan por compatibilidad y que se eliminarán; no dependas de ellos. issues enumera los problemas detectados en los datos.

Estado	Código	Cuándo
413	request_too_large	El cuerpo supera 5 MiB. El mismo límite se aplica a /design/apply-direct.
422	validación	Falta columns, está vacío, es demasiado largo o contiene duplicados; o se supera alguno de los límites anteriores.
429	quota_exceeded	Los créditos de IA no cubren la solicitud.
500	map_design_analyze_failed	Falló el análisis. No se cobra.

POST /design/apply-direct

Crea una capa de mapa a partir de una tabla y un estilo elegido, sin análisis.

Autenticación: clave de servidor, token de sesión o clave heredada. Ámbito: design. Cargo: ninguno.

Campo	Tipo	Obligatorio	Notas
style	cadena	Sí	Identificador de estilo, de 1 a 64 caracteres. Se enumera en /design/styles.
config	objeto	Sí	Objeto con location, metric y visual. Son obligatorios location.mode ("coordinates" o "region") y visual.layerName; los demás subcampos todavía no están documentados.
table	objeto	Sí	{ fileName?, columns[], rows[] }. Cada fila relaciona nombres de columnas con valores. Todos deben ser cadenas JSON: envía "120000", no 120000. Una fila con un número o null se rechaza con 422.
layerLabel	cadena	Sí	Nombre visible de la capa, de 1 a 512 caracteres.
themePackId	cadena	No	Identificador de tema de /design/themes. Se ignoran los desconocidos.
datasetSource	objeto	No	{ label, url? }: quién publicó los datos, para acreditar la fuente de la capa.
datasetId	cadena	No	Hasta 128 caracteres. Se usa como identificador de capa.
year	entero	No	De 1800 a 2100.

La respuesta siempre contiene un status:

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

status	Significado
applied	spec contiene la capa.
unsupported-style	No es posible crear ese estilo con estos datos. message indica el motivo.
insufficient-data	Faltan datos necesarios en la tabla, como columnas de coordenadas. message explica el problema.

Las tres respuestas son 200. Comprueba status.

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

Tres catálogos de solo lectura: estilos de mapa disponibles, mapas de ejemplo y paquetes de temas.

Autenticación: clave de servidor, token de sesión o clave heredada. Ámbito: design. Cargo: ninguno. Estas llamadas cuentan para las solicitudes por minuto de la clave, pero no para la concurrencia.

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

Cada respuesta contiene su lista bajo una única clave:

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

/design/samples devuelve { "samples": [ … ] } y /design/themes devuelve { "themes": [ … ] }.

---

Errores comunes a todos los endpoints de ejecución

Todos los endpoints excepto los dos intercambios de sesión pueden devolver estos errores antes de procesar su funcionalidad específica. Se comprueban en este orden.

Orden	Estado	Código	Cuándo
1	401	Invalid or missing API key	No se envió credencial o la clave es desconocida, revocada o caducada.
2	401	publishable_requires_session	Se envió una clave publicable; intercámbiala primero por una sesión.
2	403	server_key_in_browser	Se envió una clave de servidor con encabezado Origin.
2	403	session_origin_mismatch	Se utilizó un token de sesión desde otro origen.
2	403	ip_not_allowed	La llamada con una clave de servidor o antigua procede de una IP fuera de su lista permitida.
3	403	insufficient_scope	La clave carece del permiso requerido por el endpoint.
3	403	tier_capability_not_allowed	La clave tiene el permiso, pero tu plan actual no lo incluye.
3	403	product_not_allowed	Una clave de servidor o antigua limitada a determinados productos accede al endpoint de otro producto. Consulta Restricciones de claves.
4	429	quota_exceeded	Solo endpoints de pago: el saldo de créditos o el límite de la clave no cubre la llamada.
5	429	visitor_limit_reached	Solo sesiones de mapas publicados: el visitante ha enviado demasiadas solicitudes.
6	429	rate_limited	Se ha agotado el número de solicitudes por minuto permitido para la clave.
7	429	b2b_overloaded, org_overloaded	Hay demasiadas solicitudes simultáneas.

Un cuerpo demasiado grande se rechaza con 413 request_too_large: 2 MiB para los endpoints en general y 5 MiB para /design/*. Si la solicitud declara su longitud, el rechazo se produce antes de todas las comprobaciones anteriores.

Los cuerpos de respuesta y su tratamiento se describen en Errores y Cuotas y límites de frecuencia.

Temas relacionados

• Inicio rápido en servidor: primera llamada, paso a paso.
• Contrato de transmisión SSE: todos los eventos de transmisión.
• Lectura de la transmisión: ejemplos completos de clientes.
• Licencias de datos: atribuciones que debes mostrar.