地图 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 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 可以出现在该模型中，但其关键特征在于覆盖面广且共享基础设施：渲染、搜索、路线规划、地点数据、图块、地图设计、身份验证、使用控制、分析、发布和支持。谷歌的常见问题解答目前将谷歌地图平台定义为 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}
}