gogcli 中的gog maps distance在终端批量计算 Google 路线距离矩阵【免费下载链接】gogcliGoogle Workspace in your terminal.项目地址: https://gitcode.com/GitHub_Trending/gogcl/gogcli本文围绕 gogcli 的命令参考页 gog-maps-distance.md 展开完整覆盖gog maps distance的用法、参数与输出格式并结合 internal/cmd/maps.go 与 internal/googleapi/maps.go 的源码实现讲解该命令如何解析 CSV 起终点、校验出行方式与单位、构造 Distance Matrix API 请求以及如何将结果渲染为 TSV 表格或 JSON——读完你可以直接在脚本与 CI 中批量查询多点间的旅行距离与耗时。命令概览gog maps distance是 gog maps 子命令族的一员maps另有别名map用于获取旅行距离与耗时矩阵travel distance and duration matrix即一次请求返回多个起点到多个终点的距离/耗时组合。它支持两个别名distance-matrixmatrix基本调用形式如下gog maps (map) distance (distance-matrix,matrix) --originsSTRING --destinationsSTRING [flags]两个必填参数均接收逗号分隔的地址列表例如gog maps distance \ --originsBarcelona,Madrid \ --destinationsBlanes,Girona \ --modedriving \ --unitsmetric参数详解专用参数参数类型说明取值约束--originsstring起点列表必填逗号分隔源码中经splitCSV切分空串被剔除--destinationsstring终点列表必填逗号分隔同上--modestring出行方式driving|walking|bicycling|transit大小写不敏感缺省时不传该参数--unitsstring距离单位metric|imperial大小写不敏感缺省时不传该参数--languagestringBCP-47 语言代码任意字符串原样透传为 API 的language参数--regionstring区域偏好region bias任意字符串透传为 API 的region参数取值范围不是文档约定而是由命令运行时的归一化函数强制执行的。internal/cmd/maps.go 中的normalizeMapsMode与normalizeMapsUnits只做小写化与白名单匹配func normalizeMapsMode(raw string) (string, error) { v : strings.TrimSpace(strings.ToLower(raw)) switch v { case : return , nil case driving, walking, bicycling, transit: return v, nil default: return , usagef(invalid --mode %q (expected driving, walking, bicycling, or transit), raw) } }一个值得注意的实现细节参数校验发生在建立 API 客户端之前即先校验--mode/--units再解析 API Key因此传错取值时不会消耗任何 API 配额。测试 TestMapsDistanceRejectsInvalidUnitsBeforeAPIKey 专门验证了这一点——在未设置任何 API Key 的情况下传入--unitsparsecs命令即返回invalid --units错误而非缺少 Key错误。全局参数gog maps distance与所有 gogcli 命令共享一组根级参数完整列表见 命令参考页 的 Flags 表。与脚本化使用本命令最相关的几个参数说明-j/--json/--machine以 JSON 输出到 stdout适合脚本处理-p/--plain/--tsv输出稳定、可解析的 TSV 文本无颜色--account(-a)指定账号邮箱、别名或auto--access-token直接使用给定 access token绕过本地存储的 refresh token约 1 小时过期--quota-project计费到指定 GCP 项目X-Goog-User-Project--dry-run(-n)不实际发起变更仅打印将要执行的动作--readonly运行时拦截变更类 API 请求--results-onlyJSON 模式下只输出主结果--selectJSON 模式下按点路径选取字段输出格式表格模式默认internal/cmd/maps.go 中的writeMapsDistance决定默认输出遍历响应中的每一行对应一个起点、每个元素对应一个终点打印五行制表符分隔的记录ORIGIN DESTINATION STATUS DISTANCE DURATION其中起点/终点名称取自响应的origin_addresses/destination_addresses解析后的地址列表通过indexString按索引安全取值越界时输出空串。当响应为空或没有任何行时向 stderr 打印No distances。JSON 模式加上--json后writeMapsDistance直接把整个响应对象包进distanceMatrix键输出gog maps distance --originsBarcelona --destinationsBlanes,Girona --modedriving --jsonJSON 结构来自 internal/googleapi/maps.go 定义的反序列化类型type MapsDistanceMatrixResponse struct { Status string json:status,omitempty ErrorMessage string json:error_message,omitempty OriginAddresses []string json:origin_addresses,omitempty DestAddresses []string json:destination_addresses,omitempty Rows []MapsDistanceMatrixRow json:rows,omitempty } type MapsDistanceMatrixRow struct { Elements []MapsDistanceMatrixElement json:elements,omitempty } type MapsDistanceMatrixElement struct { Status string json:status,omitempty Distance MapsTextValue json:distance,omitempty Duration MapsTextValue json:duration,omitempty }其中MapsTextValue同时保留人类可读文本与原始数值type MapsTextValue struct { Text string json:text,omitempty Value int64 json:value,omitempty }因此脚本中做数值比较如哪条路线最短应使用distance.value米与duration.value秒而text仅用于展示。源码级实现从命令到 HTTP 请求gog maps distance的执行链路可以概括为四层命令层MapsDistanceCmd.Run 解析参数。它先用splitCSV切分--origins/--destinations任一列表为空则报--origins and --destinations are required用法错误随后归一化--mode与--units再创建客户端并调用client.DistanceMatrix。客户端构造newMapsClient 从配置读取 API Key见下文并用环境变量GOG_MAPS_BASE_URL覆盖默认端点return googleapi.NewMapsClient(apiKey, googleapi.WithMapsBaseURL(os.Getenv(GOG_MAPS_BASE_URL))), nil默认端点在 internal/googleapi/maps.go 定义为https://maps.googleapis.com/maps/apiHTTP 客户端超时为 10 秒。请求构造MapsClient.DistanceMatrix 把切分后的起点/终点列表用|连接strings.Join(trimNonEmpty(origins), |)这是 Google Distance Matrix API 要求的多值分隔符再按需追加mode、units、language、region最终通过doGet发起GET /distancematrix/jsonAPI Key 作为key查询参数附带。响应处理与错误映射doGet限制响应体最多读取 2 MiBio.LimitReader非 2xx 状态码直接报错。JSON 解析成功后mapsStatusError做业务状态判定if status || status OK || status ZERO_RESULTS { return nil }也就是说OK与ZERO_RESULTS不算错误后者会走No distances的空结果分支而REQUEST_DENIED、OVER_QUERY_LIMIT等状态则携带error_message转为 CLI 错误返回。API Key 从哪来maps distance与 Places 系命令共用 Key 解析逻辑 placesAPIKey优先级为gogcli 配置文件中的places_api_key可用gog config set places_api_key key写入环境变量GOG_PLACES_API_KEY环境变量GOOGLE_PLACES_API_KEY。三者均未设置时命令会直接给出可操作的报错提示Google Maps/Places API key required. Set GOG_PLACES_API_KEY, GOOGLE_PLACES_API_KEY, or run gog config set places_api_key 。端点可覆盖与测试方式GOG_MAPS_BASE_URL允许把整个 Maps 端点重定向到任意 HTTP 服务这使得离线开发与测试成为可能。internal/cmd/maps_test.go 中的 Directions/Geocode 用例就用httptest.NewServer模拟/directions/json、/geocode/json端点并断言请求中确实携带了key查询参数t.Setenv(GOG_MAPS_BASE_URL, srv.URL)distance参数层的用例如 TestMapsDistanceRejectsInvalidUnitsBeforeAPIKey则证明了先本地校验、后消耗配额的行为契约。实战要点与常见错误地址格式--origins/--destinations中每个元素可传地址文本、lat,lng坐标或 Place ID——这正是 Google Distance Matrix API 接受的形式gogcli 本身只做切分、去空白与|拼接不做地址解析因此地址合法性由 Google 服务端裁定反映在元素级status中如NOT_FOUND。矩阵规模行数等于起点数每行元素数等于终点数批量查询时注意起点/终点数量相乘后的元素总量避免触发 Google 配额限制OVER_QUERY_LIMIT会直接作为错误抛出见上文状态映射逻辑。单位语义--units只影响distance.text的展示单位km/midistance.value始终为米duration.value始终为秒。脚本逻辑请始终基于value字段。典型报错速查--origins and --destinations are requiredCSV 切分后为空例如只传了逗号。invalid --mode ... (expected driving, walking, bicycling, or transit)出行方式不在白名单。invalid --units ... (expected metric or imperial)单位不在白名单。maps API error OVER_QUERY_LIMIT: ...Google 配额/限流属服务端业务状态而非网络错误。相关命令gog maps distance是 maps 子命令族中批量矩阵定位的成员单点对单点的场景可改用同族命令见 gog-maps.md命令用途gog maps directions两点间路线含summary与逐段legsgog maps geocode地址转坐标gog maps reverse-geocode坐标转地址gog maps placesPlaces 文本搜索与详情完整的命令索引见 docs/commands/README.md这些命令参考页由make docs-commands从gog schema --json自动生成请勿手工编辑。【免费下载链接】gogcliGoogle Workspace in your terminal.项目地址: https://gitcode.com/GitHub_Trending/gogcl/gogcli创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
gogcli 中的 `gog maps distance`：在终端批量计算 Google 路线距离矩阵
gogcli 中的gog maps distance在终端批量计算 Google 路线距离矩阵【免费下载链接】gogcliGoogle Workspace in your terminal.项目地址: https://gitcode.com/GitHub_Trending/gogcl/gogcli本文围绕 gogcli 的命令参考页 gog-maps-distance.md 展开完整覆盖gog maps distance的用法、参数与输出格式并结合 internal/cmd/maps.go 与 internal/googleapi/maps.go 的源码实现讲解该命令如何解析 CSV 起终点、校验出行方式与单位、构造 Distance Matrix API 请求以及如何将结果渲染为 TSV 表格或 JSON——读完你可以直接在脚本与 CI 中批量查询多点间的旅行距离与耗时。命令概览gog maps distance是 gog maps 子命令族的一员maps另有别名map用于获取旅行距离与耗时矩阵travel distance and duration matrix即一次请求返回多个起点到多个终点的距离/耗时组合。它支持两个别名distance-matrixmatrix基本调用形式如下gog maps (map) distance (distance-matrix,matrix) --originsSTRING --destinationsSTRING [flags]两个必填参数均接收逗号分隔的地址列表例如gog maps distance \ --originsBarcelona,Madrid \ --destinationsBlanes,Girona \ --modedriving \ --unitsmetric参数详解专用参数参数类型说明取值约束--originsstring起点列表必填逗号分隔源码中经splitCSV切分空串被剔除--destinationsstring终点列表必填逗号分隔同上--modestring出行方式driving|walking|bicycling|transit大小写不敏感缺省时不传该参数--unitsstring距离单位metric|imperial大小写不敏感缺省时不传该参数--languagestringBCP-47 语言代码任意字符串原样透传为 API 的language参数--regionstring区域偏好region bias任意字符串透传为 API 的region参数取值范围不是文档约定而是由命令运行时的归一化函数强制执行的。internal/cmd/maps.go 中的normalizeMapsMode与normalizeMapsUnits只做小写化与白名单匹配func normalizeMapsMode(raw string) (string, error) { v : strings.TrimSpace(strings.ToLower(raw)) switch v { case : return , nil case driving, walking, bicycling, transit: return v, nil default: return , usagef(invalid --mode %q (expected driving, walking, bicycling, or transit), raw) } }一个值得注意的实现细节参数校验发生在建立 API 客户端之前即先校验--mode/--units再解析 API Key因此传错取值时不会消耗任何 API 配额。测试 TestMapsDistanceRejectsInvalidUnitsBeforeAPIKey 专门验证了这一点——在未设置任何 API Key 的情况下传入--unitsparsecs命令即返回invalid --units错误而非缺少 Key错误。全局参数gog maps distance与所有 gogcli 命令共享一组根级参数完整列表见 命令参考页 的 Flags 表。与脚本化使用本命令最相关的几个参数说明-j/--json/--machine以 JSON 输出到 stdout适合脚本处理-p/--plain/--tsv输出稳定、可解析的 TSV 文本无颜色--account(-a)指定账号邮箱、别名或auto--access-token直接使用给定 access token绕过本地存储的 refresh token约 1 小时过期--quota-project计费到指定 GCP 项目X-Goog-User-Project--dry-run(-n)不实际发起变更仅打印将要执行的动作--readonly运行时拦截变更类 API 请求--results-onlyJSON 模式下只输出主结果--selectJSON 模式下按点路径选取字段输出格式表格模式默认internal/cmd/maps.go 中的writeMapsDistance决定默认输出遍历响应中的每一行对应一个起点、每个元素对应一个终点打印五行制表符分隔的记录ORIGIN DESTINATION STATUS DISTANCE DURATION其中起点/终点名称取自响应的origin_addresses/destination_addresses解析后的地址列表通过indexString按索引安全取值越界时输出空串。当响应为空或没有任何行时向 stderr 打印No distances。JSON 模式加上--json后writeMapsDistance直接把整个响应对象包进distanceMatrix键输出gog maps distance --originsBarcelona --destinationsBlanes,Girona --modedriving --jsonJSON 结构来自 internal/googleapi/maps.go 定义的反序列化类型type MapsDistanceMatrixResponse struct { Status string json:status,omitempty ErrorMessage string json:error_message,omitempty OriginAddresses []string json:origin_addresses,omitempty DestAddresses []string json:destination_addresses,omitempty Rows []MapsDistanceMatrixRow json:rows,omitempty } type MapsDistanceMatrixRow struct { Elements []MapsDistanceMatrixElement json:elements,omitempty } type MapsDistanceMatrixElement struct { Status string json:status,omitempty Distance MapsTextValue json:distance,omitempty Duration MapsTextValue json:duration,omitempty }其中MapsTextValue同时保留人类可读文本与原始数值type MapsTextValue struct { Text string json:text,omitempty Value int64 json:value,omitempty }因此脚本中做数值比较如哪条路线最短应使用distance.value米与duration.value秒而text仅用于展示。源码级实现从命令到 HTTP 请求gog maps distance的执行链路可以概括为四层命令层MapsDistanceCmd.Run 解析参数。它先用splitCSV切分--origins/--destinations任一列表为空则报--origins and --destinations are required用法错误随后归一化--mode与--units再创建客户端并调用client.DistanceMatrix。客户端构造newMapsClient 从配置读取 API Key见下文并用环境变量GOG_MAPS_BASE_URL覆盖默认端点return googleapi.NewMapsClient(apiKey, googleapi.WithMapsBaseURL(os.Getenv(GOG_MAPS_BASE_URL))), nil默认端点在 internal/googleapi/maps.go 定义为https://maps.googleapis.com/maps/apiHTTP 客户端超时为 10 秒。请求构造MapsClient.DistanceMatrix 把切分后的起点/终点列表用|连接strings.Join(trimNonEmpty(origins), |)这是 Google Distance Matrix API 要求的多值分隔符再按需追加mode、units、language、region最终通过doGet发起GET /distancematrix/jsonAPI Key 作为key查询参数附带。响应处理与错误映射doGet限制响应体最多读取 2 MiBio.LimitReader非 2xx 状态码直接报错。JSON 解析成功后mapsStatusError做业务状态判定if status || status OK || status ZERO_RESULTS { return nil }也就是说OK与ZERO_RESULTS不算错误后者会走No distances的空结果分支而REQUEST_DENIED、OVER_QUERY_LIMIT等状态则携带error_message转为 CLI 错误返回。API Key 从哪来maps distance与 Places 系命令共用 Key 解析逻辑 placesAPIKey优先级为gogcli 配置文件中的places_api_key可用gog config set places_api_key key写入环境变量GOG_PLACES_API_KEY环境变量GOOGLE_PLACES_API_KEY。三者均未设置时命令会直接给出可操作的报错提示Google Maps/Places API key required. Set GOG_PLACES_API_KEY, GOOGLE_PLACES_API_KEY, or run gog config set places_api_key 。端点可覆盖与测试方式GOG_MAPS_BASE_URL允许把整个 Maps 端点重定向到任意 HTTP 服务这使得离线开发与测试成为可能。internal/cmd/maps_test.go 中的 Directions/Geocode 用例就用httptest.NewServer模拟/directions/json、/geocode/json端点并断言请求中确实携带了key查询参数t.Setenv(GOG_MAPS_BASE_URL, srv.URL)distance参数层的用例如 TestMapsDistanceRejectsInvalidUnitsBeforeAPIKey则证明了先本地校验、后消耗配额的行为契约。实战要点与常见错误地址格式--origins/--destinations中每个元素可传地址文本、lat,lng坐标或 Place ID——这正是 Google Distance Matrix API 接受的形式gogcli 本身只做切分、去空白与|拼接不做地址解析因此地址合法性由 Google 服务端裁定反映在元素级status中如NOT_FOUND。矩阵规模行数等于起点数每行元素数等于终点数批量查询时注意起点/终点数量相乘后的元素总量避免触发 Google 配额限制OVER_QUERY_LIMIT会直接作为错误抛出见上文状态映射逻辑。单位语义--units只影响distance.text的展示单位km/midistance.value始终为米duration.value始终为秒。脚本逻辑请始终基于value字段。典型报错速查--origins and --destinations are requiredCSV 切分后为空例如只传了逗号。invalid --mode ... (expected driving, walking, bicycling, or transit)出行方式不在白名单。invalid --units ... (expected metric or imperial)单位不在白名单。maps API error OVER_QUERY_LIMIT: ...Google 配额/限流属服务端业务状态而非网络错误。相关命令gog maps distance是 maps 子命令族中批量矩阵定位的成员单点对单点的场景可改用同族命令见 gog-maps.md命令用途gog maps directions两点间路线含summary与逐段legsgog maps geocode地址转坐标gog maps reverse-geocode坐标转地址gog maps placesPlaces 文本搜索与详情完整的命令索引见 docs/commands/README.md这些命令参考页由make docs-commands从gog schema --json自动生成请勿手工编辑。【免费下载链接】gogcliGoogle Workspace in your terminal.项目地址: https://gitcode.com/GitHub_Trending/gogcl/gogcli创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
