Comience con la página 1
Envíe el fid del lugar y la página 1. Los registros siguen el orden proporcionado por la galería del lugar.
POST /api/v2/photos
Lea hasta 20 elementos de galería de un lugar por página. Obtenga URLs de fotos y vídeos en el orden en que aparecen en la galería.
Para el contrato completo, consulte la documentación de la 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}'Sustituya el fid de ejemplo por el feature ID de su lugar. La respuesta es simulada; las URLs de medios de example.com son marcadores de posición. Conserve la misma clave de idempotencia y el mismo cuerpo al reintentar una solicitud en curso.
{
"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
}
}La API devuelve JSON en la misma respuesta. Tras un timeout, reintente el cuerpo sin cambios con la misma Idempotency-Key. Las credenciales de prueba devuelven datos simulados sin usar su cuota en vivo.
Comience con un lugar
Solicite metadatos de imágenes y vídeos de un solo lugar usando su feature ID.
| Campo | Significado |
|---|---|
| fid · obligatorio | Un feature ID de Google Maps, como 0x89c259af336b3341:0xa4969e07ce3108de. Use place.dataId de un resultado de la API de Search, o un feature ID que ya tenga. |
| page · predeterminado 1 | Una página numerada positiva. Increméntela solo cuando la respuesta anterior tenga next: true. |
Para descubrir un feature ID, busque un negocio con la API de scraping de Google Maps. Copie place.dataId de la entrada coincidente en data.businesses y páselo como fid. Un place ID o un nombre de negocio no es el mismo formato de entrada.
Registros de galería
Cada elemento tiene un photoUrl para la imagen o la vista previa del vídeo. Los elementos de vídeo también incluyen un videoUrl. El url de nivel superior enlaza a la galería del lugar.
| Campo | Significado |
|---|---|
| photoUrl | La URL de foto disponible, o la imagen de vista previa de un elemento de vídeo. |
| videoUrl | Una URL de vídeo opcional. Está presente en los registros de vídeo que incluyen una fuente de vídeo. |
| url | La URL de la galería de Google Maps del lugar solicitado. |
| next | Si hay otra página numerada de galería disponible. |
| total | El recuento de esta respuesta, de cero a 20. No es el tamaño total de la galería del lugar. |
| params | El fid y la page normalizados usados para esta respuesta. |
El endpoint devuelve este objeto de página directamente como JSON. Lea photos desde el nivel superior. La API devuelve metadatos y enlaces de medios. La disponibilidad de una imagen o un vídeo depende de la fuente; un elemento de galería no garantiza un vídeo descargable.
Una página delimitada cada vez
Use la marca next devuelta para decidir si su flujo de trabajo necesita otra solicitud.
Envíe el fid del lugar y la página 1. Los registros siguen el orden proporcionado por la galería del lugar.
total cuenta los elementos de galería devueltos en esta respuesta. Una página vacía es un resultado válido. Compruebe los campos disponibles antes de añadir registros a su análisis.
Cuando next sea true, incremente page y mantenga el mismo fid. Deténgase cuando next sea false, o cuando su flujo de trabajo tenga suficientes registros de medios.
Explore un lugar visualmente
Inspeccione la galería asociada a un negocio seleccionado y conserve el enlace de la galería de origen junto a los registros devueltos.
Separe los registros de fotos de los de vídeos usando el campo opcional videoUrl, y presente las imágenes de vista previa disponibles en su propia interfaz de investigación.
Permita que un agente conectado recupere una página de metadatos de galería y enumere los enlaces de medios disponibles para una inspección posterior.
Autenticación y uso
Envíe Authorization: Bearer con una clave que permita scrapes:write. Cada página en vivo exitosa, incluida una página vacía, usa una unidad de solicitud de API. REST y MCP usan la misma cuota de API. Si tiene una credencial de prueba, sus respuestas son simuladas y no consumen cuota en vivo.
Envíe una Idempotency-Key opcional con su primera solicitud y consérvela con un cuerpo idéntico para un reintento tras timeout. Un timeout de procesamiento puede dejar una unidad reservada. Si un error indica que el intento ha terminado, siga su guía de reintento antes de crear un nuevo intento con una nueva clave.
Devuelve hasta 20 registros de metadatos de fotos y vídeos de un lugar en cada respuesta JSON. Cada registro tiene un photoUrl, y los registros de vídeo también pueden incluir videoUrl. El url de nivel superior enlaza a la galería del lugar.
Use place.dataId de un negocio coincidente en una respuesta de la API de Search y envíelo como fid. También puede proporcionar un feature ID de Maps existente. Envíe el mismo fid al solicitar más páginas de galería.
El endpoint devuelve metadatos y URLs de medios en JSON. Su aplicación puede inspeccionar los enlaces disponibles y la fuente de la galería. La disponibilidad de la fuente determina qué registros y URLs se devuelven; un photoUrl puede ser la imagen de vista previa de un vídeo.
Comience con la página 1. total cuenta los registros de esa respuesta. Si next es true, solicite la página siguiente con el mismo fid y una nueva clave de idempotencia para la nueva solicitud. Deténgase cuando next sea false o su flujo de trabajo tenga suficientes registros.
La API de Photos acepta fid y page. Devuelve los elementos en el orden de galería proporcionado por la fuente; no expone un parámetro sort_by al estilo de las reseñas.
Sí. Conecte un cliente MCP compatible para usar get_google_maps_photos con sus credenciales de API. El Agent Skill añade instrucciones de flujo de trabajo y un respaldo REST. Cada página de galería en vivo exitosa usa la cuota de API compartida.
Dé el siguiente paso
Cree una clave de API, proporcione el feature ID de un lugar y recupere metadatos estructurados de fotos y vídeos.