地图设置指南

TrailSnap 使用地图服务来展示照片的地理位置分布（足迹地图）。为了正常使用地图功能，您需要自行申请并配置地图服务的 API Key。

为什么需要配置 API Key？

地图服务商（如天地图、高德、百度）通常要求开发者申请独立的 API Key (或 Token) 才能调用其服务。自行配置 Key 有以下好处：

1. 稳定性保障：拥有独立的每日调用配额，避免因共享 Key 达到限额而导致地图无法加载。
2. 合规与安全：符合地图服务商的使用条款，且 Key 由您自己管理，更加安全。

---

1. 天地图 (推荐)

天地图 是国家地理信息公共服务平台，数据权威、覆盖全，且对个人开发者提供较为宽裕的免费配额，是 TrailSnap 的默认及推荐地图服务商。

获取 API Key (Tk) 步骤

1. 注册账号 访问 天地图官网，点击右上角的“注册”，完成个人账号注册。如果已有账号，直接登录。

2. 进入控制台 登录后，点击页面顶部的“开发资源”，选择“控制台”，或者直接访问 天地图控制台。

3. 申请成为开发者 如果是首次使用，可能需要点击“申请成为个人开发者”并完成简单的实名认证。

4. 创建应用

   • 点击左侧菜单栏的 “应用管理”。
   • 点击 “创建新应用” 按钮。
   • 填写应用信息：
     • 应用名称：填写 TrailSnap 或任意您喜欢的名称。
     • 行业类别：根据实际情况选择（如“生活服务”）。
     • 应用类型：必须选择 “浏览器端” (因为 TrailSnap 是在浏览器前端直接加载地图)。
     • Ip白名单/域名白名单：
       • 如果您是在本地 (localhost) 使用，可以填写 * (表示不限制)。
       • 如果您部署在公网，建议填写您的域名或 IP 地址以提高安全性。

5. 获取 Key 创建成功后，您会在应用列表中看到刚才创建的应用。复制 Key 列对应的一串字符（通常称为 tk）。

6. 填入设置 回到 TrailSnap 系统：

   • 进入 设置 -> 基础设置。
   • 找到 地图配置 区域。
   • 确保地图提供商选择为 天地图 (Tianditu)。
   • 将复制的 Key 粘贴到 API Key 输入框中。
   • 点击保存。

7. 获取多个 Key 并配置

   • 天地图允许您为不同的应用或场景创建多个 Key，每个 Key 有独立的调用配额。
   • 防止调用次数过多，您可以在 TrailSnap 中配置多个 Key，系统会随机选择一个用于加载地图。
   • 这在您需要在不同环境（如本地开发、测试环境、生产环境）使用不同 Key 时非常有用。

---

2. 高德地图 (Amap)

注意：TrailSnap 目前主要支持天地图。高德地图的支持正在开发中，配置后可能暂不生效或仅部分功能可用。

获取 API Key 步骤

1. 注册开发者 访问 高德开放平台，注册账号并完成开发者认证（个人开发者即可）。

2. 创建应用

   • 进入 应用管理 -> 我的应用。
   • 点击 创建新应用，输入名称（如 TrailSnap）和类型（如 工具）。

3. 添加 Key

   • 在刚才创建的应用下，点击 添加 Key。
   • 服务平台：选择 Web端 (JSAPI)。
   • 域名白名单：本地测试可不填，线上部署请填写域名。
   • 勾选同意协议并提交。

4. 获取 Key 复制生成的 Key。注意：高德地图 JSAPI 2.0 可能还需要配置安全密钥 (jscode)，目前 TrailSnap 暂未通过界面支持配置安全密钥，建议优先使用天地图。

---

3. 百度地图 (Baidu)

注意：百度地图的支持正在规划中。

获取 API Key (AK) 步骤

1. 注册开发者 访问 百度地图开放平台，注册并认证。

2. 创建应用

   • 进入 应用管理 -> 我的应用。
   • 点击 创建应用。

3. 配置应用

   • 应用类型：选择 浏览器端。
   • Referer白名单：填写 * (本地测试) 或您的域名。
   • 启用服务：默认全选即可。

4. 获取 AK 提交后，列表中的 访问应用（AK） 即为 API Key。

---

4. 离线地图数据 (Offline Map Data)

TrailSnap 支持离线反向地理编码功能，即使在没有网络连接的情况下，也能根据照片的 GPS 坐标解析出所在的城市和地区。该功能依赖于离线城市数据文件。

功能说明

在 设置 -> 基础设置 -> 地图配置 下方，您可以找到 离线地图数据 管理区域。

下载国家数据

1. 在 下载国家数据 区域，从下拉框中选择您需要的国家（例如“China”）。
2. 点击 下载 按钮。
3. 系统将在后台自动下载该国的城市数据并进行处理。下载完成后，该国的数据将显示在下方的 已下载数据 列表中。

上传自定义数据

如果您无法通过系统直接下载，或者有自定义的城市数据文件，可以通过此功能手动上传。

1. 准备 CSV 格式的城市数据文件。文件必须包含以下表头字段：
   • longitude: 经度
   • latitude: 纬度
   • country: 国家代码 (如 CN, US)
   • admin_1: 一级行政区 (如 省/州)
   • admin_2: 二级行政区 (如 市)
   • admin_3: 三级行政区 (如 区/县)
   • admin_4: 四级行政区 (可选)
2. 点击 点击上传 CSV 文件 按钮，选择您的文件。
3. 上传成功后，数据将立即生效并显示在列表中。

管理已下载数据

在 已下载数据 列表中，您可以：

• 查看当前已安装的所有国家/地区数据。
• 点击文件名旁边的 下载图标，将服务器上的 CSV 数据文件下载到本地电脑进行备份或查看。

---

常见问题

Q: 地图加载显示空白或网格？ A:

1. 请检查 API Key 是否正确复制，注意不要带有空格。
2. 确认申请 Key 时选择的应用类型是否正确（天地图必须是浏览器端）。
3. 如果设置了白名单，请确认当前的访问地址（如 localhost 或 127.0.0.1）是否在白名单内。

Q: 天地图配额不够用怎么办？ A: 个人开发者的免费配额通常足以满足个人相册的日常浏览需求。如果确实超限，可以考虑注册多个账号或升级企业认证。

Q: 离线地图数据下载失败？ A: 可能是由于网络连接问题导致无法连接到数据源 (GeoNames)。您可以尝试稍后重试，或者手动下载数据并使用“上传自定义数据”功能进行导入。