local-search

使用 Google Maps 进行本地搜索

通过受 x402 保护的端点访问 Google Maps Places API。

设置

安装和钱包设置请参阅 rules/getting-started.md。

快速参考

任务	端点	价格	包含的数据
文本搜索（基础）	https://stableenrich.dev/api/google-maps/text-search/partial	$0.02	名称、地址、评分
文本搜索（完整）	https://stableenrich.dev/api/google-maps/text-search/full	$0.08	+ 评论、氛围
附近搜索（基础）	https://stableenrich.dev/api/google-maps/nearby-search/partial	$0.02	名称、地址、评分
附近搜索（完整）	https://stableenrich.dev/api/google-maps/nearby-search/full	$0.08	+ 评论、氛围
地点详情（基础）	https://stableenrich.dev/api/google-maps/place-details/partial	$0.02	核心信息
地点详情（完整）	https://stableenrich.dev/api/google-maps/place-details/full	$0.05	所有字段
航拍视图查询（GET）	https://stableenrich.dev/api/google-maps/aerial-view/lookup-video	$0.01	航拍视频 URI + 元数据
航拍视图渲染（POST）	https://stableenrich.dev/api/google-maps/aerial-view/render-video	$0.01	渲染新航拍视频
太阳能建筑洞察（GET）	https://stableenrich.dev/api/google-maps/solar/building-insights	$0.02	屋顶/太阳能潜力、imageryDate
太阳能数据图层（GET）	https://stableenrich.dev/api/google-maps/solar/data-layers	$0.08	GeoTIFF URL（rgb、dsm、flux）
太阳能 RGB 图像（GET）	https://stableenrich.dev/api/google-maps/solar/rgb-image	$0.05	渲染为 PNG/JPEG 的 GeoTIFF 图层

有关套餐选择指南，请参阅 rules/partial-vs-full.md。

文本搜索

通过文本查询搜索地点：

npx agentcash@latest fetch https://stableenrich.dev/api/google-maps/text-search/partial -m POST -b '{"textQuery": "coffee shops in downtown Seattle"}'

参数：

• textQuery - 搜索查询（必填）
• locationBias - 优先显示某地点附近的结果（使用包含中心点 lat/lng 和以米为单位的半径的 circle，最大值为 50000）
• includedType - 用于筛选的单个 Google Places 类型
• minRating - 最低评分筛选（0-5）
• openNow - 仅限营业中的地点
• maxResultCount - 每页结果数，1-5（默认：5）
• priceLevels - 按价格等级筛选（例如 PRICE_LEVEL_INEXPENSIVE）
• pageToken - 上一条响应中的分页游标

分页： 存在更多结果时，响应中会包含 nextPageToken。要获取下一页，请重复发送完整的原始请求正文（包括 textQuery），并添加原样复制的 pageToken。pageToken 仅对生成它的搜索有效。

完整套餐还会返回：评论、氛围数据、照片、价格等级。

附近搜索

搜索某个地点附近的地点：

npx agentcash@latest fetch https://stableenrich.dev/api/google-maps/nearby-search/partial -m POST -b '{
  "locationRestriction": {
    "circle": {
      "center": {"latitude": 47.6062, "longitude": -122.3321},
      "radius": 1000
    }
  },
  "includedTypes": ["restaurant", "cafe"]
}'

参数：

• locationRestriction - 包含中心点（lat/lng）和以米为单位半径的圆形区域，最大值为 50000（必填）
• includedTypes - 要包含的地点类型（仅限 Google Places 官方类型，例如 restaurant；自然语言类别请使用文本搜索）
• excludedTypes - 要排除的地点类型
• maxResultCount - 每页结果数，1-5（默认：5）
• rankPreference - POPULARITY（默认）或 DISTANCE

地点详情

获取特定地点的详细信息：

npx agentcash@latest fetch "https://stableenrich.dev/api/google-maps/place-details/partial?placeId=ChIJN1t_tDeuEmsRUsoyG83frY4"

输入：

• placeId - Google Place ID（来自搜索结果）

基础套餐返回： 名称、地址、电话、网站、营业时间、评分、类型。

完整套餐返回： 另含评论、氛围信息（无障碍轮椅通行、是否允许携带宠物）、照片、价格等级。

航拍视图

获取某个地址的电影感航拍视频。先查询是否已有视频（$0.01）；如果没有，则请求渲染（$0.01）。

npx agentcash@latest fetch "https://stableenrich.dev/api/google-maps/aerial-view/lookup-video?address=500%20W%202nd%20St%2C%20Austin%2C%20TX"

npx agentcash@latest fetch https://stableenrich.dev/api/google-maps/aerial-view/render-video -m POST -b '{"address": "500 W 2nd St, Austin, TX"}'

查询输入： address 或 videoId（必填其一）。

渲染输入： address（必填）。

返回： state、videoId、视频 uris（横屏/竖屏/缩略图）、拍摄元数据。渲染为异步操作——请轮询 lookup-video，直到 state 变为 active。

Solar

获取某个地点的屋顶太阳能洞察和影像：

npx agentcash@latest fetch "https://stableenrich.dev/api/google-maps/solar/building-insights?latitude=37.4450&longitude=-122.1390"

建筑洞察（$0.02）： latitude、longitude（必填）、requiredQuality（LOW/MEDIUM/HIGH，默认 HIGH）。返回最近建筑的屋顶/太阳能潜力和 imageryDate。

数据图层（$0.08）： latitude、longitude（必填）、radiusMeters（默认 50，最大 175）、view、requiredQuality、pixelSizeMeters。返回 GeoTIFF URL（rgbUrl、dsmUrl、flux/shade/mask URL）和 imageryDate。

RGB 图像（$0.05）： 将 Solar GeoTIFF 图层渲染为 PNG/JPEG。传入 GeoTIFF id，或 latitude/longitude，以及 layer（rgb、dsm、annualFlux、monthlyFlux、hourlyShade、mask）、radiusMeters（默认 30，最大 100）、用于 flux/shade 波段的 month/hour、format、scale、crop、quality。返回包含公开图像 URL 的 JSON。monthlyFlux：单个月份或 4x3 网格；hourlyShade：单个小时或 6x4 网格。

npx agentcash@latest fetch "https://stableenrich.dev/api/google-maps/solar/rgb-image?latitude=37.4450&longitude=-122.1390&layer=annualFlux"

常见地点类型

在 includedTypes / excludedTypes 中使用以下类型：

餐饮： restaurant、cafe、bar、bakery、coffee_shop

住宿： hotel、motel、lodging、guest_house

购物： shopping_mall、store、supermarket、clothing_store

服务： bank、atm、gas_station、car_repair、car_wash

医疗： hospital、pharmacy、doctor、dentist

娱乐： movie_theater、museum、park、gym

工作流

查找区域内的商家

• （可选）查询余额：npx agentcash@latest balance
• 使用文本搜索（partial）查找选项
• 查看结果并选出首选项
• 获取所选地点的完整详情

npx agentcash@latest fetch https://stableenrich.dev/api/google-maps/text-search/partial -m POST -b '{"textQuery": "Italian restaurants downtown Portland"}'

npx agentcash@latest fetch "https://stableenrich.dev/api/google-maps/place-details/full?placeId=ChIJ..."

使用筛选条件搜索附近地点

• 获取该区域的坐标
• 使用位置限制和筛选条件进行搜索
• 展示排序后的结果

npx agentcash@latest fetch https://stableenrich.dev/api/google-maps/nearby-search/partial -m POST -b '{
  "locationRestriction": {
    "circle": {
      "center": {"latitude": 40.7128, "longitude": -74.0060},
      "radius": 500
    }
  },
  "includedTypes": ["restaurant"],
  "rankPreference": "DISTANCE"
}'

对比地点及其评价

• 搜索以获取地点 ID
• 获取每个候选地点的完整详情
• 对比评分、评价和便利设施

npx agentcash@latest fetch "https://stableenrich.dev/api/google-maps/place-details/full?placeId=place_id_here"

成本优化

以下情况使用 Partial 层级：

• 只需要名称、地址和基本信息
• 浏览/探索选项
• 深入查询前的初步搜索

以下情况使用 Full 层级：

• 需要评价/评分详情
• 需要氛围信息（无障碍设施等）
• 做出最终决定

高效模式

1. 搜索使用 partial，详情使用 full：

   • 使用文本搜索（partial）查找地点
   • 对关注的地点获取详情（full）

2. 批量搜索：

   • 组合筛选条件以减少调用次数
   • 使用 maxResultCount 限制结果数量

3. 缓存地点 ID：

   • 地点 ID 稳定不变
   • 仅在需要时重新获取详情

响应数据

Partial 层级字段

• name - 地点名称
• formattedAddress - 完整地址
• location - 经纬度坐标
• rating - 平均评分（1-5）
• userRatingCount - 评分数量
• types - 地点类型类别
• businessStatus - OPERATIONAL、CLOSED 等
• regularOpeningHours - 营业时间
• nationalPhoneNumber - 电话号码
• websiteUri - 网站 URL

Full 层级的其他字段

• reviews - 包含文本和评分的用户评价
• priceLevel - $ 到 $$$$
• accessibilityOptions - 轮椅通行等
• parkingOptions - 停车情况
• paymentOptions - 接受的付款方式
• photos - 照片引用