Dati di Google Maps / Server MCP

Dati di Google Maps, dentro il Suo workflow AI.

Trovi attività, legga recensioni pubbliche ed esplori le gallerie dei luoghi con Claude Code, Cursor, VS Code o Codex. Tre strumenti remoti. La stessa chiave API.

Funziona con il Suo client MCP

HTTP Streamable remoto · Chiave API privata · Piani API gratuiti e a pagamento

Tre strumenti / Una connessione

Dalla scoperta delle attività al dettaglio del luogo.

Ogni strumento restituisce il suo risultato direttamente. Scelga l'operazione di cui la Sua attività ha bisogno e mantenga esplicite le pagine richieste.

Trovi attività

search_google_maps

Cerchi una categoria e una località. Riceva fino a 20 attività con i campi disponibili di scheda, contatto, valutazione e conteggio delle recensioni.

q · page · extra

Esplori l'API Search

Legga recensioni pubbliche

get_google_maps_reviews

Usi il feature ID di un luogo per richiedere fino a 10 recensioni. Scelga rilevanza, più recenti, valutazione più alta o valutazione più bassa.

fid · page · sort_by

Esplori l'API Reviews

Sfoghi i media della galleria

get_google_maps_photos

Recuperi fino a 20 record di metadati di foto e video per un luogo. Legga gli URL dei media restituiti e il flag di paginazione.

fid · page

Esplori l'API Photos

Reviews e Photos accettano il feature ID di Maps dal place.dataId di un risultato di ricerca. Search usa le pagine 1–10; gli strumenti media restituiscono next così il Suo agente può decidere se serve un'altra pagina.

Connessione MCP

Un endpoint. La Sua area di lavoro API.

Il Suo client gestisce l'inizializzazione e la scoperta degli strumenti, poi invia la Sua chiave API con ogni richiesta.

Connessione MCP remota
POST https://gmapscrawl.com/api/mcp
Authorization: Bearer <YOUR_API_KEY>
Content-Type: application/json
Accept: application/json, text/event-stream

Configurazione del client

Scelga il client in cui lavora.

Crei una chiave API, poi copi la configurazione per il Suo client. Conservi la chiave nel suo ambiente o nell'impostazione di input protetta.

Aggiunga questo server a .mcp.json. Renda GMSCRAPER_API_KEY disponibile nell'ambiente che avvia Claude Code.

{
  "mcpServers": {
    "google-maps-data": {
      "type": "http",
      "url": "https://gmapscrawl.com/api/mcp",
      "headers": {
        "Authorization": "Bearer ${GMSCRAPER_API_KEY}"
      }
    }
  }
}
Documentazione di Claude Code ↗

Dopo aver salvato la configurazione, riconnetta e confermi che i tre strumenti appaiono. Segua la guida di configurazione passo passo.

Il Suo primo workflow

Si colleghi. Testi una pagina. Legga il risultato.

Inizi con una chiave di test e dati simulati. Passi a una chiave live quando è pronto a usare la Sua quota API.

01

Prepari la Sua area di lavoro

Selezioni il prodotto API e crei una chiave di test con scrapes:write. Il Suo piano API deve consentire MCP; Online ed Estensione hanno quote separate.

Crei una chiave
02

Scopra e chiami uno strumento

Collegi il Suo client, ispezioni search_google_maps e chieda una pagina. Generi un ID di richiesta nuovo per nuovo lavoro e lo conservi quando riprova la stessa richiesta.

Veda la configurazione del client
03

Usi le attività restituite

Legga structuredContent.businesses e total. Etichetti i risultati di test come simulati, conservi i valori mancanti e si fermi dopo la pagina richiesta.

Comprenda i campi
Chiami search_google_maps

Sostituisca l'ID di richiesta per ogni nuova ricerca. Questo esempio non esegue una richiesta dalla pagina.

{
  "q": "coffee shops in Seattle",
  "page": 1,
  "hl": "en",
  "extra": false,
  "client_request_id": "replace-with-a-fresh-uuid"
}

Cosa torna

Record strutturati, nella stessa risposta dello strumento.

businesses
Fino a 20 attività restituite; alcuni campi possono mancare.
params + total
La query normalizzata e il conteggio su questa pagina.
simulated + usage metadata
Le risposte di test identificano dati fixture e usano zero unità di richiesta live.
isError
Ispezioni l'errore prima di segnalare che uno strumento è riuscito.

I risultati tornano direttamente; non serve polling di job. Conservi le date di osservazione della sorgente quando trasforma il JSON in una tabella o un report.

Prompt di esempio

Una domanda utile. Un punto di arresto chiaro.

Usi questi prompt dopo la connessione. Fornisca un feature ID reale dove necessario e chieda al Suo agente di etichettare i risultati di test come simulati.

Costruisca una lista di attività mirata

“Usi search_google_maps una volta per caffetterie a Seattle, pagina 1, extra false. Restituisca nomi, siti web, numeri di telefono, valutazioni e conteggi delle recensioni delle attività restituite. Lasci vuoti i campi mancanti e mostri le date di osservazione. Si fermi dopo questa pagina.”

Risultato atteso

Una tabella di fino a 20 attività restituite, con timestamp di origine e valori mancanti conservati.

Riassuma una pagina di recensioni

“Per l'attività che ho selezionato, usi il suo place.dataId come fid. Richieda la pagina 1 di get_google_maps_reviews con sort_by 2. Riassuma i temi solo di queste recensioni restituite e citi le loro date. Non recuperi pagine aggiuntive.”

Risultato atteso

Un riepilogo delimitato di fino a 10 recensioni, senza trattare una pagina come l'esperienza di tutti i clienti.

Ispezioni una galleria

“Usi get_google_maps_photos per questo feature ID fornito, solo pagina 1. Elenco i campi photoUrl restituiti e i videoUrl opzionali e segnali se next è true. Non scarichi file né recuperi la pagina successiva.”

Risultato atteso

Fino a 20 record di galleria e lo stato di paginazione restituito, pronti per l'ispezione della Sua applicazione.

REST + MCP

Una quota API su entrambe le interfacce.

MCP è disponibile sui piani API gratuiti e a pagamento. Ogni pagina di origine live riuscita usa un'unità di richiesta API, inclusa una pagina vuota.

01

Testi senza uso live

Le chiavi di test restituiscono fixture simulati con zero unità di richiesta. Verificano la Sua integrazione invece di produrre lead di attività reali.

Gestisca le chiavi API
02

Mantenga le richieste delimitate

Chieda solo le pagine e le località di cui la Sua attività ha bisogno. Usi un nuovo ID di richiesta per nuovo lavoro; riprovi le richieste incerte con lo stesso input e ID.

Legga la guida all'uso
03

Aggiunga istruzioni riutilizzabili

L'Agent Skill di Google Maps Data aggiunge guida di workflow, riferimenti delle operazioni e un fallback REST agli stessi strumenti.

Esplori l'Agent Skill

Esplori l'hub API → I piani Online ed Estensione hanno le proprie quote.

Aiuto per la connessione

Arrivi alla prossima richiesta riuscita.

Usi lo stato della connessione e l'errore restituito per scegliere il passo successivo.

Il client si connette ma non appare nessuno strumento
Confermi che l'endpoint è /api/mcp e che il Suo client supporta HTTP Streamable remoto con un header Authorization privato. Ricarichi la connessione e controlli che il suo processo possa leggere la chiave configurata.
401 o 403
Controlli la scadenza della chiave, gli IP consentiti, l'accesso attivo all'area di lavoro, lo scope scrapes:write e un piano API che consenta MCP. I cookie di accesso del browser non autenticano l'endpoint.
invalid_request
Legga lo schema dello strumento selezionato. Fornisca un client_request_id univoco di 16–128 caratteri; reviews e photos hanno anche bisogno del FID da place.dataId, invece di un nome di attività o di un altro identificatore di luogo.
rate_limited o quota_exceeded
Rispetti retry_after per i rate limit. Si fermi quando la quota API è esaurita e controlli il Suo uso API; creare un'altra chiave non aggiunge quota.
capability_unavailable o un fallimento della sorgente
Controlli lo stato del servizio e l'errore restituito. La disponibilità è determinata dal server. Mantenga espliciti i dati mancanti o non disponibili nel Suo risultato.
Timeout o isError: true
Ispezioni l'errore dello strumento anche quando la connessione HTTP è riuscita. Per i fallimenti per cui è possibile riprovare, mantenga lo stesso input e lo stesso ID di richiesta entro la scadenza della Sua attività. Segua la guida sugli errori terminali prima di iniziare un nuovo tentativo.

Stato del servizio Errori e guida ai retry

Domande frequenti

Cosa può fare il server MCP di Google Maps?

Espone search_google_maps, get_google_maps_reviews e get_google_maps_photos. La ricerca restituisce fino a 20 attività; le recensioni restituiscono fino a 10 record e le foto fino a 20 record di galleria per pagina. Gli strumenti restituiscono dati strutturati direttamente.

Quali client posso collegare?

Usi una versione di Claude Code, Cursor, VS Code, Codex o un altro client MCP che supporti HTTP Streamable remoto e un header Authorization privato. Le quattro configurazioni client sopra usano lo stesso endpoint e la chiave dell'area di lavoro API.

Come mi autentico?

Crei una chiave API con scrapes:write nella Sua area di lavoro API e la configuri privatamente come header Bearer. I cookie del browser non autenticano MCP. Tenga le chiavi fuori da prompt, URL e codice sorgente committato.

Come trovano reviews e photos il luogo giusto?

Passi il feature ID di Maps come fid. Può usare place.dataId di un'attività restituita. Reviews accetta anche sort_by: 1 per rilevanza, 2 per più recenti, 3 per valutazione più alta o 4 per valutazione più bassa. Legga next prima di considerare un'altra pagina di media.

MCP ha una quota separata?

MCP condivide la quota dell'API REST ed è disponibile sui piani API gratuiti e a pagamento. Una pagina live riuscita usa un'unità di richiesta, inclusa una pagina vuota. Le credenziali di test restituiscono dati simulati con zero unità. Le quote Online ed Estensione sono separate.

Ho bisogno anche dell'Agent Skill?

Il server MCP funziona da solo. L'Agent Skill di Google Maps Data opzionale aggiunge istruzioni riutilizzabili, riferimenti delle operazioni e un helper di fallback REST per quando la Sua connessione MCP configurata non è disponibile.

Faccia il passo successivo

Porti i dati di Google Maps nella Sua prossima conversazione.

Crei una chiave API, colleghi il Suo client preferito e testi una ricerca di attività mirata.