Google Directions API 服务端为何仍受 8 个 waypoint 限制？

2026-10-24数据阿明

结论

问题在于请求参数名写成了大写的 KEY，正确写法是小写的 key。

Google Maps API 的查询参数名区分大小写。KEY 无法被识别，这意味着请求没有正确携带你的 Server API Key，也就无法应用该 Key 所属项目的 Billing 配置。请求最终会按未正确认证处理，并触发 8 个 waypoint 的限制。

修正请求 URI

将：

&KEY={3}

改为：

&key={3}

完整 URI 如下：

https://maps.googleapis.com/maps/api/directions/xml?units=imperial&mode=driving&origin={0}&destination={1}&waypoints=optimize:true|{2}&key={3}

endpoint 本身没有问题，/maps/api/directions/xml 是 Directions API 的 XML 响应端点。

ASP.NET MVC 请求示例

构造 URL 时，应分别编码地址和 waypoint，避免空格、&、# 等字符破坏查询字符串。分隔 waypoint 的 | 应保留在参数结构中，也可以交给查询字符串构造工具正确编码。

using System;
using System.Linq;
using System.Net.Http;
using System.Threading.Tasks;

public async Task<string> GetDirectionsAsync(
    string origin,
    string destination,
    string[] waypoints,
    string apiKey)
{
    string waypointValue = "optimize:true|" +
        string.Join("|", waypoints.Select(Uri.EscapeDataString));

    string requestUrl =
        "https://maps.googleapis.com/maps/api/directions/xml" +
        "?units=imperial" +
        "&mode=driving" +
        $"&origin={Uri.EscapeDataString(origin)}" +
        $"&destination={Uri.EscapeDataString(destination)}" +
        $"&waypoints={waypointValue}" +
        $"&key={Uri.EscapeDataString(apiKey)}";

    using var client = new HttpClient();
    return await client.GetStringAsync(requestUrl);
}

也可以使用 QueryHelpers.AddQueryString 等工具来构造查询字符串，减少手工拼接造成的大小写和编码错误。

需要检查的配置

将参数名修正为 key 后，如果仍然出现限额或认证错误，可以继续检查以下项目：

API Key 所属的 Google Cloud 项目是否已启用 Directions API。
Billing 是否关联到该项目，而不只是关联到同一 Google 账号下的其他项目。
Key 的 API restrictions 是否允许调用 Directions API。
如果 Server API Key 设置了 IP address restrictions，请确认请求的实际出口 IP 在允许列表中。
检查响应中的 status 和 error_message，以区分 MAX_WAYPOINTS_EXCEEDED、REQUEST_DENIED 和配额错误。

Billing 并不是直接绑定到某个 Key。Key 属于 Google Cloud 项目，Billing 同样关联到项目。只有请求正确携带该项目生成的 Key，项目中的相关配置才会生效。

Waypoint 数量的计算

这里的 waypoint 通常是指 waypoints 参数中的中间点，不包括 origin 和 destination。因此，23 个中间 waypoint 加上起点和终点，最多涉及 25 个位置。

题目引用的是特定时期 Directions API 的配额规则。Google Maps Platform 的产品、计费方案和 waypoint 限额可能发生调整。对于新项目或当前生产环境，应以项目控制台和现行 Directions API 官方文档为准。

不过，就这个请求而言，首先要修正的是参数名的大小写。应该使用：

key

而不是：

KEY