# 如何使用API搜索附近的交通站点？

> 了解如何使用ROOTE API进行附近站点搜索：坐标、半径、JavaScript示例、结果读取及错误处理。

Source: https://www.roote.ai/zh/guides/remen-zhao-ji-fu-jin-de-jiao-tong-zhan-dian-yong-api-sou-suo/
Language: zh
Author: ROOTE

要搜索某点附近的站点，需向邻近API传递该点的纬度、经度和搜索半径。然后检查响应状态、返回的实体和覆盖信息，之后显示列表或地图。

在ROOTE协议 roote-1.0.0 中，GET /v1/transit/nearby 路由用于发现附近的交通场所。它不获取实时发车信息或警示。场所搜索与下一班车搜索是两个独立操作。

## 定义参数

请求使用 lat 表示纬度，lng 表示经度。协议中也描述了别名 lon。参数 radius 表示搜索半径（米），limit 限制返回结果数量。filter modes 用于指定交通方式。

| 参数 | 示例 | 含义 |
| --- | --- | --- |
| lat | 44.8378 | 搜索点纬度 |
| lng | -0.5792 | 搜索点经度 |
| radius | 600 | 请求的半径（米） |
| limit | 10 | 请求的结果数量限制 |
| modes | bus,tram | 搜索的交通方式 |

这些坐标为波尔多的搜索示例，不保证对应某一具体站点。请参阅 [ROOTE OpenAPI 协议](https://api.roote.ai/openapi.json) 了解当前的边界、字段及条件。

## 在服务器端发送首次请求

以下为Node.js环境中使用fetch的JavaScript示例。令牌（若使用）存放于服务器环境变量中。示例无需在浏览器暴露秘密。

```
async function rechercherArrets(token = process.env.ROOTE_API_TOKEN) {
  const url = new URL('https://api.roote.ai/v1/transit/nearby');
  url.search = new URLSearchParams({
    lat: '44.8378',
    lng: '-0.5792',
    radius: '600',
    limit: '10',
    modes: 'bus,tram'
  }).toString();

  const headers = { Accept: 'application/json' };
  if (token) headers.Authorization = `Bearer ${token}`;

  const response = await fetch(url, {
    headers,
    signal: AbortSignal.timeout(10000)
  });
  if (!response.ok) {
    throw new Error(`Erreur HTTP ${response.status}`);
  }

  const data = await response.json();
  if (data.contract_version !== 'roote-1.0.0') {
    throw new Error('Version du contrat non reconnue');
  }
  if (!['success', 'empty', 'partial'].includes(data.status)) {
    throw new Error('Recherche indisponible');
  }
  if (!Array.isArray(data.stations)) {
    throw new Error('Réponse sans collection stations valide');
  }

  return {
    status: data.status,
    stations: data.stations,
    lines: data.lines,
    operators: data.operators,
    coverage: data.coverage,
    warnings: data.warnings,
    attributions: data.attributions,
    meta: data.meta
  };
}
```

所使用的协议允许匿名或令牌访问，具体依适用策略。请核实您的访问权限及限制。HTTP响应正确不代表内容有效；生产环境中应使用对象模式验证。

## 读取实体及其关系

stations 集合包含返回的场所。请重点查看 id、name、entity_kind、location 和 distance_meters。line_ids 和 operator_ids 用于关联 lines 和 operators 集合（如有提供）。

将地理距离按原样显示，不要未经路径计算将其转换为步行时间。指南 [找附近的站点](https://www.roote.ai/zh/guides/zui-jin-de-gong-jiao-zhan-he-tie-lu-che-zhan/) 解释了访问方式如何影响实际行程。

也要明确处理未知信息。协议中 accessibility.wheelchair 可能为 unknown：此值既非 yes 也非 no。公布的发车能力不等同于发车列表。

## 显示列表或地图

使用id稳定界面元素，用名称作为标签，location 表示位置。通过引用关联线路，而非类似名称匹配。

若显示线路颜色或标签，视为外部输入须验证。对于名称，请使用文本而非注入HTML。

保留来源署名，显示协议要求的署名。

## 处理空结果、部分响应和错误

empty 状态表示在已知范围内无搜索结果，但不证明不存在公共交通。partial 可能包含有用场所并提示限制：应展示结果及对应警告。

读取 coverage、warnings 和 meta 中的限制。结果被截断不代表覆盖完整。网络或HTTP错误时，显示不可用，而非“无站点”。

遇到429状态码，请参考恢复建议及服务可能的响应头。避免循环重试。

## 区分站点、区域和月台

entity_kind 字段区分不同级别地点。邻近结果可能是不同月台；相似名称可能来自不同来源。

不要仅凭位置自动合并地点。使用服务记录的关系和身份。我们的指南 [GTFS、GTFS-RT 和 GBFS](https://www.roote.ai/zh/guides/gtfs-gtfs-rt-et-gbfs-quelles-differences/) 说明数据的上下文。

## 准备生产环境集成

当位置或过滤条件有意义变化时触发搜索。合并相同请求，设定超时，并根据数据类型及服务条件调整缓存。

地点列表和实时可用性对数据新鲜度要求不同。在向用户展示前，使用完整、空、部分和错误响应验证流程。

## 将搜索范围扩展到城市服务

公交站点和城市服务使用不同的接口路径。要在同一地点附近搜索厕所，GET /v1/services/nearby 路径需要传入 lat 和 lon 参数，并设置 types=toilets。不要向此接口传递 modes=toilets：该词汇属于地图 URL，而非服务过滤器。

下面的 JavaScript 示例构造了一个服务类 URL，搜索半径为600米，但并未触发请求；请复用上文描述的 HTTP 及契约验证控件。预期返回集合变为 services 而非 stations，保留 service_type、location、distance_meters 及实际存在的属性。

REST 接口契约文档中包含 toilets、drinking_water、fountain、wifi、parking、charging、aed 和 locker 等类型。MCP 提供的类型可能有所不同。有关可接受参数、边界值及访问限制，请参阅所使用接口的模式定义。

服务的属性并不保证服务在查询时刻开放。未知的可访问性不等同于服务不可用；错误返回的空列表也不代表没有厕所。请保持各类数据的完整性，而非简化为仅含名称和坐标。

对于组合地图，应将结果与其所属类别及标识符关联。显示服务错误信息时，不要删除 Transit 返回的站点信息。搜索仍以同一点为中心，但状态和覆盖范围可能不同。

```
const url = new URL('https://api.roote.ai/v1/services/nearby');
url.search = new URLSearchParams({
  lat: '44.8416106', lon: '-0.5810938',
  radius: '600', limit: '10', types: 'toilets'
}).toString();
console.log(url.toString());
```

[诊断空搜索结果或发生错误](https://www.roote.ai/zh/guides/api-no-result-vs-error-chinese/)

[直接在网站内嵌入过滤后的地图](https://www.roote.ai/zh/guides/ru-he-zhong-de-yidong-huaban-yinru-zhi-fang-fa/)

[围绕这些搜索功能构建助手](https://www.roote.ai/zh/guides/create-mobility-assistant-around-address/)

## 常见问题

### Nearby 是否提供下一班车？

本协议中无。此路径用于发现交通场所，发车信息需另行能力支持。

### 错误后能展示空列表吗？

应展示不可用状态。错误不表明无站点。

### API令牌可放浏览器端吗？

秘密应保存在服务器端。请使用适合应用及账户的访问模式。