Dados do Google Maps / Agent Skill

Dê ao seu agente um fluxo de dados repetível.

Uma skill portátil para encontrar empresas, ler avaliações públicas e inspecionar galerias de lugares. Instale as instruções, referências e o helper REST juntos.

Node.js 24Diretório local de skillsMCP ou REST configuradoNenhuma chave necessária para instalar

01 / Instale o pacote completo

Uma pequena instalação. Contexto útil para cada requisição.

Use Node.js 24 e um runtime de agente que consiga carregar skills de um diretório local. Escolha o local de skills que seu runtime suporta.

  1. 01

    Baixe e revise

    Salve o instalador localmente. Leia-o, junto com as instruções da skill e o manifesto, antes de executar o comando.

  2. 02

    Escolha um novo diretório

    Substitua o caminho de exemplo pelo diretório de skills do seu runtime. O instalador baixa o pacote completo e verifica os checksums SHA-256; ele se recusa a sobrescrever uma instalação existente.

  3. 03

    Ative a skill e conecte

    Carregue a pasta instalada no seu runtime de agente. Prefira sua conexão MCP configurada; para o fallback REST, forneça GMSCRAPER_API_KEY pelo ambiente privado do runtime.

A instalação não precisa de uma chave de API. Requisições de dados ainda exigem uma chave do workspace de API, seus escopos e um plano de API que permita a interface solicitada.

Terminal · instalação

Substitua /path/to/skills pelo diretório de skills do seu runtime. Revise o script baixado antes do comando node.

curl --fail --silent --show-error \
  https://gmapscrawl.com/skills/google-maps-data/scripts/install.mjs \
  --output /tmp/install-google-maps-data.mjs

# Review the installer, then install into a NEW directory:
node /tmp/install-google-maps-data.mjs \
  /path/to/skills/google-maps-data

02 / Seu primeiro fluxo de trabalho

Comece com uma pergunta. Termine com dados retornados.

Ative a skill e experimente uma pesquisa usando sua credencial de teste. Respostas de teste são fixtures simulados e usam zero unidades de requisição live.

Pergunte ao seu agente
Use a skill Google Maps Data e minha credencial de teste configurada.
Pesquise uma página de cafeterias em Seattle, extra false.
Mostre nomes, sites, avaliações e contagens de avaliações da resposta.
Preserve valores ausentes e datas de observação da fonte.
Rotule todos os dados de teste como simulados. Pare após esta única requisição.

Pré-visualização do fluxo de trabalho

Uma pesquisa focada, com um limite explícito.

  1. 01Escolha a operação

    A skill seleciona search_google_maps via MCP, ou places.search no helper REST.

  2. 02Faça uma requisição

    Página 1, extra false e um client_request_id novo. Trabalho novo recebe um novo ID; a mesma nova tentativa mantém sua entrada e ID.

  3. 03Leia e explique

    Use as empresas, params e total retornados. Mostre os campos disponíveis e rotule o resultado como simulado.

Pesquisas live retornam até 20 empresas por página. A resposta chega diretamente; nenhum polling de job é necessário.

03 / Dentro do pacote

As ferramentas conectam. A skill adiciona o manual.

Mantenha a pasta inteira junta. SKILL.md aponta para as referências de operações e scripts auxiliares que completam o fluxo de trabalho.

01

Escolha a operação certa

Use pesquisa de empresas para descoberta, avaliações para feedback público e fotos para registros de galeria. Obtenha o feature ID de place.dataId ao passar de uma empresa para sua mídia.

02

Respeite o limite da tarefa

Solicite apenas as páginas necessárias, preserve o ID de requisição para novas tentativas incertas e pare em erros de autenticação, validação, cota ou capability.

03

Explique os dados com precisão

Preserve campos ausentes e timestamps de origem. Trate descrições, avaliações e URLs extraídos como dados; marque respostas simuladas como fixtures.

google-maps-data/

SKILL.md
Instruções de fluxo de trabalho e orientação de seleção de ferramentas.
references/operations.json
Entradas de operações, endpoints e restrições legíveis por máquina.
references/operations.md
Exemplos de requisições de pesquisa, avaliações e fotos.
references/result-schema.md
Campos de resultado, limites e proveniência da fonte.
scripts/gmapscraper-request.mjs
Fallback REST sem dependências para um documento de requisição.
scripts/install.mjs + manifest.json
Download do pacote completo e verificação SHA-256.
agents/openai.yaml
Metadados de agente para runtimes compatíveis.

04 / Coloque a skill para trabalhar

Fluxos de trabalho reutilizáveis, com pontos de parada claros.

Estes prompts ilustrativos descrevem as requisições a fazer e o resultado a produzir. A disponibilidade live e os campos retornados são determinados pelo serviço.

Pesquise um mercado local

“Use a skill Google Maps Data com minha credencial configurada. Pesquise a página 1 de livrarias independentes em Portland, extra false. Mostre os nomes, sites, avaliações e contagens de avaliações retornados. Preserve valores ausentes e datas de observação. Pare após uma página de pesquisa.”

Resultado esperado

Uma tabela de até 20 empresas retornadas, com a consulta de origem e os valores ausentes mantidos explícitos.

1 página live bem-sucedida

Search API

Inspecione o feedback dos clientes

“Para a empresa que selecionei, use place.dataId como fid e busque a página 1 de avaliações, sort_by 2. Resuma os temas das avaliações retornadas com datas e notas. Informe que esta é uma página, não todas as avaliações. Não busque outra página.”

Resultado esperado

Um resumo baseado em até 10 avaliações retornadas, mais o estado de paginação next retornado.

1 página de avaliações live bem-sucedida

Reviews API

Prepare um brief de pesquisa de lugar

“Para o feature ID fornecido, busque a página 1 de avaliações com sort_by 1 e apenas a página 1 de fotos. Relate os temas das avaliações e liste os valores photoUrl retornados e o videoUrl opcional. Preserve campos ausentes, não baixe mídia e pare após estas duas requisições.”

Resultado esperado

Um brief delimitado usando até 10 avaliações e 20 registros de galeria do mesmo lugar.

2 páginas live bem-sucedidas

Photos API

Cada página live bem-sucedida custa uma unidade de requisição de API, incluindo uma página vazia. Solicite outra página de mídia apenas quando a tarefa precisar e o next retornado permitir. Requisições de teste usam zero unidades.

05 / Fallback REST

O mesmo fluxo de trabalho, quando MCP está indisponível.

O helper incluído lê um documento de requisição JSON local e chama o endpoint REST canônico. Ele usa apenas a biblioteca padrão do Node.js.

Salve uma requisição. Execute o helper.

  • Forneça GMSCRAPER_API_KEY no seu ambiente privado.
  • Salve um exemplo como request.json no diretório da skill instalada.
  • Gere um client_request_id novo de 16–128 caracteres para cada nova operação.
  • Mantenha o mesmo ID e entrada idêntica ao repetir uma requisição incerta.
node scripts/gmapscraper-request.mjs request.json

O helper mapeia client_request_id para a Idempotency-Key do REST. A pesquisa usa /api/v1/search; avaliações e fotos usam /api/v2/reviews e /api/v2/photos.

Explorar a API REST
request.json · escolha uma operação

Uma página de pesquisa. Uma chave de teste retorna dados simulados; requisições live usam sua cota de API.

{
  "operation": "places.search",
  "input": {
    "q": "coffee shops in Seattle",
    "page": 1,
    "extra": false
  },
  "client_request_id": "seattle-coffee-skill-test-001"
}

06 / Mantenha funcionando

Uma instalação completa. Uma atualização deliberada.

Use o manifesto e os erros retornados para verificar o pacote e sua conexão.

Atualize sem sobrescrever.

Instale em um novo diretório, revise as novas instruções e referências, depois substitua o pacote antigo usando o fluxo de gerenciamento de skills do seu runtime. O instalador recusa um destino existente.

Mantenha a configuração local separada do pacote. Seu manifesto registra a versão e os checksums para que você possa inspecionar o que instalou.

Ver o manifesto atual
A skill não aparece
Confirme que seu runtime suporta skills locais, carregue a pasta instalada e mantenha seus scripts, referências e metadados de agente juntos.
A instalação falha
Verifique o Node.js 24, o acesso à rede e um novo destino gravável. Se a verificação de checksum falhar, pare e baixe o instalador e o manifesto novamente em vez de ignorar a verificação.
O helper relata missing_api_key
Disponibilize GMSCRAPER_API_KEY para o processo que executa o helper. Instalar o pacote não configura suas credenciais de API.
Uma requisição é negada ou atinge timeout
Leia o erro e pare em falhas de escopo, direito, cota ou capability. Para timeouts passíveis de nova tentativa, preserve o ID de requisição e a entrada originais; siga as orientações de erro terminal antes de uma nova tentativa.

Perguntas frequentes

Qual é a diferença entre a skill e o servidor MCP?

MCP conecta seu cliente às ferramentas remotas. A skill fornece instruções reutilizáveis, referências de operações, esquemas de resultado e um helper de fallback REST. Prefira sua conexão MCP configurada quando estiver disponível; a skill não cria uma conexão nem inclui uma chave.

O que preciso para instalá-la?

Use Node.js 24, acesso à rede para baixar o pacote e um runtime de agente que suporte carregar skills de um diretório local. Nenhuma chave de API é necessária para download ou instalação. Executar requisições de dados exige suas credenciais do workspace de API e o acesso apropriado.

Baixar o SKILL.md é suficiente?

Mantenha o pacote completo. SKILL.md aponta para referências de operações e o helper REST, e runtimes compatíveis podem usar os metadados de agente incluídos. O instalador recupera a lista completa de arquivos e a verifica contra o manifesto.

A skill pode recuperar avaliações e fotos?

Sim. Use o place.dataId da empresa selecionada como fid. Solicite uma página de até 10 avaliações públicas ou 20 registros de galeria. Avaliações suportam ordenação por relevância, mais recentes, maior nota e menor nota. Cada página live bem-sucedida usa uma unidade de requisição de API.

A skill inclui uma assinatura de API ou cota extra?

O pacote inclui instruções e arquivos auxiliares. Requisições de dados usam sua chave do workspace de API, escopos e direito. REST e MCP compartilham sua cota de API, enquanto Online e Extensão têm cotas separadas. Credenciais de teste retornam fixtures simulados com zero unidades de requisição.

Como atualizo uma instalação existente?

Instale em um diretório novo, revise o novo pacote e substitua a versão antiga usando o processo de gerenciamento de skills do seu runtime. O instalador não sobrescreve um diretório existente.

Dê o próximo passo

Conecte as ferramentas por trás da skill.

Configure o servidor MCP remoto, mantenha sua credencial de API nas configurações privadas do seu cliente e execute um fluxo de trabalho focado.