POST /api/v2/photos

API de scraping de fotos de Google Maps

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.

Ejemplos de solicitud

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.

Respuesta

JSON ilustrativo
{
  "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

Abra la galería pública de un lugar.

Solicite metadatos de imágenes y vídeos de un solo lugar usando su feature ID.

Parámetros de solicitud de la API de scraping de fotos de Google Maps
CampoSignificado
fid · obligatorioUn 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 1Una 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

Enlaces de fotos, enlaces de vídeos y la galería de origen.

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.

Campos de respuesta de la API de scraping de fotos de Google Maps
CampoSignificado
photoUrlLa URL de foto disponible, o la imagen de vista previa de un elemento de vídeo.
videoUrlUna URL de vídeo opcional. Está presente en los registros de vídeo que incluyen una fuente de vídeo.
urlLa URL de la galería de Google Maps del lugar solicitado.
nextSi hay otra página numerada de galería disponible.
totalEl recuento de esta respuesta, de cero a 20. No es el tamaño total de la galería del lugar.
paramsEl 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

Lea hasta 20 elementos de galería en cada respuesta.

Use la marca next devuelta para decidir si su flujo de trabajo necesita otra solicitud.

01

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.

02

Inspeccione la página actual

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.

03

Continúe deliberadamente

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

Incorpore metadatos de galería a su flujo de trabajo de investigación.

01

Investigación de fichas de negocios

Inspeccione la galería asociada a un negocio seleccionado y conserve el enlace de la galería de origen junto a los registros devueltos.

02

Organización de fotos y vídeos

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.

03

Revisión de galería asistida por agente

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

Use su clave de API para cada página.

Cuota de API compartida

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.

Ver planes y límites de API →

Mantenga los reintentos vinculados a la solicitud

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.

Lea la guía de errores y reintentos →

Preguntas frecuentes

¿Qué devuelve la API de scraping de fotos de Google Maps?

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.

¿Cómo obtengo el feature ID de la galería de un 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.

¿La API de Photos descarga archivos de imagen o vídeo?

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.

¿Cómo pagino una galería de Google Maps?

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.

¿El orden de la galería es configurable?

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.

¿Puede un agente de IA recuperar metadatos de galería?

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

Explore la galería de un lugar.

Cree una clave de API, proporcione el feature ID de un lugar y recupere metadatos estructurados de fotos y vídeos.