\### 接口概览

本接口用于查询城际之间的出行路线信息，包括路线、距离、耗时、油费、过桥费、总费用及路况等详细数据。



\### 请求地址

`https://api.pearapi.ai/api/citytravelroutes/`



\### 请求方式

GET



\### 返回格式

JSON



\### 权限/付费要求

免费接口，无需付费或特殊权限。



\### 请求参数说明



| 参数名 | 是否必填 | 用途 |

| :--- | :--- | :--- |

| from | 是 | 出发地，例如“广州” |

| to | 是 | 目的地，例如“深圳” |



\### 默认请求示例

```json

{

&#x20;   "from": "广州",

&#x20;   "to": "深圳"

}

```

对应的实际请求 URL 示例为：`https://api.pearapi.ai/api/citytravelroutes/?from=广州\&to=深圳`



\### 返回字段说明



| 字段路径 | 类型 | 说明 |

| :--- | :--- | :--- |

| code | integer | 状态码 |

| msg | string | 状态信息 |

| from | string | 出发地 |

| to | string | 目的地 |

| data | string | 返回内容（可能包含路线列表或详细信息的字符串） |

| corese | string | 路线描述 |

| distance | string | 总距离 |

| time | string | 总耗时 |

| fuelcosts | string | 油费 |

| bridgetoll | string | 过桥费 |

| totalcost | string | 总费用 |

| roadconditions | string | 路况 |



\### 返回示例

原始接口配置中未提供返回示例（`example\_result` 字段为空），因此无法提供。请在实际对接时根据接口返回进行解析。



\### 对接注意事项

1\.  \*\*参数传递方式\*\*：请求参数必填，通过 URL 查询字符串（Query String）的方式传递。

2\.  \*\*编码问题\*\*：请求参数中的中文（如“广州”、“深圳”）需要进行 URL 编码（例如 UTF-8 编码）。

3\.  \*\*返回数据结构\*\*：返回的 JSON 对象中，`data` 字段类型为字符串，可能包含结构化的文本信息，解析时需注意。

4\.  \*\*字段类型\*\*：`distance`、`time`、`fuelcosts`、`bridgetoll`、`totalcost` 等字段虽然定义为字符串，但通常包含数字和单位（如“120公里”、“1.5小时”），提取数值时需进行字符串处理。



\### 给 AI 助手的实现建议

1\.  \*\*请求构建\*\*：使用 HTTP GET 方法，将 `from` 和 `to` 参数作为 URL 的查询参数附加到基础 URL 后。

2\.  \*\*参数编码\*\*：务必对 `from` 和 `to` 参数的值进行 URL 编码，以正确处理中文和特殊字符。

3\.  \*\*响应处理\*\*：将返回的 JSON 字符串解析为对象（如 Python 的 `json` 模块，JavaScript 的 `JSON.parse`）。

4\.  \*\*错误处理\*\*：检查返回的 `code` 字段值，判断请求是否成功。建议实现超时和重试机制。

5\.  \*\*数据提取\*\*：对于 `distance`、`time` 等字段，如果需要纯数值，可以使用正则表达式提取数字部分。例如，从“120公里”中提取“120”。

6\.  \*\*示例代码（Python）\*\*：

&#x20;   ```python

&#x20;   import requests

&#x20;   import json



&#x20;   def query\_city\_travel\_routes(from\_location, to\_location):

&#x20;       url = "https://api.pearapi.ai/api/citytravelroutes/"

&#x20;       params = {

&#x20;           "from": from\_location,

&#x20;           "to": to\_location

&#x20;       }

&#x20;       try:

&#x20;           response = requests.get(url, params=params)

&#x20;           response.raise\_for\_status()  # 检查请求是否成功

&#x20;           data = response.json()

&#x20;           if data.get("code") == 200:  # 假设成功状态码为200

&#x20;               return data

&#x20;           else:

&#x20;               print(f"接口返回错误: {data.get('msg')}")

&#x20;               return None

&#x20;       except requests.exceptions.RequestException as e:

&#x20;           print(f"请求失败: {e}")

&#x20;           return None



&#x20;   # 使用示例

&#x20;   result = query\_city\_travel\_routes("广州", "深圳")

&#x20;   if result:

&#x20;       print(json.dumps(result, ensure\_ascii=False, indent=2))

