地圖 SDK 與地圖 API 的差別在於所有權劃分，而非產品選擇。地圖 SDK 打包了可重複使用的用戶端元件、生命週期管理和瀏覽器身分驗證。地圖 API 透過程式化請求公開空間服務。地圖平台則提供客戶端和服務調用，以及身分驗證、資料、分析、使用控制和支援功能。大多數生產環境的地圖產品都使用多個圖層。
以下各節將分別介紹這三個圖層，分配所有權，並根據 Kaleidr 目前的公開開發者頁面對其進行文件化。相關閱讀包括什麼是AI地圖SDK？ 、無程式碼地圖建構器 vs 地圖API、地圖API認證和什麼是位置智慧API？。已選定實現方案的團隊可直接跳至Kaleidr映射部分；仍在命名圖層的團隊應先參考對比表。
對比要點
- 先命名作業，再命名圖層： SDK負責客戶端行為；API負責服務契約；平台負責共用作業。
- 不要將這些條款視為對立關係： 生產產品通常會同時使用 SDK、API 和平台控制。
- **維持主機規則的權威性：**身分、租用戶權限、私有記錄和交易都保留在主機應用程式中。
- **依運行時拆分憑證：**瀏覽器安全可發布金鑰和伺服器金鑰屬於不同的威脅模型。
- 確認現行合約： Kaleidr 開發人員文件目前描述了
kaleidr.js產品、平台 API 系列和金鑰範圍；行銷文案並非 API 合約。
地圖 SDK 與地圖 API 和地圖平台有何不同？
區分它們的關鍵在於每個圖層執行的任務。地圖 SDK 存在於客戶端，並打包了可重複使用的行為：元件、掛載生命週期、地圖附件、事件和瀏覽器安全的會話處理。地圖 API 是空間功能的程式設計契約，例如搜尋、路徑規劃、檢索、推理、切片或設計。地圖平台是一個更廣泛的系統，可以包含地圖 SDK 和地圖 API，以及身分驗證、資料服務、工具、分析、發布、配額和支援等功能。AWS 目前將 SDK 定義為一組特定於平台的建置工具（例如程式庫），而 API 是一種使兩個軟體元件能夠使用預定協定進行通訊的機制，並指出 SDK 可能包含 API 以及其他資源（SDK 和 API 有什麼區別？）。
各供應商平台在公開文件中採用相同的分層結構。Google目前將 Google Maps Platform 描述為一套 API 和 SDK，開發者可以使用它將地圖嵌入到應用程式和網頁中，或從 Google Maps 取得資料（Google Maps Platform 常見問題解答）。同一供應商目前將這些能力依平台拆分為獨立的 API 系列發布（Google Maps Platform API 平台）。Mapbox 目前將其描述為一個模組化的位置平台，由 API、SDK 和工具組成，開發者可以組合使用這些工具來創建自訂位置體驗（入門指南）。這些頁面權威地說明了各供應商如何命名自己的技術堆疊。但這些頁面並不能證明每個產品都必須購買完整的平台才能進行單一地理編碼。
| 問題 | 地圖 SDK | 地圖 API | 地圖平台 |
|---|---|---|---|
| 主要任務 | 增加可重複使用的客戶行為 | 以程式設計方式存取服務 | 提供完整的空間產品堆疊 |
| 典型運行時 | 瀏覽器、行動裝置或應用程式用戶端 | 應用層或客戶端（如允許） | 用戶端、應用層和操作工具 |
| 整合方式 | 庫、元件、載入器或套件 | HTTP 或其他服務請求 | SDK、API、工具、身分驗證、資料和分析的組合 |
| 最適合 | 使用者介面、地圖生命週期、嵌入、交互 | 搜尋、路由、推理、資料檢索 | 需要多種空間功能的產品 |
| 主要所有權 | 客戶端集成 | 服務合約 | 端對端平台功能 |
| 身分驗證 | 通常使用瀏覽器安全性金鑰或會話 | 通常使用伺服器金鑰或作用域權杖 | 金鑰管理、作用域、配額與組織控制 |
| 是否包含使用者介面？ | 通常包含 | 通常不包含 | 可能包含 SDK 使用者介面以及 API 和工具 |
| 是否替換宿主應用程式？ | 否 | 否 | 否；它提供基礎架構和建置模組 |
什麼是地圖 SDK？
軟體開發工具包 (SDK) 將開發人員可以直接在應用程式中使用的程式碼打包在一起。對於地圖應用程式來說，該工具包通常包含地圖元件、渲染器適配器、控制項、生命週期管理、瀏覽器安全性認證、事件處理、結構化操作、嵌入式檢視器或編輯器以及錯誤規範化。SDK 通常比原始服務呼叫更接近使用者介面，因此當任務是「將此功能新增至我們現有的畫面」時，團隊會選擇使用 SDK。
Web 平台使這種打包方式更加具體。MDN 目前將自訂元素描述為開發人員定義的 HTML 元素，用於擴充瀏覽器中可用的元素集（使用自訂元素）。安裝自訂元素的地圖 SDK 正是遵循瀏覽器的這種約定：宿主頁面聲明或掛載元件，而 SDK 則負責版本控制、套件載入和生命週期管理。Kaleidr 目前將 kaleidr.js 記錄為輕量級載入器，它安裝 window.Kaleidr 和 <kaleidr-map> 元素，延遲載入產品包，並擁有版本控制、設定、金鑰傳遞、掛載生命週期和錯誤規範化（kaleidr.js — 載入器。
SDK 不會取代宿主應用程式。宿主應用程式仍然擁有身分、租用戶權限、私有資料和業務流程。在 AI 領域，這一界限依然存在：SDK 將意圖、結構化地點和地圖操作連接到即時渲染器，但不會成為庫存或資格的權威來源。
什麼是地圖 API？
地圖 API 透過定義的程序化契約公開功能。典型的 API 包括地點搜尋、地理編碼、路徑規劃、行程時間計算、瓦片請求、靜態地圖生成、空間推理、資料集管理和地圖設計操作。API 通常不會決定結果在介面中的顯示方式，而是由宿主應用程式決定。
請求模型是普通的 Web 架構。MDN 目前將 Fetch API 描述為使用 Request 和 Response 物件跨網路取得資源的介面（Fetch API）。地圖 API 呼叫是將這種模式應用於空間工作：應用程式發送結構化請求，接收結構化回應或串流，然後決定渲染什麼。Kaleidr 目前將平台 API 路由放在 https://api.kaleidr.com/inference-api/b2b/v1/ 下，並在公共端點參考 (Endpoints) 中記錄聊天、路由、POI 增強、SDK 會話交換和設計系列。確切的路徑清單可能會有所變化，因此實作應使用當前的開發者參考，而不是部落格範例作為權威來源。
當需要沒有預先建構介面的服務回應時，應先選擇 API 層：檢索地點上下文、呼叫推理服務、計算路線、增強興趣點、運行設計操作或在私有記錄旁邊協調這些呼叫。權衡取捨顯而易見。應用程式需要編寫更多整合程式碼，包括憑證、重試、錯誤處理以及（如果適用）流處理。
什麼是地圖平台？
地圖平台圍繞著一個通用的帳戶、資料、安全性和營運模型，整合了多個建置模組。SDK 和 API 可以出現在該模型中，但其關鍵特徵在於覆蓋面廣且共享基礎設施：渲染、搜尋、路線規劃、地點資料、圖塊、地圖設計、身分驗證、使用控制、分析、發布和支援。Google的常見問題解答目前將Google地圖平台定義為 API 和 SDK 的結合使用，而不是單一的端點。Mapbox 目前將相同的概念拆分為地圖、搜尋、導航、資料產品和工具（例如 Mapbox Studio）。
當多個相互關聯的問題同時重要時，平台的價值就體現出來了：瀏覽器身分驗證和應用層身分驗證、地圖使用者介面、圖塊、編輯器、推理、分析和使用控制。單一地理編碼或單一靜態地圖不需要如此龐大的營運介面。無程式碼建構器可以作為平台的介面，而無需構成完整的平台，而功能較窄的 API 仍然可以是一個合適的起點。
Kaleidr 目前將開發者引入描述為一個組織級關鍵系統，其功能範圍涵蓋人工智慧、地圖和設計，並提供可發布和伺服器兩種形式（使用 Kaleidr 構建）。Kaleidr Enterprise 目前將此商業堆疊定位為針對現有產品堆疊構建的空間智能，提供 SDK、推理 API、排名、分析和部署支援（位置智能 API 和地圖 SDK）。在依賴特定生產工作流程之前，請在定價與計畫上確認目前計畫的權限。
哪一層應該負責哪些職責？
清晰的整合始於確定哪一層負責哪些職責。宿主應用程式應保持對身分、租用戶權限、客戶狀態、私人資料、事務和特定於產品的工作流程的權威性。SDK 可以負責掛載、可重複使用介面行為、地圖附件、瀏覽器會話處理和元件生命週期。API 可能擁有推理、路線計算、地點豐富、設計操作和其他服務回應。平台可能擁有憑證、範圍、配額、產品存取權限、基礎設施、支援和共享計費。跨越這些界限會導致私有授權洩漏到元件中，或者語言模型回應被視為預訂帳簿。
私有記錄通常會將編排推入應用層。清單、庫存、客戶記錄、營運資產和受保護的業務規則應在主機中進行授權，然後最小化的結果才能到達地圖。瀏覽器 SDK 仍然可以呈現結果。地圖組件不應成為授權服務。用於 AI 地圖工作流程的私人位置資料涵蓋了這些記錄的最小化。多租戶 SaaS 產品增加了另一個邊界：平台金鑰用於向提供者驗證 SaaS 組織的身分；它並不能取代主機關於哪些客戶可以看到哪些地圖或哪些私有行的決定。
團隊何時應該選擇 SDK、API 或平台？
首先選擇滿足產品需求的最淺層集成，然後僅在控製或編排需要時才進行更深入的集成。如果任務是顯示已設計的地圖，則發布地圖或檢視器嵌入就足夠了。如果任務是將聊天、編輯器或圖塊附加到主機介面，則 SDK 元件就足夠了。當應用層必須擁有請求建置、私有資料連線或自訂 UI 時，平台 API 是適當的下一步。企業整合是一種治理和營運選擇，而不是取代當前渲染器的必要條件。
當 Web 應用需要快速取得受支援的地圖功能、現有元件行為符合要求且瀏覽器整合合適時，應優先選擇 SDK。當服務回應屬於應用層、介面為自訂介面或私有資料編排占主導地位時，應優先選擇 API。當多個空間功能、共享身分驗證、使用情況、分析和企業支援對跨團隊都至關重要時，應優先選擇平台。當首要問題是地圖創作和發布而非應用程式程式碼時，應優先使用 Studio；Kaleidr Studio 目前提供了該創作路徑的文件。這些路徑以後可以匯合，而無需強制重寫宿主地圖。
Kaleidr 如何映射到這些層？
Kaleidr 目前公開了 JavaScript SDK 層和平台 API 層，而企業版則提供了更廣泛的商業和營運介面。目前的開發者快速入門指南使用位於 https://cdn.kaleidr.com/embed/v1/kaleidr.js 的單一版本載入器。此載入器可掛載 chat、viewer、editor 和 tile 的產品包。聊天功能目前會附加到 Mapbox、MapLibre、Google Maps 或 Leaflet 的即時主機實例，而不是取代渲染器（快速入門）。如何將 AI 聊天加入 Mapbox、Google Maps 和 MapLibre 提供了實際操作的附加方法。如何嵌入互動式地圖 介紹了已發布地圖的嵌入方法。
| 圖層 | Kaleidr 範例 | 典型用法 |
|---|---|---|
| SDK | kaleidr.js、<kaleidr-map>、Kaleidr.mount() |
新增聊天、檢視器、編輯器或圖塊行為 |
| API | 平台 API 端點系列 | 調用推理、路由、檢索或設計服務 |
| 平台 | Kaleidr Enterprise 及開發者堆疊 | 管理功能、密鑰、範圍、使用情況、支援和集成 |
| 創作工具 | Kaleidr Studio | 無需從代碼開始即可創建和發布品牌地圖 |
| 分析圖層 | Kaleidr Analytics | 測量地圖與地點互動 |
產品包並非同一組件的互換名稱。檢視器用於顯示已發布的地圖。聊天功能用於在即時主機地圖上進行地圖感知對話式互動。編輯器用於嵌入地圖創作功能；地圖編輯器 SDK涵蓋了此 SaaS 場景。圖塊用於使用預設的底圖樣式。請根據產品用途進行選擇。技術細節的更新速度也比頁面定位更快。目前的開發者快速入門指南和 kaleidr.js 參考文件指出，已發佈的檢視器使用共用 ID，無需金鑰。在實施過程中，請以開發者文件為準。
SDK 和 API 的身分驗證有何不同？
瀏覽器整合和應用層整合具有不同的威脅模型。任何發送到瀏覽器的內容通常都可以被檢查，因此長期有效的伺服器金鑰不應出現在頁面原始碼、用戶端套件或公共儲存庫中。Kaleidr 目前使用可發布密鑰供瀏覽器 SDK 使用；SDK 會將其交換為短期的、綁定到來源的會話。伺服器金鑰用於受信任的應用層，可以作為 bearer 或 X-Api-Key 發送。目前的身分驗證參考文件指出，直接作為 bearer 提供的可發布密鑰將被拒絕，伺服器密鑰無法獲得 CORS 授權，並且 SDK 在掛載時會拒絕伺服器密鑰，使其保留在伺服器端（身分驗證和範圍）。
SDK 可以隱藏通用瀏覽器路徑。目前的端點參考文件將 POST /sdk/sessions 指定為接受可發佈金鑰的交換器，並指出 SDK 會在常規瀏覽器整合中掛載時呼叫該交換器（端點）。如果沒有 SDK，應用程式需要處理來源驗證、產品選擇、範圍檢查、短期會話交換以及產品包生命週期管理。當主機必須控制請求建構、串流、重試和私有資料授權時，直接使用 API 仍然是合適的。Kaleidr 目前能夠區分缺失或無效的憑證與範圍不足的有效憑證，並記錄了單獨的速率限制條件。應用程式日誌應保留這種區分，而不是將所有失敗合併為「映射失敗」。
團隊應避免哪些錯誤？
反覆出現的錯誤是將相鄰用語視為替代品。SDK 與 API 並非二選一的關係。SDK 通常會在後台呼叫平台 API； SDK 是一個更高層級的開發者介面，並不代表不存在服務合約。API 並不需要從頭開始建立每個介面；許多產品使用 SDK 來建立使用者介面，並使用 API 來進行應用層編排。平台也不需要取代現有的地圖堆疊。 Kaleidr 目前已提供將聊天功能附加到現有受支援地圖的文件，而 Enterprise 目前也圍繞現有產品堆疊建立商業方案。
| 錯誤 | 結果 | 更佳方案 |
|---|---|---|
| 將 SDK 和 API 視為互斥 | 架構變得人為 | 在適當的層級使用它們 |
| 假設 SDK 擁有業務邏輯 | 產品邊界模糊 | 維持主機規則的權威性 |
| 在瀏覽器中放置伺服器金鑰 | 憑證洩露 | 使用可發布的 SDK 身分驗證 |
| 直接呼叫 API 以滿足標準 UI 需求 | 需要維護更多客戶端程式碼 | 在適當的情況下使用 SDK |
| 將 SDK 用於私有授權 | 租戶與資料風險 | 在主機應用程式中進行授權 |
| 假設平台取代現有平台地圖 | 遷移成本上升 | 在支援的情況下附加 |
| 將行銷頁面視為 API 合約 | 技術不匹配 | 優先使用最新的開發者文件 |
| 為了一個微不足道的需求而採用整個平台 | 過度複雜 | 從最窄的層開始 |
團隊應該如何開始整合？
選擇與任務相符的圖層，然後僅在所有權需要時才添加深度。使用 SDK 實作可重複使用的用戶端行為，使用 API 實作服務級控制，並使用平台實現共享的空間基礎架構。Kaleidr 目前嚴格遵循此模型：kaleidr.js 提供輕量級的瀏覽器整合層，平台 API 公開了已記錄的推理和設計服務，而 Kaleidr Enterprise 則為建立空間產品的團隊提供更廣泛的商業技術堆疊。閱讀 Kaleidr 開發者文件 以了解目前的載入器、驗證和端點協定。探索 Kaleidr Enterprise 了解目前公開頁面上所述的 SDK、推理 API、位置智慧和部署支援。
常見問題解答
地圖 SDK 和地圖 API 有什麼不同？
地圖 SDK 是可重複使用的用戶端程式碼，可協助開發人員將地圖功能整合到應用程式中，包括使用者介面、生命週期管理以及瀏覽器身分驗證（通常）。地圖 API 是一種程式設計介面，用於請求特定的地圖或空間服務。許多產品同時使用兩者。
地圖 SDK 只是 API 的封裝嗎？
有時是，但並非總是如此。SDK 還可以管理使用者介面元件、地圖生命週期管理、瀏覽器驗證、提供者適配器、事件和錯誤處理。AWS 目前指出，SDK 可能包含 API 以及其他資源。
什麼是地圖平台？
地圖平台是指用於建立位置感知產品的更廣泛的 SDK、API、資料、渲染、身分驗證、工具、分析、發布、配額和營運服務的集合。Google 和 Mapbox 目前都用這些術語來描述他們的商業技術堆疊。
團隊應該使用 SDK 還是 API？
當受支援的用戶端元件與產品相符時，請使用 SDK。當主機需要直接的服務級控製或應用層編排時，請使用 API。許多產品同時使用這兩種方式。
SDK 是否會取代地圖渲染器？
不一定。Kaleidr Chat 目前支援將配件附加到現有的 Mapbox、MapLibre、Google Maps 或 Leaflet 地圖。其他 SDK 產品（例如 Viewer 或 Editor）具有不同的渲染器所有權模型。
何時應在應用層進行 API 呼叫？
當請求涉及伺服器憑證、私有資料、租用戶授權或不應暴露給瀏覽器的業務邏輯時，請使用應用程式層。
平台和無程式碼地圖建構器之間有什麼區別？
無程式碼建構器專注於創作和發布。一個平台可以包含建構器，以及 SDK、API、身分驗證、資料服務、分析和企業控制。
Kaleidr 目前如何公開其 SDK 和 API？
Kaleidr 目前使用版本化的 kaleidr.js 載入器，該載入器會安裝 window.Kaleidr 和 <kaleidr-map>，其中包含聊天、檢視器、編輯器和圖塊的產品包。目前的公共平台 API 文件在其 B2B 推理 API 基本 URL 下記錄了聊天、路由、POI 增強、SDK 會話交換和設計系列。
Kaleidr Viewer 是否需要可發佈的密鑰？
目前的開發者快速入門指南和 kaleidr.js 參考文件指出，已發布的 Viewer 使用共享 ID，無需金鑰。
Kaleidr 能否與現有地圖堆疊配合使用？
Kaleidr 目前的文件中介紹瞭如何將聊天功能附加到受支援的即時主機地圖，而 Kaleidr Enterprise 目前將其定位為專為現有堆疊構建的空間智慧解決方案。替換目前的地圖提供者並非其核心定位。
參考資料
- Amazon Web Services。《SDK 和 API 的差別是什麼？》。瀏覽日期：2026 年 9 月 3 日。 https://aws.amazon.com/compare/the-difference-between-sdk-and-api/
- Google Maps Platform。《Google Maps Platform 常見問題》。瀏覽日期：2026 年 9 月 3 日。 https://developers.google.com/maps/faq
- Google Maps Platform。《Google Maps Platform API 平台》。訪問日期：2026年9月3日。 https://developers.google.com/maps/apis-by-platform
- Mapbox。「入門指南」。訪問日期：2026年9月3日。 https://docs.mapbox.com/help/getting-started/
- MDN。“使用自訂元素”。訪問日期：2026年9月3日。 https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_custom_elements
- MDN。「Fetch API」。訪問日期：2026年9月3日。 https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API
- Kaleidr。「使用 Kaleidr 建造」。開發者文件。訪問日期：2026年9月3日。 https://docs.kaleidr.com/
- Kaleidr。「快速入門」。開發者文件。訪問日期：2026年9月3日。https://docs.kaleidr.com/quickstart
- Kaleidr。「kaleidr.js — 載入器」。開發者文件。瀏覽日期：2026 年 9 月 3 日。https://docs.kaleidr.com/sdk/kaleidr-js
- Kaleidr. 身分驗證和範圍。開發者文件。瀏覽日期：2026 年 9 月 3 日。https://docs.kaleidr.com/platform-api/auth-and-scopes
- Kaleidr. 端點。開發者文件。瀏覽日期：2026 年 9 月 3 日。https://docs.kaleidr.com/platform-api/endpoints
- Kaleidr. 位置智慧 API 和地圖 SDK。瀏覽日期：2026 年 9 月 3 日。 https://kaleidr.com/enterprise
@misc{aws_sdk_api_difference_2026_09_03,
title = {What's the Difference Between SDK and API?},
author = {{Amazon Web Services}},
note = {Accessed 3 September 2026},
url = {https://aws.amazon.com/compare/the-difference-between-sdk-and-api/}
}
@misc{google_maps_platform_faq_2026_09_03,
title = {Google Maps Platform FAQ},
author = {{Google Maps Platform}},
note = {Accessed 3 September 2026},
url = {https://developers.google.com/maps/faq}
}
@misc{google_maps_apis_by_platform_2026_09_03,
title = {Google Maps Platform APIs by Platform},
author = {{Google Maps Platform}},
note = {Accessed 3 September 2026},
url = {https://developers.google.com/maps/apis-by-platform}
}
@misc{mapbox_getting_started_2026_09_03,
title = {Getting Started},
author = {{Mapbox}},
note = {Accessed 3 September 2026},
url = {https://docs.mapbox.com/help/getting-started/}
}
@misc{mdn_using_custom_elements_2026_09_03,
title = {Using custom elements},
author = {{MDN}},
note = {Accessed 3 September 2026},
url = {https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_custom_elements}
}
@misc{mdn_fetch_api_2026_09_03,
title = {Fetch API},
author = {{MDN}},
note = {Accessed 3 September 2026},
url = {https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API}
}
@misc{kaleidr_docs_intro_2026_09_03,
title = {Build with Kaleidr},
author = {{Kaleidr}},
note = {Developer documentation; accessed 3 September 2026},
url = {https://docs.kaleidr.com/}
}
@misc{kaleidr_quickstart_2026_09_03,
title = {Quickstart},
author = {{Kaleidr}},
note = {Developer documentation; accessed 3 September 2026},
url = {https://docs.kaleidr.com/quickstart}
}
@misc{kaleidr_js_loader_2026_09_03,
title = {kaleidr.js -- the Loader},
author = {{Kaleidr}},
note = {Developer documentation; accessed 3 September 2026},
url = {https://docs.kaleidr.com/sdk/kaleidr-js}
}
@misc{kaleidr_auth_scopes_2026_09_03,
title = {Auth \& scopes},
author = {{Kaleidr}},
note = {Developer documentation; accessed 3 September 2026},
url = {https://docs.kaleidr.com/platform-api/auth-and-scopes}
}
@misc{kaleidr_endpoints_2026_09_03,
title = {Endpoints},
author = {{Kaleidr}},
note = {Developer documentation; accessed 3 September 2026},
url = {https://docs.kaleidr.com/platform-api/endpoints}
}
@misc{kaleidr_enterprise_2026_09_03,
title = {Location Intelligence APIs and Map SDK},
author = {{Kaleidr}},
note = {Accessed 3 September 2026},
url = {https://kaleidr.com/enterprise}
}