Dati di Google Maps / Agent Skill

Dia al Suo agente un workflow di dati ripetibile.

Una skill portatile per trovare attività, leggere recensioni pubbliche e ispezionare le gallerie dei luoghi. Installi insieme istruzioni, riferimenti e helper REST.

Node.js 24Directory locale delle skillMCP o REST configuratoNessuna chiave necessaria per installare

01 / Installi il pacchetto completo

Una piccola installazione. Contesto utile per ogni richiesta.

Usi Node.js 24 e un runtime per agenti che possa caricare skill da una directory locale. Scelga la posizione delle skill supportata dal Suo runtime.

  1. 01

    Scarichi e revisioni

    Salvi l'installer in locale. Legga l'installer, le istruzioni della skill e il manifest prima di eseguire il comando.

  2. 02

    Scelga una nuova directory

    Sostituisca il percorso di esempio con la directory delle skill del Suo runtime. L'installer recupera il pacchetto completo e verifica i checksum SHA-256; rifiuta di sovrascrivere un'installazione esistente.

  3. 03

    Abiliti la skill e si colleghi

    Carichi la cartella installata nel Suo runtime per agenti. Preferisca la Sua connessione MCP configurata; per il fallback REST, fornisca GMSCRAPER_API_KEY tramite l'ambiente privato del runtime.

L'installazione non richiede una chiave API. Le richieste di dati richiedono comunque una chiave dell'area di lavoro API, i suoi scope e un piano API che consenta l'interfaccia richiesta.

Terminale · installazione

Sostituisca /path/to/skills con la directory delle skill del Suo runtime. Revisioni lo script scaricato prima del 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 / Il Suo primo workflow

Inizi con una domanda. Finisca con i dati restituiti.

Abiliti la skill e provi una ricerca usando la Sua credenziale di test. Le risposte di test sono fixture simulati e usano zero unità di richiesta live.

Chieda al Suo agente
Usi la skill Google Maps Data e la mia credenziale di test configurata.
Cerchi una pagina di caffetterie a Seattle, extra false.
Mostri nomi, siti web, valutazioni e conteggi delle recensioni dalla risposta.
Conservi i valori mancanti e le date di osservazione della sorgente.
Etichetti tutti i dati di test come simulati. Si fermi dopo questa singola richiesta.

Anteprima del workflow

Una ricerca mirata, con un limite esplicito.

  1. 01Scelga l'operazione

    La skill seleziona search_google_maps tramite MCP, o places.search nell'helper REST.

  2. 02Faccia una richiesta

    Pagina 1, extra false e un client_request_id nuovo. Il nuovo lavoro riceve un nuovo ID; lo stesso retry conserva input e ID.

  3. 03Legga e spieghi

    Usi businesses, params e total restituiti. Mostri i campi disponibili ed etichetti il risultato come simulato.

Le ricerche live restituiscono fino a 20 attività per pagina. La risposta arriva direttamente; non serve polling di job.

03 / Dentro il pacchetto

Gli strumenti si collegano. La skill aggiunge il playbook.

Tenga l'intera cartella unita. SKILL.md rimanda ai riferimenti delle operazioni e agli script helper che completano il workflow.

01

Scelga l'operazione giusta

Usi la ricerca di attività per la scoperta, le recensioni per il feedback pubblico e le foto per i record della galleria. Ottenga il feature ID da place.dataId passando da un'attività ai suoi media.

02

Rispetti il limite dell'attività

Richieda solo le pagine necessarie, conservi l'ID di richiesta per i retry incerti e si fermi su errori di autenticazione, validazione, quota o capability.

03

Spieghi i dati accuratamente

Conservi i campi mancanti e i timestamp di origine. Tratti descrizioni, recensioni e URL estratti come dati; segni le risposte simulate come fixture.

google-maps-data/

SKILL.md
Istruzioni di workflow e guida alla selezione degli strumenti.
references/operations.json
Input delle operazioni, endpoint e vincoli leggibili da macchina.
references/operations.md
Esempi di richieste di ricerca, recensioni e foto.
references/result-schema.md
Campi dei risultati, limiti e provenienza della sorgente.
scripts/gmapscraper-request.mjs
Fallback REST senza dipendenze per un documento di richiesta.
scripts/install.mjs + manifest.json
Download del pacchetto completo e verifica SHA-256.
agents/openai.yaml
Metadati agente per runtime compatibili.

04 / Metta la skill al lavoro

Workflow riutilizzabili, con punti di arresto chiari.

Questi prompt illustrativi descrivono le richieste da fare e il risultato da produrre. La disponibilità live e i campi restituiti sono determinati dal servizio.

Ricerchi un mercato locale

“Usi la skill Google Maps Data con la mia credenziale configurata. Cerchi la pagina 1 per librerie indipendenti a Portland, extra false. Mostri nomi, siti web, valutazioni e conteggi delle recensioni restituiti. Conservi valori mancanti e date di osservazione. Si fermi dopo una pagina di ricerca.”

Risultato atteso

Una tabella di fino a 20 attività restituite, con la query di origine e i valori mancanti mantenuti espliciti.

1 pagina live riuscita

API Search

Ispezioni il feedback dei clienti

“Per l'attività che ho selezionato, usi place.dataId come fid e recuperi la pagina 1 delle recensioni, sort_by 2. Riassuma i temi delle recensioni restituite con date e valutazioni. Dichiari che questa è una pagina, non tutte le recensioni. Non recuperi un'altra pagina.”

Risultato atteso

Un riepilogo basato su fino a 10 recensioni restituite, più lo stato di paginazione next restituito.

1 pagina di recensioni live riuscita

API Reviews

Prepari un brief di ricerca su un luogo

“Per il feature ID fornito, recuperi la pagina 1 delle recensioni con sort_by 1 e solo la pagina 1 delle foto. Riporti i temi delle recensioni ed elenchi i valori photoUrl restituiti e i videoUrl opzionali. Conservi i campi mancanti, non scarichi media e si fermi dopo queste due richieste.”

Risultato atteso

Un brief delimitato che usa fino a 10 recensioni e 20 record di galleria per lo stesso luogo.

2 pagine live riuscite

API Photos

Ogni pagina live riuscita costa un'unità di richiesta API, inclusa una pagina vuota. Richieda un'altra pagina di media solo quando l'attività lo richiede e il next restituito lo consente. Le richieste di test usano zero unità.

05 / Fallback REST

Lo stesso workflow, quando MCP non è disponibile.

L'helper incluso legge un documento di richiesta JSON locale e chiama l'endpoint REST canonico. Usa solo la libreria standard di Node.js.

Salvi una richiesta. Esegua l'helper.

  • Fornisca GMSCRAPER_API_KEY nel Suo ambiente privato.
  • Salvi un esempio come request.json nella directory della skill installata.
  • Generi un client_request_id nuovo di 16–128 caratteri per ogni nuova operazione.
  • Mantenga lo stesso ID e input identico quando riprova una richiesta incerta.
node scripts/gmapscraper-request.mjs request.json

L'helper mappa client_request_id alla Idempotency-Key REST. La ricerca usa /api/v1/search; reviews e photos usano /api/v2/reviews e /api/v2/photos.

Esplori l'API REST
request.json · scelga un'operazione

Una pagina di ricerca. Una chiave di test restituisce dati simulati; le richieste live usano la Sua quota API.

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

06 / La mantenga funzionante

Un'installazione completa. Un aggiornamento deliberato.

Usi il manifest e gli errori restituiti per controllare il pacchetto e la Sua connessione.

Aggiorni senza sovrascrivere.

Installi in una nuova directory, revisioni le nuove istruzioni e i nuovi riferimenti, poi sostituisca il vecchio pacchetto usando il workflow di gestione delle skill del Suo runtime. L'installer rifiuta una destinazione esistente.

Tenga la configurazione locale separata dal pacchetto. Il suo manifest registra versione e checksum, così può ispezionare ciò che ha installato.

Veda il manifest attuale
La skill non appare
Confermi che il Suo runtime supporta le skill locali, carichi la cartella installata e tenga uniti script, riferimenti e metadati agente.
L'installazione fallisce
Controlli Node.js 24, l'accesso alla rete e una destinazione nuova e scrivibile. Se la verifica del checksum fallisce, si fermi e recuperi di nuovo installer e manifest invece di bypassare la verifica.
L'helper segnala missing_api_key
Renda GMSCRAPER_API_KEY disponibile al processo che esegue l'helper. Installare il pacchetto non configura le Sue credenziali API.
Una richiesta è negata o va in timeout
Legga l'errore e si fermi su fallimenti di scope, diritto, quota o capability. Per i timeout per cui è possibile riprovare, conservi ID di richiesta e input originali; segua la guida sugli errori terminali prima di un nuovo tentativo.

Domande frequenti

Qual è la differenza tra la skill e il server MCP?

MCP collega il Suo client agli strumenti remoti. La skill fornisce istruzioni riutilizzabili, riferimenti delle operazioni, schemi dei risultati e un helper di fallback REST. Preferisca la Sua connessione MCP configurata quando disponibile; la skill non crea una connessione né include una chiave.

Cosa mi serve per installarla?

Usi Node.js 24, accesso alla rete per scaricare il pacchetto e un runtime per agenti che supporti il caricamento di skill da una directory locale. Nessuna chiave API è richiesta per download o installazione. Eseguire richieste di dati richiede le Sue credenziali dell'area di lavoro API e l'accesso appropriato.

Scaricare SKILL.md è sufficiente?

Conservi il pacchetto completo. SKILL.md rimanda ai riferimenti delle operazioni e all'helper REST, e i runtime compatibili possono usare i metadati agente inclusi. L'installer recupera l'elenco completo dei file e lo verifica contro il manifest.

La skill può recuperare recensioni e foto?

Sì. Usi il place.dataId dell'attività selezionata come fid. Richieda una pagina di fino a 10 recensioni pubbliche o 20 record di galleria. Le recensioni supportano l'ordinamento per rilevanza, più recenti, valutazione più alta e valutazione più bassa. Ogni pagina live riuscita usa un'unità di richiesta API.

La skill include una sottoscrizione API o quota extra?

Il pacchetto include istruzioni e file helper. Le richieste di dati usano la chiave, gli scope e il diritto della Sua area di lavoro API. REST e MCP condividono la Sua quota API, mentre Online ed Estensione hanno quote separate. Le credenziali di test restituiscono fixture simulati con zero unità di richiesta.

Come aggiorno un'installazione esistente?

Installi in una directory nuova, revisioni il nuovo pacchetto e sostituisca la vecchia versione usando il processo di gestione delle skill del Suo runtime. L'installer non sovrascrive una directory esistente.

Faccia il passo successivo

Collegi gli strumenti dietro la skill.

Configuri il server MCP remoto, tenga la Sua credenziale API nelle impostazioni private del Suo client ed esegua un workflow mirato.