POST /api/v2/photos

Google Maps 照片抓取 API

每页读取某个地点最多 20 条相册内容。按照片在相册中出现的顺序获取照片和视频 URL。

请求示例

完整的接口约定请参见 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 是占位符。重试进行中的请求时,请保持相同的幂等键和请求体。

响应

示例 JSON
{
  "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 请求其图像和视频元数据。

Google Maps 照片抓取 API 请求参数
字段含义
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 指向该地点的相册。

Google Maps 照片抓取 API 响应字段
字段含义
photoUrl可用的照片 URL,或视频条目的预览图。
videoUrl可选的视频 URL。仅在包含视频来源的视频记录中出现。
url所请求地点的 Google Maps 相册 URL。
next是否还有下一个相册页。
total本次响应中的记录数,0 到 20。这不是该地点相册的总大小。
params本次响应使用的规范化 fid 和 page。

端点将该页面对象直接作为 JSON 返回。从顶层读取 photos。API 返回的是元数据和媒体链接。图像或视频的可用性取决于来源;相册条目并不保证有可下载的视频。

每次一个有边界的页面

每个响应最多读取 20 条相册内容。

使用返回的 next 标志决定您的工作流是否需要再发请求。

01

从第 1 页开始

发送地点的 fid 和第 1 页。记录按地点相册提供的顺序排列。

02

检查当前页

total 统计的是本次响应返回的相册条目数。空页面也是有效结果。将记录纳入分析前,请先检查可用字段。

03

有意识地继续

当 next 为 true 时,递增 page 并保持 fid 不变。当 next 为 false,或您的工作流已有足够媒体记录时停止。

直观地探索地点

把相册元数据带入您的研究工作流。

01

商户列表研究

查看与所选商户关联的相册,并在返回记录旁保留来源相册链接。

02

照片和视频整理

利用可选的 videoUrl 字段区分照片记录和视频记录,并在您自己的研究界面中展示可用的预览图。

03

智能体辅助相册检查

让已连接的智能体获取一页相册元数据,并列出可用的媒体链接以供进一步检查。

认证与用量

每页都使用您的 API 密钥。

共享 API 额度

发送携带 Authorization: Bearer 的密钥,且该密钥需允许 scrapes:write。每个成功的正式页(包括空页)消耗一个 API 请求单位。REST 和 MCP 使用同一 API 额度。如果您使用测试凭据,其响应为模拟数据且不消耗正式额度。

查看 API 套餐和限额 →

让重试始终对应原请求

在首次请求中发送可选的 Idempotency-Key,超时重试时用相同请求体保留该键。处理中超时可能会保留一个已预留单位。如果错误报告该尝试已结束,请遵循其重试指引,再使用新键创建新尝试。

阅读错误与重试指引 →

常见问题

Google Maps 照片抓取 API 返回什么?

每个 JSON 响应返回某个地点最多 20 条照片和视频元数据记录。每条记录都有 photoUrl,视频记录还可能包含 videoUrl。顶层的 url 指向该地点的相册。

如何获取地点相册的 feature ID?

在 Search API 响应中找到匹配商户的 place.dataId,并将其作为 fid 发送。您也可以提供已有的 Maps feature ID。请求后续相册页时使用相同的 fid。

Photos API 会下载图像或视频文件吗?

端点以 JSON 返回元数据和媒体 URL。您的应用可以检查可用的链接和相册来源。返回哪些记录和 URL 取决于来源可用性;photoUrl 也可能是视频的预览图。

如何对 Google Maps 相册分页?

从第 1 页开始。total 统计该响应中的记录数。如果 next 为 true,用相同的 fid 请求下一页,并为新请求使用新的幂等键。当 next 为 false 或您的工作流已有足够记录时停止。

相册顺序可以配置吗?

Photos API 接受 fid 和 page。它按来源提供的相册顺序返回条目,不提供评价接口那样的 sort_by 参数。

AI 智能体能获取相册元数据吗?

可以。连接兼容的 MCP 客户端,使用您的 API 凭据调用 get_google_maps_photos。Agent Skill 还提供工作流说明和 REST 备用方案。每个成功的正式相册页都使用共享 API 额度。

迈出下一步

探索某个地点的相册。

创建 API 密钥,提供地点的 feature ID,获取结构化的照片和视频元数据。