POST /api/v2/photos

API de scraping de fotos do Google Maps

Leia até 20 itens de galeria de um lugar por página. Obtenha URLs de fotos e vídeos na ordem em que aparecem na galeria.

Exemplos de requisição

Para o contrato completo, consulte a documentação da 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}'

Substitua o fid de exemplo pelo feature ID do seu lugar. A resposta é simulada; as URLs de mídia example.com são placeholders. Mantenha a mesma chave de idempotência e corpo ao repetir uma requisição em execução.

Resposta

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
  }
}

A API retorna JSON na mesma resposta. Após um timeout, repita o corpo inalterado com a mesma Idempotency-Key. Credenciais de teste retornam dados simulados sem usar sua cota live.

Comece com um lugar

Abra a galeria pública de um lugar.

Solicite metadados de imagens e vídeos de um único lugar usando seu feature ID.

Parâmetros de requisição da API de scraping de fotos do Google Maps
CampoSignificado
fid · obrigatórioUm feature ID do Google Maps, como 0x89c259af336b3341:0xa4969e07ce3108de. Use place.dataId de um resultado da Search API, ou um feature ID que você já tem.
page · padrão 1Uma página numerada positiva. Aumente-a apenas quando a resposta anterior tiver next: true.

Para descobrir um feature ID, pesquise uma empresa com a API de scraping do Google Maps. Copie place.dataId da entrada correspondente em data.businesses e passe-o como fid. Um place ID ou nome de empresa não é o mesmo formato de entrada.

Registros de galeria

Links de fotos, links de vídeos e a galeria de origem.

Cada item tem um photoUrl para a imagem ou pré-visualização do vídeo. Itens de vídeo também incluem um videoUrl. O url de nível superior aponta para a galeria do lugar.

Campos de resposta da API de scraping de fotos do Google Maps
CampoSignificado
photoUrlA URL de foto disponível, ou a imagem de pré-visualização de um item de vídeo.
videoUrlUma URL de vídeo opcional. Está presente para registros de vídeo que incluem uma fonte de vídeo.
urlA URL da galeria do Google Maps do lugar solicitado.
nextSe outra página numerada de galeria está disponível.
totalA contagem nesta resposta, de zero a 20. Este não é o tamanho total da galeria do lugar.
paramsO fid e a página normalizados usados para esta resposta.

O endpoint retorna este objeto de página diretamente como JSON. Leia photos do nível superior. A API retorna metadados e links de mídia. A disponibilidade de uma imagem ou vídeo depende da fonte; um item de galeria não garante um vídeo baixável.

Uma página delimitada por vez

Leia até 20 itens de galeria em cada resposta.

Use a flag next retornada para decidir se seu fluxo de trabalho precisa de outra requisição.

01

Comece com a página 1

Envie o fid do lugar e a página 1. Os registros seguem a ordem fornecida pela galeria do lugar.

02

Inspecione a página atual

total conta os itens de galeria retornados nesta resposta. Uma página vazia é um resultado válido. Verifique os campos disponíveis antes de adicionar registros à sua análise.

03

Continue deliberadamente

Quando next for true, incremente page e mantenha o mesmo fid. Pare quando next for false, ou quando seu fluxo de trabalho tiver registros de mídia suficientes.

Explore um lugar visualmente

Traga metadados de galeria para o seu fluxo de pesquisa.

01

Pesquisa de fichas de empresas

Inspecione a galeria associada a uma empresa selecionada e mantenha o link da galeria de origem ao lado dos registros retornados.

02

Organização de fotos e vídeos

Separe registros de foto de registros de vídeo usando o campo opcional videoUrl, e apresente as imagens de pré-visualização disponíveis na sua própria interface de pesquisa.

03

Revisão de galeria assistida por agente

Permita que um agente conectado recupere uma página de metadados de galeria e liste os links de mídia disponíveis para inspeção adicional.

Autenticação e uso

Use sua chave de API para cada página.

Cota de API compartilhada

Envie Authorization: Bearer com uma chave que permita scrapes:write. Cada página live bem-sucedida, incluindo uma página vazia, usa uma unidade de requisição de API. REST e MCP usam a mesma cota de API. Se você tem uma credencial de teste, suas respostas são simuladas e não consomem a cota live.

Ver planos e limites da API →

Mantenha as novas tentativas vinculadas à requisição

Envie uma Idempotency-Key opcional com sua primeira requisição e preserve-a com um corpo idêntico para uma nova tentativa após timeout. Um timeout de processamento pode deixar uma unidade reservada. Se um erro indicar que a tentativa terminou, siga suas orientações de nova tentativa antes de criar uma nova tentativa com uma nova chave.

Leia as orientações de erros e novas tentativas →

Perguntas frequentes

O que a API de scraping de fotos do Google Maps retorna?

Ela retorna até 20 registros de metadados de fotos e vídeos de um lugar em cada resposta JSON. Cada registro tem um photoUrl, e registros de vídeo também podem incluir videoUrl. O url de nível superior aponta para a galeria do lugar.

Como obtenho o feature ID da galeria de um lugar?

Use place.dataId de uma empresa correspondente em uma resposta da Search API e envie-o como fid. Você também pode fornecer um feature ID do Maps existente. Envie o mesmo fid ao solicitar outras páginas da galeria.

A Photos API baixa arquivos de imagem ou vídeo?

O endpoint retorna metadados e URLs de mídia em JSON. Seu aplicativo pode inspecionar os links disponíveis e a fonte da galeria. A disponibilidade da fonte determina quais registros e URLs são retornados; um photoUrl pode ser a imagem de pré-visualização de um vídeo.

Como faço a paginação de uma galeria do Google Maps?

Comece com a página 1. total conta os registros dessa resposta. Se next for true, solicite a próxima página com o mesmo fid e uma nova chave de idempotência para a nova requisição. Pare quando next for false ou seu fluxo de trabalho tiver registros suficientes.

A ordem da galeria é configurável?

A Photos API aceita fid e page. Ela retorna itens na ordem da galeria fornecida pela fonte; não expõe um parâmetro sort_by no estilo de avaliações.

Um agente de IA pode recuperar metadados de galeria?

Sim. Conecte um cliente MCP compatível para usar get_google_maps_photos com suas credenciais de API. O Agent Skill adiciona instruções de fluxo de trabalho e um fallback REST. Cada página de galeria live bem-sucedida usa a cota de API compartilhada.

Dê o próximo passo

Explore a galeria de um lugar.

Crie uma chave de API, forneça o feature ID de um lugar e recupere metadados estruturados de fotos e vídeos.