엔드포인트

Kaleidr 플랫폼 API의 모든 공개 엔드포인트를 절별로 설명합니다.

• 기본 URL: https://api.kaleidr.com/inference-api/b2b/v1
• 인증 정보: Authorization: Bearer … 또는 X-Api-Key: …를 사용합니다. 백엔드에서는 서버 키(kld_sk_live_…), 브라우저에서는 세션 토큰(kld_sess_live_…)을 사용합니다. 공개용 키는 세션 교환에서만 허용됩니다. 인증 및 범위를 참조하세요.
• 요청 본문: JSON, UTF-8 형식입니다. 모든 POST 요청에 Content-Type: application/json을 보내세요. 요청 본문은 최대 2 MiB이며 /design/* 엔드포인트는 최대 5 MiB입니다. 초과하면 413 request_too_large 오류가 발생합니다.
• 오류: 4xx 또는 5xx 응답에는 JSON 본문이 포함되며 오류에 설명되어 있습니다. 한 엔드포인트는 실패해도 200을 반환합니다. 경로 안내를 참조하세요.

예제에서는 환경 변수에 저장된 서버 키를 사용합니다:

export KALEIDR_KEY="kld_sk_live_…"

요약

엔드포인트	목적	범위	요금
POST /sdk/sessions	공개용 키를 세션으로 교환	제품별 범위	tile은 지도 로드 1회, 그 외에는 무료
POST /sdk/share-sessions	게시된 지도 ID를 채팅 세션으로 교환	없음	무료
POST /chat/control/stream	질문하고 답변·장소·작업·경로를 스트리밍	ai	사용한 토큰에 따른 AI 크레딧
POST /chat/control/route	좌표가 알려진 두 지점 간 경로 안내	ai	무료
GET /retrieval/geocode/forward	입력 텍스트를 장소 및 주소로 변환	ai	AI 크레딧, 고정 요금
POST /spot	좌표 지점의 장소·주소·지역 및 선택적 콘텐츠 조회	ai	AI 크레딧, 고정 요금
POST /spot/overview/stream	/spot에서 반환한 항목의 짧은 설명을 스트리밍	ai	사용한 토큰에 따른 AI 크레딧
GET /retrieval/poi/enrich	사용 중단 예정, /spot 사용. 장소 상세 정보와 사진	ai	AI 크레딧, 고정 요금
POST /chat/summary/stream	사용 중단 예정, /spot/overview/stream 사용. 장소나 건물 설명 스트리밍	ai	사용한 토큰에 따른 AI 크레딧
POST /chat/button/stream	하나의 장소에 관한 질문의 답변 스트리밍	ai	사용한 토큰에 따른 AI 크레딧
POST /design/analyze	데이터 테이블에 적합한 지도 디자인 추천	design	AI 크레딧, 고정 요금
POST /design/apply-direct	테이블과 스타일로 지도 레이어 만들기	design	무료
GET /design/styles, /design/samples, /design/themes	디자인 카탈로그	design	무료

과금, 보류 및 제한의 작동 방식은 할당량 및 속도 제한을 참조하세요.

모든 런타임 엔드포인트에서 모든 런타임 엔드포인트의 공통 오류가 반환될 수 있습니다. 아래 각 절에는 해당 엔드포인트에만 적용되는 오류가 나와 있습니다.

---

POST /sdk/sessions

공개용 키를 요청한 출처와 하나의 제품에 바인딩된 단기 세션 토큰으로 교환합니다. SDK는 키를 사용하는 모든 마운트에서 자동으로 교환합니다. 자체 브라우저 클라이언트를 구현할 때만 이 엔드포인트를 직접 호출하세요.

인증: 게시 가능 키. 필수: Origin 헤더(브라우저가 추가). 요금: product가 tile일 때 지도 로드 1회, 그 외에는 없음.

필드	유형	필수	설명
product	문자열	예	chat, editor, viewer, 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는 조직의 기본 베이스맵을 가리키며 설정되지 않은 경우 null입니다.

상태	코드	발생 조건
401	Invalid or missing API key	알 수 없거나 철회되었거나 만료된 키.
403	publishable_key_required	서버 키 또는 레거시 키가 전송됨.
403	origin_required	Origin 헤더가 없음.
403	origin_not_allowed	요청 출처가 키의 허용 출처 목록에 없음.
403	product_not_allowed	키의 허용 제품에 product가 포함되지 않음.
403	tier_capability_not_allowed	현재 요금제에서 제품 또는 범위를 지원하지 않음.
403	insufficient_scope	키 생성 시 제품에 필요한 범위를 부여하지 않음.
422	유효성 검사	product가 없거나 네 가지 값 중 하나가 아님.
429	rate_limited	키의 세션 교환 요청이 너무 많음. Retry-After: 5.
429	map_load_quota_exceeded	tile 전용: 지도 로드 할당량을 모두 사용함.
404	sessions_disabled	플랫폼에서 세션이 비활성화됨. 지원팀에 문의하세요.
503	sessions_not_configured	플랫폼 장애. 다시 시도하고 지속되면 지원팀에 문의하세요.

유효 기간, 갱신 규칙 및 검사 순서는 인증 및 범위: 세션 교환에 설명되어 있습니다.

POST /sdk/share-sessions

게시된 지도 ID를 채팅 세션으로 교환하여 페이지에 키를 넣지 않고 방문자가 채팅할 수 있게 합니다. Studio에서 지도의 Kaleidr AI 타일이 요청한 기능을 켜 두어야 합니다.

인증: 없음. 필수: Origin 헤더. 요금: 없음. 세션을 사용한 채팅 호출 비용은 지도 소유자의 조직에 청구됩니다.

필드	유형	필수	설명
share_id	문자열	예	영문자, 숫자, _, -로 구성된 1~128자.
feature	문자열	아니요	control_tower(기본값, 지도의 Ask Kaleidr 패널) 또는 popups(팝업의 AI 채팅). 각 기능은 해당 스위치가 켜져 있을 때만 허용됩니다.

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

상태	코드	발생 조건
403	origin_required	Origin 헤더 없음.
404	not_found	해당 ID의 게시된 지도나 공유 링크가 없거나, 공유 링크의 지도가 게시 취소됨.
403	chat_disabled	지도의 Kaleidr AI가 요청한 기능을 켜지 않음.
403	origin_not_allowed	페이지가 지도에서 허용한 도메인에 포함되지 않음.
403	owner_has_no_organization	지도 소유자에게 요금을 청구할 조직이 없음.
403	tier_capability_not_allowed	소유자 요금제에 채팅 기능이 없음.
422	유효성 검사	share_id가 없거나 허용되지 않는 문자를 포함함, 또는 feature가 두 값 중 어느 것도 아님.
429	rate_limited	지도 또는 해당 주소에서 세션 교환을 너무 많이 요청함. Retry-After: 5.
404	sessions_disabled	플랫폼에서 세션이 비활성화됨.
503	share_grant_unavailable, sessions_not_configured	플랫폼 장애. 다시 시도하세요.

게시된 지도의 Kaleidr AI를 참조하세요.

---

POST /chat/control/stream

질문을 받아 답변을 작성하는 대로 텍스트를 스트리밍하고, 언급한 장소의 좌표, 지도 작업 및 경로도 전달합니다. Kaleidr Chat에서 사용하는 핵심 엔드포인트입니다.

인증: 서버 키, 세션 토큰 또는 레거시 키. 범위: ai. 요금: AI 크레딧, 답변에 사용된 토큰 수에 따라 청구됩니다. 응답: text/event-stream. SSE 전송 규약에 설명되어 있습니다.

필드	유형	필수	기본값	설명
messages	{ role, content } 배열	아니요	[]	지금까지의 대화를 오래된 순서로 나열하고 사용자의 새 메시지로 끝냅니다. role은 user 또는 assistant입니다. system을 비롯한 다른 역할과 content가 빈 메시지는 무시합니다. 마지막 user 메시지에 답변합니다. 크기 제한은 아래를 참조하세요.
session_id	문자열	아니요	자동 생성	영문자, 숫자, _, ., :, -로 된 1~128자 대화 ID. 안정적인 ID를 지정하고 모든 턴에서 반복해서 보내세요. 생략하면 서버가 요청에 대한 ID를 생성해 phase 및 start 이벤트에서 반환합니다.
location	객체 { lat, lng }	아니요	없음	사용자가 보고 있는 위치, 즉 지도 중심. '이 근처'라는 표현을 해석할 때 사용합니다.
map_zoom	숫자	아니요	없음	지도 확대 수준.
lang	문자열	아니요	"en"	답변 언어를 나타내는 BCP 47 태그. 예: fr, pt-BR. 최대 35자.
layout	문자열	아니요	없음	대화가 진행되는 viewer 레이아웃. 임베드된 viewer가 가이드 레이아웃을 표시하는 동안 "guide"이며, 그 외에는 생략하세요. 최대 16자.
app_snapshot	객체	아니요	없음	허용하지만 필요하지 않으므로 생략하세요.
auto_actions	불리언	아니요	없음	허용하지만 필요하지 않으므로 생략하세요.

알 수 없는 필드도 허용하지만 무시합니다. 시스템 지침, 페르소나, 도구 또는 자체 컨텍스트를 넣을 수 있는 필드는 없습니다. 요청에는 대화, 위치, 언어만 담깁니다.

서버는 대화 기록을 저장해 주지 않습니다. 매 호출마다 이전 대화를 messages에 넣고 동일한 session_id를 보내세요.

session_id는 조직별로 독립적입니다. 대화의 단기 컨텍스트가 조직 단위로 분리되어 있어, 다른 조직이 동일한 ID를 전송하더라도 해당 대화를 읽거나 변경할 수 없습니다. 조직 내부에서는 각 최종 사용자의 대화마다 별도의 ID를 부여하세요.

요청 제한

이러한 제한을 초과한 요청은 답변 생성 전에 422로 거부되고 과금되지 않습니다. 본문은 {"detail": "<code>"}입니다.

제한 항목	값	코드
messages 안의 메시지 수	400	too_many_messages
단일 메시지 content 길이	64,000자	message_too_long
모든 content의 총 길이	200,000자	conversation_too_long
session_id	영문자, 숫자, _, ., :, -로 구성된 1~128자	invalid_session_id
lang	35자	lang_too_long
layout	16자	invalid_layout

무시되는 메시지도 제한에 포함됩니다. 긴 대화는 대개 메시지 수 제한보다 전체 길이 제한에 먼저 도달합니다. 필요한 최신 턴만 보내고 오래된 턴은 제거하세요. 스트림 읽기를 참조하세요.

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은 curl 출력 버퍼링을 해제하여 프레임이 도착하는 즉시 표시합니다. 아래는 예시 값을 포함한 축약 응답입니다:

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

상태	코드	발생 조건
413	request_too_large	요청 본문이 2 MiB를 초과함.
422	유효성 검사	본문이 유효한 JSON이 아니거나 필드의 타입이 잘못됨.
422	too_many_messages, message_too_long, conversation_too_long, invalid_session_id, lang_too_long, invalid_layout	요청 제한을 초과함.
429	quota_exceeded	AI 크레딧 할당량 또는 이 키의 월간 상한이 부족함.

예시의 quota 이벤트는 서버 키를 사용했을 때 받는 내용입니다. 세션 토큰으로 읽는 스트림에는 더 간단한 형태가 포함됩니다. quota 이벤트를 참조하세요.

스트림이 시작된 뒤 오류가 발생하면 HTTP 상태 대신 error 이벤트로 전달됩니다. 클라이언트를 구현하려면 스트림 읽기를 참조하세요.

POST /chat/control/route

이미 알고 있는 두 좌표 사이의 경로를 계산합니다. 질문을 받거나 텍스트를 생성하지 않습니다.

인증: 서버 키, 세션 토큰 또는 레거시 키. 범위: ai. 요금: 없음. 다만 호출이 허용되려면 AI 크레딧에 충분한 여유가 있어야 합니다.

필드	유형	필수	기본값	설명
places	객체 배열	예, 최소 2개	[]	각 항목은 { lat, lng, name? }이며 숫자형 lat과 lng가 객체의 최상위 수준에 있어야 합니다. name 대신 label을 사용할 수 있습니다. 숫자형 lat 또는 lng가 없으면 오류 없이 건너뜁니다.
profile	문자열	아니요	"driving"	driving, walking, cycling, transit 중 하나. 그 외 값은 driving으로 처리됩니다.
raw_query	문자열	아니요	"Show directions"	사용자가 입력한 표현(있는 경우).

첫 번째 장소는 출발지이고 마지막 장소는 목적지입니다.

장소 데이터 구조가 스트림과 다릅니다

채팅 스트림의 place 이벤트는 위치를 { "coordinates": { "lat": …, "lng": … } } 형태로 중첩합니다. 하지만 이 엔드포인트는 lat과 lng가 객체의 최상위에 있어야 합니다. 스트림의 장소를 그대로 전달하면 유효한 좌표를 찾지 못해 error 응답을 반환합니다.

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

성공 응답은 action이 포함된 200입니다(값은 예시입니다):

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

action.payload.coordinates에 담긴 [lng, lat] 쌍 목록으로 경로를 그리세요. distance_m은 미터, duration_s는 초 단위입니다. 경로를 표시할 때는 항상 attribution.text를 표시하고 attribution.url로 연결하세요.

profile: "transit"이면 payload.transit에는 도보, 대중교통 1회 탑승, 도보로 구성된 환승 없는 여정이 들어 있습니다. 최상위 수준에는 attribution이 없고 운송사업자 출처 표시는 payload.transit.attribution에 있습니다. 여정과 함께 표시하세요.

이 엔드포인트는 HTTP 200으로 실패를 알림

경로 계획 실패는 4xx 오류가 아닙니다. error 문자열이 포함되고 action은 없는 200 응답을 반환합니다:

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

경로 계획기가 장소를 연결할 수 없거나 다른 이유로 실패하면 이런 응답이 발생합니다. 유효한 좌표를 가진 장소가 두 개 미만이면 At least two resolved places are required to build a route.라는 문구가 반환됩니다. 이 문구는 사용자에게 그대로 보여주도록 작성되었으므로 텍스트가 아니라 error 필드의 존재 여부로 판단하세요. 직행 대중교통편이 없을 때도 같은 방식으로 사유와 추가 필드 reason, covered, available을 반환합니다.

상태 코드가 아니라 응답 본문으로 분기하세요:

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

인증, 범위, 유효성 검사, 할당량 및 속도 제한 실패는 일반적인 401, 403, 422, 429 응답으로 반환됩니다.

GET /retrieval/geocode/forward

입력한 텍스트를 일치하는 장소와 주소로 변환합니다. 검색창이나 출발지/목적지 입력란에 맞춰 설계되었습니다.

인증: 서버 키, 세션 토큰 또는 레거시 키. 범위: ai. 요금: AI 크레딧, 호출당 고정 요금입니다. results가 비어 있어도 청구됩니다.

매개변수	유형	필수	기본값	설명
q	문자열	예		1~200자: 장소명, 건물 번호가 있는 주소 또는 직접 입력한 lat,lng.
near_lat	숫자	아니요		−90~90. 가까운 검색 결과의 순위를 올립니다. near_lng와 함께 사용해야 합니다.
near_lng	숫자	아니요		−180~180. near_lat와 함께 사용해야 합니다.
limit	정수	아니요	5	1~20.
mode	문자열	아니요		이동 수단(driving, walking, cycling, transit). 짧은 이동은 가까운 결과를 우선합니다.

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

모든 결과에는 lat, lng, display_name, type, source가 포함됩니다. 나머지 필드는 해당하는 경우 표시됩니다:

결과 필드	의미
id	도로명 주소에서 해당 출입구를 식별하는 Kaleidr ID입니다. 데이터가 업데이트되어도 유지되므로 저장하고 비교할 수 있습니다.
confidence	텍스트와 결과가 일치한 방식(다음 표). lat,lng를 입력했을 때는 없습니다.
approximate, method, matched_numbers, within_m, score	아래에서 설명하는 추정 주소에만 제공됩니다.
attribution	이 결과의 원본 데이터세트 조건: dataset, license와 해당되는 경우 license_url, attribution(표시할 출처), use_restriction.

confidence	결과의 의미
exact	입력한 번호, 도로, 지역이 정확히 일치함.
fuzzy	도로명에 오타가 있지만 같은 주소를 찾음.
name_exact	입력한 단어와 이름이 정확히 같은 장소.
locality	입력한 도시, 지역 또는 동네.
interpolated, nearest	데이터에 없는 건물 번호의 추정 위치.
partial	도로 전체 이름이 입력한 글자로 시작함.
name_partial	장소 이름이 입력 단어와 일부 일치함.
ambiguous	지역이나 가까운 기준점이 지정되지 않은 주소로, 여러 후보 중 하나.

추정 주소. 입력한 건물 번호가 데이터에 없으면 같은 도로의 같은 쪽에 있는 가장 가까운 번호들 사이, 가장 가까운 기존 번호 위치 또는 해당 번호 범위를 포함하는 블록 안에 배치합니다. 결과에는 approximate: true와 다음 값이 포함됩니다.

필드	의미
method	"interpolated"(기존 번호 두 개 사이), "nearest"(가까운 기존 번호), "range"(블록을 따라 배치).
matched_numbers	위치 추정의 기준이 된 번호.
within_m	기준 번호 사이 거리 또는 블록의 길이(미터). 도로의 번호가 순서대로 매겨졌을 때 가능한 최대 오차입니다. "nearest"에서는 제공하지 않습니다.
score	0~1의 신뢰도. 낮은 값은 출입구의 정확한 위치가 아니라 도로 수준의 위치로 취급하세요.

정확히 일치하는 결과에는 이러한 필드가 포함되지 않습니다.

출처 표시. 결과와 함께 최상위 attribution을 전달하세요. text는 화면에 표시해야 할 출처이고, licenses에는 데이터에 동반되어야 하는 이용 조건이 들어 있습니다. 결과에 도로명 주소가 포함되면 attribution.sources에 사용된 주소 데이터세트가 열거됩니다. 해당 결과는 각 데이터세트의 use_restriction을 준수해야 합니다.

데이터세트	표시할 출처	이용 제한
au/countrywide (G-NAF)	G-NAF © Geoscape Australia, 호주 연방정부가 Open Geo-coded National Address File (G-NAF) End User Licence Agreement에 따라 라이선스를 부여함.	G-NAF 외의 출처를 통해 각 주소가 우편물을 받을 수 있는지 검증하지 않는 한, 우편 발송에 사용할 주소나 주소 목록을 생성해서는 안 됩니다. 사용은 Australian Privacy Principles를 준수해야 합니다.
ca/countrywide (Statistics Canada)	Statistics Canada, National Address Register, 2025-07-29에서 수정·가공함. 이는 Statistics Canada가 본 제품을 보증한다는 뜻이 아닙니다.	개인, 사업체, 조직의 신원을 확인하거나 Statistics Canada의 보증을 암시하는 데 사용할 수 없습니다.
us/ny/city_of_new_york	NYC Department of City Planning의 주소 데이터.	없음.
us/ma/statewide (MassGIS)	MassGIS (Bureau of Geographic Information), Commonwealth of Massachusetts EOTSS	없음(퍼블릭 도메인).

검색 결과 없음과 내부 실패는 같은 형태입니다. 일치하는 항목이 없으면 200과 "results": []를 반환합니다. 검색 자체가 내부적으로 실패했을 때도 같지만 그 경우에는 요금이 부과되지 않습니다. 빈 배열은 오류가 아니라 '표시할 항목 없음'으로 처리하세요.

상태	코드	발생 조건
422	유효성 검사	q가 없거나 비어 있거나 200자를 초과함. limit 또는 좌표가 허용 범위를 벗어남.
429	quota_exceeded	AI 크레딧이 부족함.

POST /spot

한 지점에 무엇이 있는지 알려줍니다. 사용자가 클릭한 장소, 가장 가까운 도로명 주소, 해당 지점이 속한 지역을 반환합니다. 각 값에는 표시해야 할 출처 정보가 붙습니다. 요청하면 장소에 대한 설명과 사진도 추가합니다.

인증: 서버 키, 세션 토큰 또는 레거시 키. 범위: ai. 요금: AI 크레딧, want에서 요청한 항목 중 가장 비싼 항목에 따른 고정 요금이며 검색 결과가 없어도 청구됩니다. content 또는 photos는 이 호출을 위해 콘텐츠를 가져올 때 /retrieval/poi/enrich 요금이 적용되고, 그렇지 않으면 address에 /retrieval/geocode/forward 요금이 적용됩니다. 이전 요청에서 이미 가져온 콘텐츠는 요금이 없으므로, 이런 호출에 address도 요청하면 지오코딩 요금이 청구됩니다. entities, regions, boundaries, tenants만 요청하는 호출은 무료입니다. 기본 want에 address가 포함되므로 want를 생략하면 지오코딩 요금이 청구됩니다.

필드	유형	필수	기본값	설명
lat	숫자	예		−90~90. 대상 지점의 위도.
lng	숫자	예		−180~180. 경도.
zoom	숫자	아니요		0~24. 지도 확대 수준.
hint	객체	아니요		사용자가 클릭한 대상(아래 설명).
want	문자열 배열	아니요	["entities", "address", "regions"]	반환할 정보의 종류(아래 설명).
lang	문자열	아니요	"en"	content의 언어. 최대 16자.

위치가 결과를 결정하고 힌트는 선택만 돕습니다. 힌트는 지정된 지점에 있는 항목 사이에서 선택할 뿐 결과의 위치를 이동시키지 않습니다. 힌트에 어떤 이름이 있든 lat, lng에서 75m보다 멀리 있는 장소는 반환되지 않습니다.

hint 필드	설명
id	장소의 Kaleidr ID입니다. poi: 참조에서 콜론 뒤에 오는 부분입니다.
name	지도 레이블에 표시되는 장소 이름입니다. 최대 200자입니다. 지정된 지점에 있는 장소의 이름과 정확히 일치하는지 확인하며, content에 사용할 장소를 지정합니다. region_level이 county, state, country 중 하나이면 해당 지점의 같은 수준에 있는 지역 중 이름이 일치하는 지역도 선택합니다. 비교할 때 대소문자와 발음 구별 기호는 무시합니다(주 또는 국가의 경우 해당 지점에서 5 km 이내에 있는 지역도 포함). 일치하는 지역이 없으면 아무것도 변경되지 않습니다.
category	장소의 카테고리입니다. 최대 100자입니다. content에 사용됩니다.
region_level	boundaries를 지정하면 이 수준(city, county, state, country)의 지역 경계선만 반환하고, 지정하지 않으면 모든 지역의 경계선을 반환합니다. name을 함께 지정하면 regions와 boundaries 모두에서 이 수준의 지역은 이름으로 선택된 지역이 됩니다.
layer, wiki_title, ta_location_id, yelp_business_id, data_source	허용되는 필드입니다. Kaleidr 자체 앱에서 사용하므로 요청에서는 생략하세요.

want 값	추가되는 내용
entities	hint가 해당 지점에 위치한 장소를 지정하는 경우 클릭한 장소입니다.
address	가장 가까운 도로명 주소입니다.
regions	해당 지점이 포함된 시와 카운티(미국에만 해당), 주, 국가입니다. 해안에서 바다 쪽으로 최대 5 km 떨어진 지점에는 가장 가까운 주와 국가를 반환합니다.
boundaries	각 지역의 경계선이 포함된 regions입니다(hint.region_level을 지정하면 한 수준만 포함).
content	장소의 설명 콘텐츠로, 요약, 사진, 링크가 포함됩니다. 클릭한 장소 또는 hint.name에서 얻은 장소 이름이 필요합니다.
photos	장소의 사진만 반환합니다. 비용은 content와 같습니다.
tenants	해당 지점 인근에서 이름이 지정된 장소를 가까운 순서대로 반환합니다. 즉, 건물 안의 사업체들입니다. 앱은 표시된 건물의 외곽선 안에 있는 장소만 유지해야 합니다.

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

예시 값이 포함된 축약 응답:

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

필드	의미
spot	전송한 지점: { lat, lng, zoom }.
entities	클릭한 장소와 요청한 경우 입주 업소가 뒤따르며, 없으면 빈 배열입니다. 항목마다 ref, kind(클릭한 장소는 "poi", 입주 업소는 "tenant"), role("clicked" 또는 "inside"), name, at(실제 위치 { lat, lng }), facts(category, 알려진 경우 클릭한 장소의 website)가 있습니다. 업소의 ref도 poi: 참조이므로 개요를 스트리밍할 수 있습니다. 모르는 kind의 항목은 무시하세요.
address	가장 가까운 도로명 주소 또는 null: { ref, line, at }.
regions	지점을 포함하는 지역을 작은 지역부터 반환합니다. 각 항목에는 ref, kind("region"), level(city, county, state, country), name, 그리고 지역명 표시용 위치인 label({ lat, lng } 또는 null)이 포함됩니다. want: ["boundaries"]를 지정하면 GeoJSON 형식의 지역 윤곽 geometry도 포함됩니다.
content	want에 content 또는 photos가 있고 장소명이 알려져 있으며 제공 가능한 콘텐츠가 있을 때 포함됩니다. /retrieval/poi/enrich가 반환하는 객체(필드), 또는 photos 전용인 경우 { photos, source, cached }에 다른 값과 마찬가지로 license와 attr를 추가한 것입니다. 콘텐츠를 찾지 못하면 null일 수 있습니다.
attributions	응답에 포함된 출처 표기: 각 값의 attr로 찾는 { text, license }.
withheld	API가 반환할 수 없어 생략한 정보의 종류. 생략한 내용이 없으면 빈 배열입니다.

ref는 /spot/overview/stream에서 사용할 대상을 나타냅니다. 장소는 poi:<id>, 주소는 address:<id>, 지역은 region:<source>:<id>를 사용합니다(<source>는 tiger, nuts, ne 중 하나입니다). Kaleidr 자체 앱에서는 building:<id>도 사용하지만 API는 이를 반환하지 않습니다. 참조 문자열의 내부 구조를 해석하지 마세요.

각 값의 출처 표시

데이터세트에서 온 값은 모두 { value, license, attr } 객체로 전달됩니다. 이는 값, 라이선스, attributions를 참조하는 키입니다. 어떤 값을 표시하든 attributions[attr].text도 함께 표시하세요. 값 옆이나 사용자가 접근할 수 있는 출처 영역에 넣을 수 있습니다. 하나의 응답에 여러 출처가 혼합되므로 응답 전체에 한 줄의 출처만 표시해서는 부족합니다. 저장하거나 전달하는 값에는 license와 출처 표기를 함께 보존하세요.

content 역시 자체 attr를 통해 같은 방식으로 출처를 표시해야 합니다. live_only: true가 붙은 값은 현재 사용자에게만 보여줄 수 있으며 저장하거나 다른 사람에게 전달할 수 없습니다.

각 라이선스 요구 사항은 데이터 라이선스를 참조하세요.

API가 반환하지 않는 정보

Kaleidr의 자체 앱은 API보다 지점에 대한 정보를 더 많이 보여줍니다. 일부 데이터는 다른 사이트에서 사용할 수 있도록 라이선스가 부여되지 않았기 때문입니다:

• OpenStreetMap에서 파생된 ODbL 적용 값: 건물의 층수, 높이, 분류 등 속성. 건물 개요도 제공하지 않습니다.
• 제3자 제공업체의 응답: 외부 지오코딩 서비스의 주소 검색 결과, Yelp 및 Tripadvisor의 평점, 리뷰, 사진.

withheld를 통해 '정보가 존재하지 않음'과 'API로 제공할 수 없음'을 구별할 수 있습니다. 실제 값이 아니라 정보 종류만 표시합니다. 지점이 건물 안에 있으면 building_facts, 장소의 유일한 콘텐츠를 제공하지 못할 가능성이 있으면 content가 포함될 수 있습니다. 다른 항목도 같은 방식으로 생략된 응답 부분을 나타냅니다.

POST /spot의 오류:

상태	코드	발생 조건
413	request_too_large	요청 본문이 2 MiB보다 큼.
422	유효성 검사	lat 또는 lng가 없거나 범위를 벗어남, zoom이 0~24 범위 밖임, want에 알 수 없는 값이 있음, 필드가 길이 제한을 넘었거나 형식이 잘못됨.
429	quota_exceeded	AI 크레딧 잔액이 호출에 충분하지 않음.

조회하지 못한 항목은 빈 값(null 또는 [])으로 반환됩니다. 호출 비용은 그대로 청구됩니다.

POST /spot/overview/stream

/spot에서 반환한 항목의 ref를 지정해 짧은 설명을 스트리밍합니다.

인증: 서버 키, 세션 토큰 또는 레거시 키. 범위: ai. 요금: AI 크레딧, 사용한 토큰 수에 따라 청구됩니다. 각 개요는 요청할 때마다 새로 작성됩니다. 응답: text/event-stream. 보통 장소의 전체 이름(예: "Springfield, Ohio, United States of America")이 담긴 place 프레임이 먼저 오고, 이어서 장소 요약 프레임이 전송됩니다. 요약 및 버튼 스트림을 참조하세요.

필드	유형	필수	기본값	설명
ref	문자열	예		/spot 응답의 ref(최대 128자) 또는 아래의 place:.
lat, lng	숫자	예		/spot에 전송한 지점.
lang	문자열	아니요	"en"	설명문을 작성할 언어. 최대 16자.
hint	객체	place:에만 필요		{ name, category? }: 설명할 레이블.

ref	설명 대상
poi:<id>	장소.
region:<source>:<id>	지역.
place:	Kaleidr에 기록이 없는 이름 있는 대상. 예를 들어 /spot이 해당 장소의 엔터티를 반환하지 않은 경우입니다. hint.name에 이름을 보내세요.
address:<id>, building:<id>	API로 제공되지 않습니다. 스트림에서 error 프레임 하나를 보냅니다. API에서 제공하지 않는 정보를 참조하세요.

대상은 lat, lng 위치에서 다시 조회하므로 요청에 넣은 내용이 자동으로 사실로 받아들여지지 않습니다. 기준 지점에서 75m를 넘는 poi: 참조, 지점을 포함하지 않는 region: 참조, hint.name이 없는 place: 역시 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"}'

설명할 수 없는 참조는 요약 대신 이 프레임으로 응답합니다. ref가 포함되고 partial_text는 없습니다:

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

상태	코드	발생 조건
413	request_too_large	요청 본문이 2 MiB보다 큼.
422	유효성 검사	ref가 위 형식이 아님, lat 또는 lng가 없거나 범위 밖임, lang이 16자를 초과함.
429	quota_exceeded	AI 크레딧이 부족함.

지원 중단 예정 엔드포인트에서 이전

GET /retrieval/poi/enrich와 POST /chat/summary/stream은 사용 중단 예정입니다. 2027-01-15까지는 이전처럼 작동하며 그 이후에는 언제든 제거될 수 있습니다. 모든 응답 헤더에 관련 정보가 포함됩니다. Deprecation 헤더에는 사용 중단 예정으로 지정된 날짜인 2026-10-16가 Unix 타임스탬프로 담깁니다.

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

/chat/summary/stream의 Link 헤더는 /inference-api/b2b/v1/spot/overview/stream을 지정합니다. 아직 사용 중인 호출을 찾으려면 Sunset 헤더를 기록하세요.

GET /retrieval/poi/enrich에서 POST /spot으로:

이전	이후
lat, lon(쿼리)	lat, lng(본문). 필드 이름에 주의하세요.
name, category	hint.name, hint.category
lang	lang, 최대 16자
전체 조회	want: ["content"]
photos_only=true	want: ["photos"]
radius, dataSource, ta_location_id, regionLevel	생략하세요.
응답 본문	content: 동일한 객체에 live_only 추가
attribution	content.attribution

요금은 같거나 더 낮습니다. /spot은 이전 요청에서 이미 가져온 콘텐츠에 요금을 부과하지 않습니다. 조회 요금은 want에서 가장 비싼 항목 기준이므로, 이 호출을 위해 콘텐츠를 가져올 때 entities, address, regions를 추가하면 추가 요금 없이 한 번의 호출로 함께 받을 수 있습니다.

POST /chat/summary/stream에서 POST /spot/overview/stream으로:

변경 전	변경 후
장소: location, building_properties.name, .category	해당 좌표와 hint: { name, category }로 /spot을 호출하고, 같은 lat와 lng를 사용해 entities에 있는 장소의 ref 개요를 스트리밍합니다. entities가 비어 있으면 동일한 hint와 함께 ref: "place:"를 보내세요.
building_properties.pid	ref: "poi:<id>"
lang	lang, 최대 16자
max_tokens	생략하세요.
건물: type: "building" 및 관련 필드	후속 API가 없습니다. 건물 개요는 API로 제공하지 않습니다.
프레임	장소 이름을 담은 새 place 프레임 뒤에 장소 개요용 프레임이 이어집니다.

GET /retrieval/poi/enrich

사용 중단 예정

이 엔드포인트는 사용 중단 예정이며 2027-01-15 이후 삭제될 수 있습니다. want: ["content"]를 사용해 POST /spot을 호출하세요. 사용 중단 예정 엔드포인트에서 이전하기를 참조하세요.

한 장소의 설명 콘텐츠(제목, 요약, 사진, 링크)를 반환합니다.

인증: 서버 키, 세션 토큰 또는 레거시 키. 범위: ai. 요금: AI 크레딧, 호출당 고정 요금입니다. 콘텐츠가 검색되지 않아도 요금이 청구됩니다.

매개변수	유형	필수	기본값	설명
lat	숫자	예		장소의 위도.
lon	숫자	예		장소의 경도. lng가 아니라 lon입니다.
name	문자열	아니요		장소 이름. 좌표만으로는 찾지 못할 때가 많으므로 권장합니다.
category	문자열	아니요		place 이벤트에 제공된 장소 분류.
radius	정수	아니요	250	지점 주변의 검색 반경(미터).
lang	문자열	아니요	"en"	콘텐츠 언어.
photos_only	불리언	아니요	false	사진만 반환(응답 크기가 작음, 아래 참조).
dataSource, ta_location_id, regionLevel	문자열	아니요		허용되지만 Kaleidr 자체 패널용 힌트입니다. 생략하세요.

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

필드	유형	의미
source	문자열	콘텐츠 출처. "omitted"는 콘텐츠가 존재하지만 API로 반환하지 못할 수 있음을 뜻합니다(아래 설명).
found	불리언	찾지 못하면 false이며 나머지 필드는 비어 있습니다.
title	문자열	원본 출처에 있는 장소 제목.
summary	문자열 또는 null	짧은 설명.
photos	URL 배열	비어 있을 수 있음.
url	문자열 또는 null	출처 페이지 링크.
attribution	문자열 배열	표시해야 하는 출처 이름. 예: ["Wikipedia"]. 콘텐츠와 함께 표시하세요.
rating, phone, hours, reviews		null이거나 비어 있을 수 있습니다. 라이선스가 필요한 제공업체의 평점과 리뷰는 API에서 반환하지 않습니다.
unverified	불리언	선택적 필드. true이면 장소 일치가 확실하지 않음을 뜻합니다.

photos_only=true인 경우 응답은 { "photos": […], "source": "…", "cached": false }입니다.

제공이 제한되는 콘텐츠. 일부 콘텐츠는 Kaleidr 자체 앱에서만 사용할 수 있도록 라이선스가 부여됩니다. 해당 장소에 이런 콘텐츠만 있으면 응답은 200이고 "source": "omitted", "found": false이며 콘텐츠는 포함되지 않습니다. 이 호출에도 요금이 부과됩니다. 데이터 라이선스를 참조하세요.

상태	코드	발생 조건
422	유효성 검사	lat 또는 lon이 누락되었거나 숫자가 아님.
429	quota_exceeded	AI 크레딧이 부족함.
500	An internal error occurred. Please try again.	조회가 실패함. 호출 요금은 부과됨.

---

POST /chat/summary/stream

사용 중단 예정

이 엔드포인트는 사용 중단 예정이며 2027-01-15 이후 삭제될 수 있습니다. POST /spot/overview/stream을 사용하세요. 건물 설명을 반환하는 후속 기능은 없습니다. 사용 중단 예정 엔드포인트에서 이전하기를 참조하세요.

한 장소 또는 건물의 짧은 글 요약을 스트리밍합니다. Kaleidr Chat 장소 카드에서 사용됩니다.

인증: 서버 키, 세션 토큰 또는 레거시 키. 범위: ai. 요금: AI 크레딧, 사용한 토큰 수에 따라 청구됩니다. 각 요약은 요청할 때마다 새로 작성됩니다. 응답: text/event-stream. 요약 및 버튼 스트림을 참조하세요.

본문의 type이 요약 유형을 선택합니다.

건물 ("type": "building"):

필드	유형	필수	설명
type	문자열	예	"building".
address	문자열	예	건물 전체 주소. 최대 500자.
lat, lng	숫자	아니요	건물 위치.
building_levels	정수	아니요	알고 있는 경우 층수.
building_height_m	숫자	아니요	알고 있는 경우 건물 높이(미터).
tenant_names	문자열 배열	아니요	건물 내 사업체 이름. 최대 100개, 각 200자 이하.
poi_count	정수	아니요	건물 내 장소 개수.
lang	문자열	아니요	기본값 "en". 최대 35자.

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

장소(type 생략 또는 "poi"). 본문은 location(객체 { lat, lng }), building_properties(객체), lang, max_tokens(정수)를 받습니다. 이 형식은 Kaleidr 자체 패널용이며 각 필드의 의미가 아직 공개 계약으로 확정되지 않았습니다. 자체 코드에서 장소에 대해 질문하려면 /chat/control/stream을 사용하세요.

장소 필드	제한
building_properties.name, .type, .category, .poi_type	각각 200자
building_properties.pid	128자
building_properties.event의 각 텍스트 필드	4,000자
lang	35자
max_tokens	엔드포인트 기본값을 초과하면 기본값으로 줄어듭니다. 더 긴 설명을 요청할 수 없습니다.

두 방식 모두 여기에 나열된 필드만 읽습니다. 본문에 추가된 다른 필드는 무시됩니다. 길이 제한을 초과한 필드는 설명을 생성하기 전에 422 field_too_long으로 거부됩니다.

상태	코드	발생 조건
413	request_too_large	요청 본문이 2 MiB보다 큼.
422	field_too_long	필드가 제한을 넘거나 tenant_names에 100개 넘는 항목이 있음. 본문은 {"detail": "field_too_long"}.
500	Summary stream error	본문을 읽을 수 없거나 건물 요청에 address가 없음. 이 엔드포인트의 다른 잘못된 본문은 422가 아니라 500을 반환함.
429	quota_exceeded	AI 크레딧이 부족함.

POST /chat/button/stream

장소 하나에 관한 질문 하나, 예를 들어 '영업시간이 어떻게 되나요?'에 답하는 내용을 스트리밍합니다. Kaleidr Chat의 장소 카드에 있는 질문 버튼에서 사용합니다. 대화 문맥은 없으며 매번 독립적인 요청입니다.

인증: 서버 키, 세션 토큰 또는 레거시 키. 범위: ai. 요금: AI 크레딧, 사용한 토큰 수에 따라 청구됩니다. 응답: text/event-stream. 요약 및 버튼 스트림을 참조하세요.

필드	유형	필수	기본값	설명
query	문자열	예		질문. 최대 4,000자.
place_name	문자열	아니요		질문할 장소 이름. 최대 200자.
place_type	문자열	아니요		장소 분류. 최대 200자.
address	문자열	아니요		장소 주소. 최대 500자.
location	객체 { lat, lng }	아니요		위치.
lang	문자열	아니요	"en"	답변 언어. 최대 35자.
description	문자열	아니요		이미 보유한 장소 설명. 최대 4,000자.
website	문자열	아니요		알고 있는 경우 장소 웹사이트. 최대 2,048자.
stores_preview	객체 배열 { name }	아니요		이미 알고 있는 경우 이 장소에 있는 사업체. 최대 50개, 각 name은 200자 이하. 항목의 다른 속성은 무시됩니다.
button_id, session_id, place_id	문자열	아니요		요청 연관관계를 추적하기 위한 자체 식별자. 각 최대 128자.

표에 없는 필드는 무시됩니다. 길이 제한을 초과한 필드는 답변이 생성되기 전에 422 field_too_long으로 거부됩니다.

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}

상태	코드	발생 조건
413	request_too_large	요청 본문이 2 MiB보다 큼.
422	field_too_long	필드의 길이가 초과되거나 stores_preview에 50개 넘는 항목이 있음. 본문은 {"detail": "field_too_long"}.
500	Button chat stream error	본문을 읽을 수 없거나 query가 없음. 이 엔드포인트의 다른 잘못된 본문은 422가 아니라 500을 반환함.
429	quota_exceeded	AI 크레딧이 부족함.

---

POST /design/analyze

테이블의 열과 샘플을 확인하고 지도에 표시하는 방법을 추천합니다.

임베드된 Editor는 디자인 엔드포인트를 호출하지 않습니다. 이들은 자체 도구용 REST 인터페이스입니다.

인증: 서버 키, 세션 토큰 또는 레거시 키. 범위: design. 요금: AI 크레딧, 성공한 호출당 고정 요금입니다. 실패한 호출에는 요금이 청구되지 않습니다.

필드	유형	필수	설명
columns	문자열 배열	예	서로 다른 컬럼 이름 1~256개.
sampleRows	객체 배열	아니요	최대 1,000개 행. 각 행은 컬럼 이름을 키로 하는 객체.
datasetName	문자열	아니요	최대 512자.
rowCount	정수	아니요	원본 테이블 전체 행 수, 0 이상.
userGoal	문자열	아니요	최대 1,000자. 지도에서 보여주려는 내용.
supportedStyles	문자열 배열	아니요	선택할 수 있는 스타일 ID. 소문자 단어를 하이픈으로 연결한 형식.

필드 이름은 camelCase입니다. 알 수 없는 필드는 무시됩니다.

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

designPlan을 확인하세요. 값은 null일 수 있습니다. recommendation, suggestedConfig, explanation은 호환성을 위해 남겨둔 이전 필드로 향후 삭제될 예정이므로 이에 의존해 구현하지 마세요. issues에는 데이터에서 발견된 문제가 나열됩니다.

상태	코드	발생 조건
413	request_too_large	요청 본문이 5 MiB를 초과함. /design/apply-direct에도 동일한 제한 적용.
422	유효성 검사	columns가 없거나 비었거나 너무 길거나 중복됨. 또는 위 제한을 초과함.
429	quota_exceeded	AI 크레딧 부족.
500	map_design_analyze_failed	분석에 실패함. 요금 부과 없음.

POST /design/apply-direct

분석 없이 테이블과 선택한 스타일을 사용해 지도 레이어를 만듭니다.

인증: 서버 키, 세션 토큰 또는 레거시 키. 범위: design. 요금: 없음.

필드	유형	필수	설명
style	문자열	예	1~64자 스타일 ID. /design/styles에서 확인할 수 있습니다.
config	객체	예	location, metric, visual을 포함하는 객체. location.mode("coordinates" 또는 "region")와 visual.layerName은 필수이며 나머지 하위 필드는 아직 문서화되지 않았습니다.
table	객체	예	{ fileName?, columns[], rows[] }. 각 행은 컬럼명과 값으로 된 객체이며, 모든 값은 JSON 문자열이어야 합니다. 120000이 아니라 "120000"을 보내세요. 숫자나 null이 포함된 행은 422로 거부됩니다.
layerLabel	문자열	예	레이어의 표시 이름. 1~512자.
themePackId	문자열	아니요	/design/themes의 테마 ID. 알 수 없는 ID는 무시합니다.
datasetSource	객체	아니요	{ label, url? }: 레이어의 출처 표시에 사용할 데이터 게시자.
datasetId	문자열	아니요	최대 128자. 레이어 ID로 사용합니다.
year	정수	아니요	1800~2100.

응답에는 항상 status가 포함됩니다:

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

status	의미
applied	spec에 레이어가 담겨 있습니다.
unsupported-style	전달한 데이터로 스타일을 생성할 수 없습니다. message에 이유가 나옵니다.
insufficient-data	위치 컬럼 등 스타일에 필요한 데이터가 테이블에 없습니다. message에 부족한 항목이 나옵니다.

세 응답 모두 200입니다. status를 확인하세요.

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

사용 가능한 지도 스타일, 지도 예제, 테마 팩의 읽기 전용 카탈로그 세 개입니다.

인증: 서버 키, 세션 토큰 또는 레거시 키. 범위: design. 요금: 없음. 이 호출은 키의 분당 요청 한도에는 포함되지만 동시 요청 한도에는 포함되지 않습니다.

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

각 응답은 하나의 키 아래에 목록을 담습니다:

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

/design/samples는 { "samples": [ … ] }를 반환하고 /design/themes는 { "themes": [ … ] }를 반환합니다.

---

모든 런타임 엔드포인트의 공통 오류

두 세션 교환 엔드포인트를 제외한 모든 엔드포인트는 자체 작업을 시작하기 전에 이 오류들을 반환할 수 있습니다. 다음 순서로 검사합니다.

순서	상태	코드	발생 조건
1	401	Invalid or missing API key	인증 정보가 없거나 알 수 없는 키, 철회된 키, 만료된 키.
2	401	publishable_requires_session	공개용 키가 전송됨. 먼저 세션으로 교환해야 합니다.
2	403	server_key_in_browser	서버 키가 Origin 헤더와 함께 전송됨.
2	403	session_origin_mismatch	다른 출처에서 세션 토큰을 사용함.
2	403	ip_not_allowed	IP 허용 목록이 있는 서버/레거시 키를 목록 밖의 주소에서 사용함.
3	403	insufficient_scope	키에 엔드포인트에 필요한 범위가 없음.
3	403	tier_capability_not_allowed	키에는 범위가 있지만 현재 요금제에서 제공하지 않음.
3	403	product_not_allowed	특정 제품으로 제한된 서버/레거시 키로 다른 제품의 엔드포인트를 호출함. 키 제한을 참조하세요.
4	429	quota_exceeded	과금되는 엔드포인트에만 적용: 공동 크레딧 풀 또는 키의 사용 한도가 부족함.
5	429	visitor_limit_reached	게시된 지도 세션에서 해당 방문자의 요청이 너무 많음.
6	429	rate_limited	키의 분당 요청 한도를 모두 사용함.
7	429	b2b_overloaded, org_overloaded	처리 중인 동시 요청이 너무 많음.

요청 본문이 크기 제한을 초과하면 413 request_too_large가 반환됩니다. 모든 엔드포인트에서 2 MiB, /design/* 엔드포인트에서 5 MiB가 한도입니다. 요청에서 본문 길이를 선언했다면 위의 다른 검사보다 먼저 거부됩니다.

응답 본문과 처리 방법은 오류 및 할당량과 속도 제한에 나와 있습니다.

관련 문서

• 서버 빠른 시작: 단계별 첫 API 호출.
• SSE 전송 규약: 스트림에서 발생하는 모든 이벤트.
• 스트림 읽기: 완성된 클라이언트 예제.
• 데이터 라이선스: 표시해야 하는 출처 정보.