gogcli 实战指南用gog maps places search在终端里做 Google Places 文本搜索【免费下载链接】gogcliGoogle Workspace in your terminal.项目地址: https://gitcode.com/GitHub_Trending/gogcl/gogcli本篇聚焦 gogcliGoogle Workspace in your terminal中的gog maps places search子命令如何完成 Places API 密钥配置、如何按文本搜索地点、如何以 TSV/JSON 两种格式消费结果并结合源码拆解命令从参数解析到 HTTP 请求的完整调用链。读完你不仅能直接复制命令用于脚本与 Agent 工作流还能理解该命令底层调用的 Places API v1 接口形态places:searchText、字段掩码、密钥鉴权头与错误边界。命令概览与别名体系gog maps places search是 gogcli Maps 子树下的地点文本搜索命令官方文档页 gog-maps-places-search.md 给出的标准用法为gog maps (map) places (place) search (find) query ... [flags]括号中的内容是别名命令树在 internal/cmd/maps.go 中用 kong 标签注册maps可写作mapplaces可写作placesearch可写作find。也就是说下面三种写法等价gog maps places search cafe in Berlin gog map place find cafe in Berlinquery是位置参数且支持多段——从源码看参数定义为Query []string运行时用空格把所有片段拼接成一个查询串见 MapsPlacesSearchCmd.Run所以不必担心 shell 引号截断gog maps places search cafe in Berlin与加引号效果一致若拼接后为空则直接报missing query。该命令在 Maps 子树中属于 Places 分支docs/commands/gog-maps-places.md与gog maps places details平级同级的还有directions、distance、geocode、reverse-geocode见 docs/commands/gog-maps.md 对应的 internal/cmd/maps.go 命令树定义。完整命令索引见 docs/commands/README.md。Places API 密钥的三种配置方式gog maps places search使用 Google API 密钥而非 OAuth 账号鉴权。密钥解析入口是 placesAPIKey其读取逻辑由 internal/config/keys.go 中的KeyPlacesAPIKey规格定义按以下优先级取第一个非空值环境变量GOG_PLACES_API_KEY环境变量GOOGLE_PLACES_API_KEY配置文件中的places_api_key项通过gog config set places_api_key key写入配置项在 internal/config/config.go 中映射为places_api_keyJSON 字段。该键被标记为Sensitive: true即配置读写路径会对其做脱敏处理。三个来源都缺失时命令给出明确的排障提示Google Maps/Places API key required. Set GOG_PLACES_API_KEY, GOOGLE_PLACES_API_KEY, or run gog config set places_api_key key因此最省事的落地方式是gog config set places_api_key AIza... # 写入配置 # 或临时使用环境变量适合 CI GOG_PLACES_API_KEYAIza... gog maps places search coffee命令参数详解该命令自身只有两个查询参数其余为全局通用 flag参数类型说明query ...位置参数多值文本搜索查询串多个片段会以空格拼接空串直接报 usage 错误--languagestringBCP-47 语言代码作为请求体languageCode下发--regionstringCLDR 地区代码作为请求体regionCode下发用于结果本地化偏好--language与--region会经strings.TrimSpace处理后装入googleapi.PlacesLookupOptions见 internal/cmd/maps.go仅当非空时才写入请求即不传时对 API 默认行为零影响。全局常用 Flag文档页列出的完整 Flag 表覆盖所有 gogcli 全局 flag这里挑出与脚本化、Agent 场景最相关的几项完整表格以 gog-maps-places-search.md 为准Flag类型默认作用-j/--json/--machineboolfalse以 JSON 输出到 stdout最适合脚本消费-p/--plain/--tsvboolfalse输出稳定可解析的 TSV 文本无颜色--select/--pickstringJSON 模式下选取逗号分隔字段支持点路径尽力而为--results-onlyboolJSON 模式只输出主结果丢弃nextPageToken等信封字段--colorstringauto颜色输出auto/always/never-n/--dry-run等别名bool不产生变更仅打印意图动作--no-input/--non-interactivebool从不交互提问失败即退出CI 友好-a/--accountstring账号邮箱、别名或auto本命令走 API 密钥一般用不到--access-tokenstring直接使用给定 access token本命令不使用 OAuth--quota-projectstring计费项目X-Goog-User-Project--enable-commands/--disable-commandsstring以点路径限制/禁用命令前缀做 CLI 收窄--wrap-untrustedboolfalse在 JSON/raw 输出中用“外部不可信内容”标记包裹抓取到的文本字段-y/--forcebool跳过破坏性命令确认-v/--verbosebool开启详细日志--homestring覆盖 gogcli 配置/数据/状态/缓存根目录等价GOG_HOME输出格式人类可读 TSV 与 JSON输出由 writeMapsPlace 统一生成分两条路径JSON 模式-j以{place: {...}}信封输出完整Place对象字段为id、name、formatted_address、google_maps_uri人类模式按行输出字段\t值且只打印非空字段——id恒输出name、address、maps_uri仅在有值时出现若拿到空结果则向 stderr 打印No place并正常退出。一个典型用法是把它接入脚本取地图链接gog maps places search Brandenburg Gate Berlin -j \ | jq -r .place.google_maps_uri或取坐标线索做后续处理gog maps places search Eiffel Tower -p # id ChIJd8... # name Eiffel Tower # address Avenue Gustave Eiffel, 75007 Paris, France # maps_uri https://maps.google.com/?cid...注意--select是“尽力而为”的字段筛选帮助文本明确建议多数命令优先用--fields思路而--results-only用于裁掉信封字段——对本命令这种单结果输出两者通常不是必需的。源码级剖析从 Run 到 HTTP 请求调用链MapsPlacesSearchCmd.Runinternal/cmd/maps.go的流程为拼接并 Trim 查询串为空则返回missing query调 newMapsPlacesClient先经placesAPIKey取密钥再用googleapi.NewPlacesClient构建客户端并用环境变量GOG_PLACES_BASE_URL覆盖默认 base URL测试与本地调试钩子调用client.TextSearch(ctx, query, opts)随后交给writeMapsPlace输出。TextSearch 的接口形态核心 HTTP 逻辑在 internal/googleapi/places.go端点POST {baseURL}/places:searchText默认 base URL 为https://places.googleapis.com/v1Places API v1请求体{textQuery: query}非空时追加languageCode、regionCode鉴权与字段掩码密钥放在X-Goog-Api-Key请求头X-Goog-FieldMask固定为places.id,places.displayName,places.formattedAddress,places.googleMapsUri——即客户端只索取这四个字段响应体被限制在 2 MB 内读取io.LimitReaderHTTP 超时 10 秒见 NewPlacesClient结果策略命令只返回places数组中的第一个匹配项映射为Place{ID, Name, FormattedAddress, GoogleMapsURI}数组为空时报no places matched: query。也就是说gog maps places search的语义是“取最佳匹配的单条结果”。如果你需要完整结果列表可以走 gogcli 的通用 raw API 通道参见 raw-api.md或基于id接着调gog maps places details placeId取详情。错误边界doJSON 与非 2xx 状态处理placesAPIError会解析 Google 标准error.message/error.status包装为places API error code status: message形式抛出——密钥无效、配额超限等场景在终端里会直接看到 Google 的原始错误信息便于排障。测试证据如何验证这个命令的行为单元测试 internal/cmd/maps_test.go 中的TestMapsPlacesSearch给出了一个可直接参考的端到端验证方式起一个httptest本地服务器断言请求为POST /places:searchText且携带X-Goog-Api-Key: test-key通过GOG_PLACES_API_KEYtest-key与GOG_PLACES_BASE_URL测试服务器地址两个环境变量把真实客户端指向 mock以[]string{cafe}构造查询运行命令断言 JSON 输出包含 place id、名称与 maps URI。这个模式也说明了GOG_PLACES_BASE_URL的设计意图无需真实密钥即可离线复现、调试整个 Places 搜索链路。同文件的TestMapsDirections、TestMapsGeocode对 directions/geocode 分支采用同样手法。小结与关联命令gog maps places search是 Places API v1 文本搜索的极简封装多段 query 拼接、单条最佳结果、四字段精简输出、密钥三级配置GOG_PLACES_API_KEY→GOOGLE_PLACES_API_KEY→config set places_api_key拿到id后可用gog maps places details iddocs/commands/gog-maps-places-details.md深入取详情二者共用同一PlacesClient与PlacesLookupOptions路线、距离矩阵、地理编码由同文件内的MapsDirectionsCmd/MapsDistanceCmd/MapsGeocodeCmd/MapsReverseGeocodeCmd提供同样受GOG_MAPS_BASE_URL覆盖钩子与同一密钥配置约束见 internal/cmd/maps.go该命令为只读查询--dry-run、--readonly等安全 flag 语义与其它命令一致可直接纳入 CI 或 Agent 工作流配合--no-input、-j、-p获得稳定、可解析的输出。【免费下载链接】gogcliGoogle Workspace in your terminal.项目地址: https://gitcode.com/GitHub_Trending/gogcl/gogcli创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考