Google Maps Search
Google Maps Search trasforma la query di un’attività, di una categoria o di un luogo, insieme a una posizione obbligatoria, in record pubblici strutturati di luoghi. Ogni risultato salvato usa lo schema PlaceItem indipendente dal provider, così i campi disponibili di identità, indirizzo, contatto, valutazione, numero di recensioni e coordinate possono confluire in sistemi di ricerca e arricchimento senza vincolare i client alle chiavi di risposta specifiche della fonte.
Funzionalità della Google Maps Search API
- Scoperta per query e posizioneCombina una query obbligatoria non vuota, per esempio coffee, con una posizione obbligatoria, per esempio New York, NY, per trovare i luoghi pubblici corrispondenti.
- Controlli geografici facoltativiAggiungi country, una coppia di latitudine e longitudine e zoom_level quando la ricerca richiede un contesto geografico più esplicito; i campi facoltativi omessi non vengono inventati.
- Identità e dati di contatto normalizzati dei luoghiRicevi campi PlaceItem stabili per ID, URL di origine, nomi, categorie, indirizzi, numeri di telefono pubblici, siti web e momento di raccolta, quando disponibili.
- Valutazioni e coordinate geograficheMantieni con ogni luogo le valutazioni, il numero di recensioni, la città, la regione, il paese, la latitudine e la longitudine disponibili, gestendo in sicurezza i campi di origine assenti.
Parametri della Google Maps Search API
| Parametri | Obbligatorio | Descrizione |
|---|---|---|
query | Obbligatorio | Termine di ricerca obbligatorio e non vuoto per un luogo, un’attività o una categoria. |
location | Obbligatorio | Area di ricerca obbligatoria, non vuota e leggibile da una persona, come una città, una regione o un indirizzo. Se entrambe le coordinate sono omesse, viene combinata con la query per la ricerca. |
country | Facoltativo | Nome o codice di un paese, facoltativo e non vuoto, inoltrato come contesto geografico. |
latitude | Facoltativo | Latitudine facoltativa da -90 a 90. Deve essere fornita insieme alla longitudine. |
longitude | Facoltativo | Longitudine facoltativa da -180 a 180. Deve essere fornita insieme alla latitudine. |
zoom_level | Facoltativo | Livello di zoom della mappa facoltativo, intero da 0 a 21. |
results_limit | Facoltativo | Numero massimo di record di luoghi da salvare; il valore predefinito è 100 e accetta interi da 1 a 2.000. |
Come usare la Google Maps Search API
Invia una query e una posizione, segui l’attività asincrona e leggi i record dei luoghi normalizzati con la paginazione a cursore.
- Prepara una query e una posizione non vuote; se vuoi, aggiungi country, coordinate, zoom_level e un results_limit da 1 a 2.000.
- Invia la richiesta con POST a /v1/google-maps/search e salva il task_id restituito.
- Interroga /v1/tasks/{task_id} finché l’attività non ha successo o segnala un errore.
- Leggi data.results.items e passa next_cursor all’endpoint dell’attività finché has_more resta true.
curl -X POST "https://api.socq.ai/v1/google-maps/search" \
-H "Authorization: Bearer $SOCQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{"query":"coffee","location":"New York, NY","country":"US","results_limit":3}'
# Poll GET /v1/tasks/{task_id}
# Read data.results.items and follow next_cursor while has_more is trueCasi d’uso della Google Maps Search API
- Scoperta di attività locali: Costruisci un elenco circoscritto di attività pubbliche che corrispondono a una categoria o a un servizio in una città, un quartiere o un’area indicata da un indirizzo.
- Arricchimento dei dati di posizione: Aggiungi nomi, categorie, indirizzi, telefoni, siti web e coordinate disponibili ai luoghi candidati già presenti in un CRM o in una coda di ricerca.
- Ricerche di mercato e copertura: Confronta numero di luoghi raccolti, categorie, valutazioni e volumi di recensioni tra ricerche geografiche inviate in modo indipendente.
- Preparazione di una selezione di luoghi: Usa URL pubblici, campi di contatto, contesto delle valutazioni e coordinate per scegliere i luoghi da passare a un flusso di verifica o di dettaglio separato.
Consigli degli esperti per la Google Maps Search API
- Usa una categoria o un termine di attività specifico e una città, un quartiere o un indirizzo chiari in location: combinazioni vaghe possono produrre corrispondenze ampie o ambigue.
- Invia country, coordinate o zoom_level solo quando offrono un contesto geografico verificato. Fornisci latitude e longitude insieme e tieni entrambi i valori negli intervalli documentati.
- Tieni results_limit vicino al numero di record che ti servono. Controlla il limite di raccolta, mentre il limit del GET dell’attività controlla quanti record salvati vengono restituiti per pagina di risposta.
- Prosegui con next_cursor finché has_more è false, quando i risultati salvati superano la prima pagina di risposta dell’attività.
- Considera descrizioni, campi di contatto, valutazioni, numero di recensioni e coordinate come dati pubblici facoltativi e conserva collected_at per i confronti puntuali nel tempo.
API correlate
Oltre alla Google Maps Search API, usa queste API quando ti serve un altro tipo di dati pubblici di Google Maps.