POST /api/v1/search

API di scraping di Google Maps

Trovi attività per parola chiave e località. Riceva fino a 20 record di attività strutturati nella stessa risposta JSON, pronti per la Sua applicazione o il Suo workflow di ricerca.

Esempi di richiesta

Per il contratto completo, consulti la documentazione API.

curl https://gmapscrawl.com/api/v1/search \
  -H "Authorization: Bearer $GMSCRAPER_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: seattle-coffee-search-001" \
  -d '{"q":"coffee shops in Seattle","page":1,"extra":false}'

Risposta vuota illustrativa. Una ricerca live restituisce le attività disponibili. Conservi la Sua chiave API lato server; usi una nuova chiave di idempotenza per nuovo lavoro e la conservi per un retry invariato.

Risposta

JSON illustrativo
{
  "data": {
    "total": 0,
    "params": {
      "q": "coffee shops in Seattle",
      "page": 1,
      "hl": "en",
      "extra": false
    },
    "businesses": []
  },
  "request_id": "req_example",
  "schema_version": "2026-09-22"
}

L'API restituisce JSON nella stessa risposta. Dopo un timeout, riprovi il body invariato con la stessa Idempotency-Key. Le credenziali di test restituiscono dati simulati senza usare la Sua quota live.

Dati strutturati delle attività

Da una ricerca su Maps a record che può usare.

Legga data.businesses dalla risposta. Ogni attività raggruppa i campi della scheda sotto place; la disponibilità dei campi dipende dalla sorgente.

01

Identità e località dell'attività

Usi il nome dell'attività, le categorie, l'indirizzo formattato, le coordinate e l'URL di Maps per organizzare un dataset di attività locali.

02

Contatto e reputazione

Legga numeri di telefono, siti web, valutazioni e conteggi delle recensioni disponibili. Con extra attivo, richieda l'arricchimento dei contatti email e social.

03

Identificatori e date di osservazione

Conservi place.dataId per le ricerche di recensioni e foto. Ispezioni place.observedAt e contactsCheckedAt per capire quando i dati sono stati osservati.

Tenga visibili i dati mancanti e più vecchi

I campi non disponibili possono essere null o vuoti, e l'arricchimento può riportare not_found o failed. Un record non garantisce l'esistenza di un indirizzo email o di un sito web. I dettagli di Maps possono essere riutilizzati fino a 730 giorni con i timestamp di osservazione originali; valuti la freschezza prima di usare un record.

Legga sulla freschezza dei dati →

Una richiesta mirata

Scelga la query, la pagina e l'arricchimento.

Invii un body JSON con la Sua chiave API lato server nell'header di autorizzazione. Solo q è obbligatorio.

Parametri della Google Maps Search API
ParametroRequisitoScopo
qObbligatorioUna parola chiave di attività e una località, come caffetterie a Seattle. Usi da 2 a 200 caratteri.
pagePredefinito: 1Una pagina di ricerca numerata da 1 a 10. Ogni richiesta restituisce al massimo 20 attività.
llOpzionaleUn viewport di Maps nella forma @47.6062,-122.3321,12z per guidare la località della ricerca.
hlPredefinito: enIl codice lingua usato per la ricerca.
glOpzionaleUn codice paese di due lettere che qualifica la query. Non è un filtro geografico rigido.
extraPredefinito: falseLo imposti su true per richiedere l'arricchimento dei contatti email e social disponibile. Può richiedere più tempo.

La risposta riporta i parametri normalizzati in data.params. Il valore data.total conta le attività in questa risposta, non il numero totale di attività su Google Maps. Scelga esplicitamente un'altra pagina quando il Suo workflow ha bisogno di più risultati.

Costruisca la Sua prima integrazione

Una richiesta. Un passo successivo utile.

L'API Search è sincrona: legga il risultato direttamente dalla risposta HTTP.

01

Crei la Sua chiave API

Usi la Sua area di lavoro API per creare una chiave con il permesso scrapes:write. Conservi la chiave nell'ambiente del Suo server e invii Authorization: Bearer con la richiesta.

Apra le chiavi API
02

Cerchi in un'area delimitata

Scelga una categoria e una località, richieda la pagina 1 e ispezioni i campi della scheda restituiti. Per un confronto di mercato, emetta ricerche separate per le aree che vuole confrontare.

03

Segua un identificatore di luogo

Usi place.dataId di un'attività corrispondente come fid per recuperare una pagina di recensioni o una pagina di galleria. Sono richieste separate con i propri record restituiti.

Esplori l'API Reviews

Pianifichi per richieste reali

Pagine prevedibili, limiti espliciti.

Uso e disponibilità

Ogni pagina di ricerca live riuscita usa un'unità di richiesta API, incluso un risultato vuoto. REST e MCP condividono la quota API. Le sottoscrizioni dello scraper Online e dell'Estensione hanno quote separate. Si applicano comunque rate limit, credenziali, capacità del servizio e disponibilità della sorgente.

Confronti i piani API →

Timeout e retry

Consenta fino a 180 secondi nel Suo client HTTP. Un timeout può lasciare lavoro in elaborazione con un'unità di richiesta riservata. Riutilizzi il body identico e la Idempotency-Key per riprovare quella richiesta. Controlli i dettagli dell'errore e la possibilità di retry prima di iniziare un nuovo tentativo.

Comprenda i retry →

Continui il Suo workflow

Altri modi per usare gli stessi dati delle attività.

01

Dati di recensioni e galleria

Recuperi recensioni pubbliche o metadati di foto e video di un luogo usando il suo feature ID.

Esplori i dati della galleria
02

Collegi un client MCP

Permetta a un client AI compatibile di scoprire gli strumenti di ricerca, recensioni e foto con le Sue credenziali API.

Configuri MCP
03

Installi l'Agent Skill

Dia al Suo agente istruzioni di workflow, riferimenti delle operazioni e un fallback REST per la ricerca su Google Maps.

Esplori la skill

Domande frequenti

Cosa restituisce l'API di scraping di Google Maps?

Restituisce un envelope JSON con data.businesses, data.total, data.params normalizzati, request_id e schema_version. Le attività includono i campi della scheda disponibili come nomi, indirizzi, categorie, informazioni di contatto, valutazioni e identificatori di Maps.

Posso usare l'API da Python o JavaScript?

Sì. L'endpoint accetta richieste HTTP POST standard con JSON e autenticazione Bearer. Gli esempi sopra usano la libreria standard di Python e fetch di JavaScript lato server. Qualsiasi client HTTP che possa inviare quegli header e quel body può integrarsi.

Quante attività può restituire una richiesta?

Una pagina di ricerca restituisce da zero a 20 attività. Il parametro page accetta valori da 1 a 10. Ogni pagina live riuscita, inclusa una pagina vuota, usa un'unità di richiesta API; una ricerca non garantisce che ogni pagina contenga 20 attività.

Posso recuperare singole recensioni e foto?

Sì. Copi place.dataId da un'attività e lo passi come fid all'API separata Reviews o Photos. Quegli endpoint restituiscono una pagina delimitata per richiesta. La panoramica API rimanda a campi, esempi e regole di paginazione di ogni endpoint.

Gli indirizzi email sono inclusi per ogni attività?

No. Imposti extra su true per richiedere l'arricchimento dei contatti disponibile. Siti web, email e profili social possono mancare. Ispezioni enrichmentState e fieldStates e mantenga espliciti i dati non disponibili nella Sua applicazione.

Come dovrei testare un'integrazione?

Se ha una credenziale di test, le sue risposte sono simulate e non consumano quota API live. Etichetti quei risultati come simulati. Le chiavi live richiedono un diritto API attivo e capacità del servizio disponibile, e le chiamate live riuscite usano unità di richiesta.

Faccia il passo successivo

Costruisca la Sua prima ricerca su Google Maps.

Crei una chiave API, scelga una query e una località, e legga dati di attività strutturati nella stessa risposta.