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.
POST /api/v1/search
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.
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.
{
"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à
Legga data.businesses dalla risposta. Ogni attività raggruppa i campi della scheda sotto place; la disponibilità dei campi dipende dalla sorgente.
Usi il nome dell'attività, le categorie, l'indirizzo formattato, le coordinate e l'URL di Maps per organizzare un dataset di attività locali.
Legga numeri di telefono, siti web, valutazioni e conteggi delle recensioni disponibili. Con extra attivo, richieda l'arricchimento dei contatti email e social.
Conservi place.dataId per le ricerche di recensioni e foto. Ispezioni place.observedAt e contactsCheckedAt per capire quando i dati sono stati osservati.
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
Invii un body JSON con la Sua chiave API lato server nell'header di autorizzazione. Solo q è obbligatorio.
| Parametro | Requisito | Scopo |
|---|---|---|
| q | Obbligatorio | Una parola chiave di attività e una località, come caffetterie a Seattle. Usi da 2 a 200 caratteri. |
| page | Predefinito: 1 | Una pagina di ricerca numerata da 1 a 10. Ogni richiesta restituisce al massimo 20 attività. |
| ll | Opzionale | Un viewport di Maps nella forma @47.6062,-122.3321,12z per guidare la località della ricerca. |
| hl | Predefinito: en | Il codice lingua usato per la ricerca. |
| gl | Opzionale | Un codice paese di due lettere che qualifica la query. Non è un filtro geografico rigido. |
| extra | Predefinito: false | Lo 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
L'API Search è sincrona: legga il risultato direttamente dalla risposta HTTP.
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 APIScelga 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.
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 ReviewsPianifichi per richieste reali
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 →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
Recuperi recensioni pubbliche o metadati di foto e video di un luogo usando il suo feature ID.
Esplori i dati della galleriaPermetta a un client AI compatibile di scoprire gli strumenti di ricerca, recensioni e foto con le Sue credenziali API.
Configuri MCPDia al Suo agente istruzioni di workflow, riferimenti delle operazioni e un fallback REST per la ricerca su Google Maps.
Esplori la skillRestituisce 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.
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.
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à.
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.
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.
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
Crei una chiave API, scelga una query e una località, e legga dati di attività strutturati nella stessa risposta.