本文详解如何正确调用 bing maps driving routes api 获取两地间驾驶距离，重点纠正 url 参数格式错误、参数命名不规范及缺乏异常处理等常见问题，并提供健壮、可复用的 python 实现示例。
本文详解如何正确调用 bing maps driving routes api 获取两地间驾驶距离，重点纠正 url 参数格式错误、参数命名不规范及缺乏异常处理等常见问题，并提供健壮、可复用的 python 实现示例。
在使用 Bing Maps REST API（特别是 Routes/Driving 端点）计算地址或邮编间驾驶距离时，一个高频出错原因是 URL 查询参数构造不合规。原始代码中存在多处关键错误：
- 错误使用 wp,0（逗号）而非标准参数名 wp.0；
- 混用 mp.1（该参数已弃用，应统一使用 wp.N 表示途经点）；
- URL 末尾多余 / 导致路径解析失败；
- 未对输入地址（如 CEP 或城市名）做 URL 编码，特殊字符（空格、中文、标点）将导致 400 错误；
- 缺乏 HTTP 状态码校验与 JSON 结构容错，一旦 API 返回异常响应（如配额超限、地理编码失败），程序直接崩溃。
✅ 正确的请求格式必须遵循 Bing Maps 官方规范：
- 使用 wp.0={origin} 和 wp.1={destination} 指定起点与终点；
- 所有地址值需经 urllib.parse.quote() 编码（例如 "São Paulo" → "S%C3%A3o%20Paulo"）；
- 可选参数如 avoid=minimizeTolls 需置于 key 前；
- key 必须为最后一个查询参数。
以下是推荐的生产级实现（含错误处理、动态地址注入与 DataFrame 结构化输出）：
import requests
import pandas as pd
from urllib.parse import quote
# 配置项（请替换为实际值）
API_KEY = "Aqa9_KZFeRDAiAsJwyxVLQJh5tfZYeMyGHtUXEVd7PGm13xT1evy3vwA5MCcscqd"
lista_cep = ["01001-000", "22793-080"] # 示例：巴西 CEP 列表（需确保地理可解析）
lista_cidade = ["São Paulo, SP", "Rio de Janeiro, RJ"]
distancia_matrix = []
for origem in lista_cep:
linha_distancias = []
for destino in lista_cidade:
# 关键：URL 编码地址，避免空格/特殊字符破坏请求
encoded_origem = quote(origem)
encoded_destino = quote(destino)
url = (
f"http://dev.virtualearth.net/REST/V1/Routes/Driving?"
f"wp.0={encoded_origem}&wp.1={encoded_destino}"
f"&avoid=minimizeTolls&key={API_KEY}"
)
try:
response = requests.get(url, timeout=15)
response.raise_for_status() # 抛出 4xx/5xx 异常
data = response.json()
# 容错读取：逐层检查嵌套结构，避免 KeyError
resources = data.get("resourceSets", [{}])[0].get("resources", [{}])
if not resources:
raise ValueError("No routing resources returned")
route = resources[0]
distancia_km = route.get("travelDistance") # 单位：公里（float）
if distancia_km is None:
linha_distancias.append("N/A (no distance)")
else:
linha_distancias.append(round(distancia_km, 3))
except requests.exceptions.Timeout:
linha_distancias.append("Error: Timeout")
except requests.exceptions.ConnectionError:
linha_distancias.append("Error: Connection failed")
except requests.exceptions.HTTPError as e:
linha_distancias.append(f"HTTP {response.status_code}")
except (KeyError, ValueError, TypeError) as e:
linha_distancias.append(f"Parse Error: {str(e)}")
except Exception as e:
linha_distancias.append(f"Unexpected: {str(e)}")
distancia_matrix.append(linha_distancias)
# 构建带行列标签的 DataFrame，提升可读性
df = pd.DataFrame(
distancia_matrix,
columns=lista_cidade,
index=lista_cep
)
print(df)? 重要注意事项：
- 地址格式建议：Bing Maps 对 CEP（巴西邮编）支持有限，强烈推荐使用“城市+州”组合（如 "Curitiba, PR"）或完整街道地址，以提升地理编码成功率；
- 配额与认证：免费版 Bing Maps API 有日调用量限制（约 50,000 次/月），且需在 Azure Portal 中启用 Maps 服务并绑定有效订阅；
- HTTPS 强制要求：生产环境务必使用 https://（而非 http://），否则部分区域会拒绝响应；
- 批量优化：若需计算大量点对，应考虑使用 Bing Maps 的 Matrix Routing API（支持单次请求计算 N×M 组合），显著降低延迟与请求数。
通过以上修正，您将获得稳定、可维护、符合生产标准的距离矩阵计算能力。
