要搜索某点附近的站点，需向邻近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 协议 了解当前的边界、字段及条件。
查找您身边的站点。
探索某城市或您位置周围登记的站点。查看详情验证交通方式及可用信息。
在服务器端发送首次请求
以下为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 集合（如有提供）。
将地理距离按原样显示，不要未经路径计算将其转换为步行时间。指南 找附近的站点 解释了访问方式如何影响实际行程。
也要明确处理未知信息。协议中 accessibility.wheelchair 可能为 unknown：此值既非 yes 也非 no。公布的发车能力不等同于发车列表。
显示列表或地图
使用id稳定界面元素，用名称作为标签，location 表示位置。通过引用关联线路，而非类似名称匹配。
若显示线路颜色或标签，视为外部输入须验证。对于名称，请使用文本而非注入HTML。
保留来源署名，显示协议要求的署名。
处理空结果、部分响应和错误
empty 状态表示在已知范围内无搜索结果，但不证明不存在公共交通。partial 可能包含有用场所并提示限制：应展示结果及对应警告。
读取 coverage、warnings 和 meta 中的限制。结果被截断不代表覆盖完整。网络或HTTP错误时，显示不可用，而非“无站点”。
遇到429状态码，请参考恢复建议及服务可能的响应头。避免循环重试。
区分站点、区域和月台
entity_kind 字段区分不同级别地点。邻近结果可能是不同月台；相似名称可能来自不同来源。
不要仅凭位置自动合并地点。使用服务记录的关系和身份。我们的指南 GTFS、GTFS-RT 和 GBFS 说明数据的上下文。
准备生产环境集成
当位置或过滤条件有意义变化时触发搜索。合并相同请求，设定超时，并根据数据类型及服务条件调整缓存。
地点列表和实时可用性对数据新鲜度要求不同。在向用户展示前，使用完整、空、部分和错误响应验证流程。
将搜索范围扩展到城市服务
公交站点和城市服务使用不同的接口路径。要在同一地点附近搜索厕所，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());常见问题
Nearby 是否提供下一班车？
本协议中无。此路径用于发现交通场所，发车信息需另行能力支持。
错误后能展示空列表吗？
应展示不可用状态。错误不表明无站点。
API令牌可放浏览器端吗？
秘密应保存在服务器端。请使用适合应用及账户的访问模式。