エンドポイント

Kaleidr プラットフォーム API の各公開エンドポイントを 1 節ずつ説明します。

• ベース 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 本文があり、詳細はエラーに記載しています。1 つのエンドポイントでは失敗時にも 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

公開可能キーを、呼び出し元のオリジンと 1 つの製品に紐づく短期間有効なセッショントークンに交換します。SDK はキーを使用するマウントごとに自動で交換します。独自のブラウザークライアントを作成する場合に限り、この API を直接呼び出してください。

認証： 公開可能キー。必須： 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 が未指定、または許可された 4 値以外。
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	文字列	いいえ	自動生成	会話 ID。英数字、_、.、:、- を使用した 1～128 文字。同じ安定した 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
1 件の 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 にはなりません。 レスポンスは 200 で、error 文字列を含み、action はありません：

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

プランナーが場所同士を結べない場合や、その他の理由で計画に失敗した場合に発生します。有効な座標を持つ場所が 2 件未満なら、At least two resolved places are required to build a route. というテキストが返ります。利用者向けにそのまま表示できる文面なので、文言ではなく error の有無で判定してください。直通の公共交通機関がない場合も同じ形式で返され、理由とともに reason、covered、available の 3 フィールドが追加されます。

ステータスではなくレスポンス本文で分岐してください：

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	地域も基準地点も指定されていない住所で、複数候補の 1 つ。

推定住所。 入力した番地がデータに存在しない場合、同じ側の既知の番地の間、最寄りの既知の番地、またはその番地を含む街区の番号範囲に沿って配置されます。結果には approximate: true と以下の値が含まれます。

フィールド	意味
method	"interpolated"（既知の 2 番地の間）、"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 が本製品を推奨するものではありません。	個人・企業・組織の特定や、それらによる推薦を示唆する目的で使用できません。
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 から 75 メートルを超える場所は、ヒントの内容に関係なく返されません。

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 を指定した場合は、その 1 階層のみ）。
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 も表示してください。 近くに記載するか、利用者が開ける出典欄に記載します。1 回のレスポンスには複数の情報源が混在するため、レスポンス全体への 1 件の表示では不十分です。値を保存・転送するときも、対応する license と出典情報を保持してください。

content も独自の attr を通じて同様に出典表示が必要です。live_only: true の値は現在のユーザーにのみ表示でき、保存や他者への転送は禁止されています。

各ライセンスの要件はデータライセンスを参照してください。

API が返さない情報

Kaleidr の自社アプリは API より多くの地点情報を表示します。一部のデータは外部サイトでの利用が許諾されていないためです：

• OpenStreetMap 由来で ODbL の対象となる値： 階数、高さ、分類など建物の属性。建物の概要も提供できません。
• 外部事業者からの回答： ジオコーディングサービスによる住所検索結果、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 で再度検索されるため、リクエスト内の記述がそのまま事実として採用されることはありません。指定点から 75 メートル以上離れた 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 を使用してください。非推奨エンドポイントからの移行を参照してください。

1 つの場所について、タイトル、概要、写真、リンクなどの説明コンテンツを返します。

認証： サーバーキー、セッショントークン、または旧式のキー。スコープ： 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 を使用してください。建物の概要には後継 API がありません。非推奨エンドポイントからの移行を参照してください。

1 つの場所または建物の短い文章による要約を配信します。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

「営業時間は？」など、1 つの場所に関する 1 件の質問への回答をストリーミングします。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	文字列	いいえ		照合用の独自 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。不明な値は無視されます。
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 に説明が入ります。

3 つの応答はいずれも 200 です。status を確認してください。

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

読み取り専用の 3 つのカタログ：利用可能な地図スタイル、サンプル地図、テーマパック。

認証： サーバーキー、セッショントークン、または旧式のキー。スコープ： design. 料金： なし。ただし、キーの 1 分あたりのリクエスト数に算入され、同時実行数には算入されません。

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

各レスポンスは一覧を 1 つのキーの下に格納します：

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

/design/samples は { "samples": [ … ] } を、/design/themes は { "themes": [ … ] } を返します。

---

すべてのランタイムエンドポイントに共通するエラー

2 つのセッション交換を除くすべてのエンドポイントは、固有の処理を始める前にこれらのエラーを返す場合があります。次の順に確認されます。

順序	ステータス	コード	発生条件
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 通信仕様：すべてのストリームイベント。
• ストリームの読み取り：完全なクライアント実装例。
• データライセンス：表示すべき出典情報。