google-maps/
search

Cerca luoghi pubblici di Google Maps per query e posizione, con nomi, categorie, indirizzi, dati di contatto, valutazioni, numero di recensioni, URL e coordinate normalizzati.

Google Maps Search API

Input di query e posizione
Contesto geografico facoltativo
Da 1 a 2.000 risultati richiesti
Record di luoghi normalizzati
0,15 crediti per risultato
Pronto
Pronto

Inserisci i parametri e invia una richiesta. Qui compariranno lo stato dell’attività e i risultati normalizzati.

README

A cura di SocQ · Aggiornato il

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

ParametriObbligatorioDescrizione
queryObbligatorioTermine di ricerca obbligatorio e non vuoto per un luogo, un’attività o una categoria.
locationObbligatorioArea 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.
countryFacoltativoNome o codice di un paese, facoltativo e non vuoto, inoltrato come contesto geografico.
latitudeFacoltativoLatitudine facoltativa da -90 a 90. Deve essere fornita insieme alla longitudine.
longitudeFacoltativoLongitudine facoltativa da -180 a 180. Deve essere fornita insieme alla latitudine.
zoom_levelFacoltativoLivello di zoom della mappa facoltativo, intero da 0 a 21.
results_limitFacoltativoNumero 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.

  1. Prepara una query e una posizione non vuote; se vuoi, aggiungi country, coordinate, zoom_level e un results_limit da 1 a 2.000.
  2. Invia la richiesta con POST a /v1/google-maps/search e salva il task_id restituito.
  3. Interroga /v1/tasks/{task_id} finché l’attività non ha successo o segnala un errore.
  4. 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 true

Casi 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.

Oltre alla Google Maps Search API, usa queste API quando ti serve un altro tipo di dati pubblici di Google Maps.

Esplora altre piattaforme

Combina i dati di Google Maps con i dati pubblici delle altre piattaforme social supportate.

Google Maps Search API — FAQ

Google Maps Search API è un’interfaccia asincrona per scoprire luoghi pubblici a partire da una query e da una posizione obbligatorie. Restituisce record PlaceItem indipendenti dal provider, con i campi disponibili di identità, categoria, indirizzo, contatto, valutazione, numero di recensioni, URL e posizione geografica.

query e location sono entrambe stringhe obbligatorie e non vuote. country, latitude, longitude, zoom_level e results_limit sono facoltativi.

Sì. La specifica attuale della richiesta accetta le coordinate solo in coppia. Omettile entrambe per combinare location con query, oppure fornisci latitude da -90 a 90 insieme a longitude da -180 a 180.

results_limit è un massimo di raccolta, non una garanzia. La fonte può restituire meno corrispondenze pubbliche e i record con la stessa identità esposta vengono salvati una sola volta per attività.

Un risultato pubblico può non avere descrizione, categoria, indirizzo, telefono, sito web, valutazione, numero di recensioni, URL o alcuni campi di posizione. I client devono gestire i valori null senza considerarli errori dell’attività.

Ogni record di luogo salvato costa 0,15 crediti SocQ. L’addebito preventivo usa results_limit, o 100 se omesso; dopo il successo l’utilizzo viene regolato sul numero effettivo di risultati salvati e un insieme di risultati vuoto non ha alcun costo per i risultati.