从第 1 页开始
发送地点的 fid 和第 1 页。记录按地点相册提供的顺序排列。
完整的接口约定请参见 API 文档。
curl https://gmapscrawl.com/api/v2/photos \
-H "Authorization: Bearer $GMSCRAPER_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: place-photos-page-1-example" \
-d '{"fid":"0x89c259af336b3341:0xa4969e07ce3108de","page":1}'请将示例 fid 替换为您地点的 feature ID。该响应是模拟的;example.com 的媒体 URL 是占位符。重试进行中的请求时,请保持相同的幂等键和请求体。
{
"photos": [
{
"photoUrl": "https://example.com/gallery-image.jpg"
},
{
"photoUrl": "https://example.com/gallery-preview.jpg",
"videoUrl": "https://example.com/gallery-video.mp4"
}
],
"next": false,
"total": 2,
"url": "https://www.google.com/maps/uv?pb=!1s0x89c259af336b3341:0xa4969e07ce3108de!15sCgIgAQ",
"params": {
"fid": "0x89c259af336b3341:0xa4969e07ce3108de",
"page": 1
}
}API 在同一响应中返回 JSON。超时后,请使用相同的 Idempotency-Key 以不变的请求体重试。测试凭据返回模拟数据,不消耗您的正式额度。
从一个地点开始
使用地点的 feature ID 请求其图像和视频元数据。
| 字段 | 含义 |
|---|---|
| fid · 必填 | Google Maps feature ID,例如 0x89c259af336b3341:0xa4969e07ce3108de。使用 Search API 结果中的 place.dataId,或您已有的 feature ID。 |
| page · 默认 1 | 正整数页码。仅当上一个响应返回 next: true 时才增加。 |
要获取 feature ID,请使用 Google Maps 抓取 API 搜索商户。在 data.businesses 中找到匹配项,复制其中的 place.dataId 并将其作为 fid 传入。地点 ID 或商户名称不是相同的输入格式。
相册记录
每个条目都有用于图像或视频预览的 photoUrl。视频条目还包含 videoUrl。顶层的 url 指向该地点的相册。
| 字段 | 含义 |
|---|---|
| photoUrl | 可用的照片 URL,或视频条目的预览图。 |
| videoUrl | 可选的视频 URL。仅在包含视频来源的视频记录中出现。 |
| url | 所请求地点的 Google Maps 相册 URL。 |
| next | 是否还有下一个相册页。 |
| total | 本次响应中的记录数,0 到 20。这不是该地点相册的总大小。 |
| params | 本次响应使用的规范化 fid 和 page。 |
端点将该页面对象直接作为 JSON 返回。从顶层读取 photos。API 返回的是元数据和媒体链接。图像或视频的可用性取决于来源;相册条目并不保证有可下载的视频。
每次一个有边界的页面
使用返回的 next 标志决定您的工作流是否需要再发请求。
发送地点的 fid 和第 1 页。记录按地点相册提供的顺序排列。
total 统计的是本次响应返回的相册条目数。空页面也是有效结果。将记录纳入分析前,请先检查可用字段。
当 next 为 true 时,递增 page 并保持 fid 不变。当 next 为 false,或您的工作流已有足够媒体记录时停止。
直观地探索地点
查看与所选商户关联的相册,并在返回记录旁保留来源相册链接。
利用可选的 videoUrl 字段区分照片记录和视频记录,并在您自己的研究界面中展示可用的预览图。
让已连接的智能体获取一页相册元数据,并列出可用的媒体链接以供进一步检查。
认证与用量
发送携带 Authorization: Bearer 的密钥,且该密钥需允许 scrapes:write。每个成功的正式页(包括空页)消耗一个 API 请求单位。REST 和 MCP 使用同一 API 额度。如果您使用测试凭据,其响应为模拟数据且不消耗正式额度。
在首次请求中发送可选的 Idempotency-Key,超时重试时用相同请求体保留该键。处理中超时可能会保留一个已预留单位。如果错误报告该尝试已结束,请遵循其重试指引,再使用新键创建新尝试。
每个 JSON 响应返回某个地点最多 20 条照片和视频元数据记录。每条记录都有 photoUrl,视频记录还可能包含 videoUrl。顶层的 url 指向该地点的相册。
在 Search API 响应中找到匹配商户的 place.dataId,并将其作为 fid 发送。您也可以提供已有的 Maps feature ID。请求后续相册页时使用相同的 fid。
端点以 JSON 返回元数据和媒体 URL。您的应用可以检查可用的链接和相册来源。返回哪些记录和 URL 取决于来源可用性;photoUrl 也可能是视频的预览图。
从第 1 页开始。total 统计该响应中的记录数。如果 next 为 true,用相同的 fid 请求下一页,并为新请求使用新的幂等键。当 next 为 false 或您的工作流已有足够记录时停止。
Photos API 接受 fid 和 page。它按来源提供的相册顺序返回条目,不提供评价接口那样的 sort_by 参数。
可以。连接兼容的 MCP 客户端,使用您的 API 凭据调用 get_google_maps_photos。Agent Skill 还提供工作流说明和 REST 备用方案。每个成功的正式相册页都使用共享 API 额度。