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.
POST /api/v2/photos
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.
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.
{
"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
Solicite metadados de imagens e vídeos de um único lugar usando seu feature ID.
| Campo | Significado |
|---|---|
| fid · obrigatório | Um 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 1 | Uma 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
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.
| Campo | Significado |
|---|---|
| photoUrl | A URL de foto disponível, ou a imagem de pré-visualização de um item de vídeo. |
| videoUrl | Uma URL de vídeo opcional. Está presente para registros de vídeo que incluem uma fonte de vídeo. |
| url | A URL da galeria do Google Maps do lugar solicitado. |
| next | Se outra página numerada de galeria está disponível. |
| total | A contagem nesta resposta, de zero a 20. Este não é o tamanho total da galeria do lugar. |
| params | O 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
Use a flag next retornada para decidir se seu fluxo de trabalho precisa de outra requisição.
Envie o fid do lugar e a página 1. Os registros seguem a ordem fornecida pela galeria do lugar.
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.
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
Inspecione a galeria associada a uma empresa selecionada e mantenha o link da galeria de origem ao lado dos registros retornados.
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.
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
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.
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.
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.
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.
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.
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 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.
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
Crie uma chave de API, forneça o feature ID de um lugar e recupere metadados estruturados de fotos e vídeos.