Cerca luoghi

Lo strumento search_places consente a un LLM di trovare luoghi su Google Maps da una query in linguaggio naturale. Lo strumento restituisce un riepilogo dei luoghi corrispondenti generato dall'AI. Per ogni luogo citato nel riepilogo, restituisce anche l'ID luogo, le coordinate, i link a Google Maps e l'attribuzione.

Questa pagina descrive le opzioni di richiesta, incluse le opzioni Pro, il contenuto della risposta e la modalità di fatturazione delle richieste. Per lo schema completo dello strumento, consulta il riferimento search_places.

Opzioni di richiesta

L'LLM imposta queste opzioni quando chiama lo strumento, in base alla richiesta dell'utente e alla descrizione dello strumento. Puoi influenzare le opzioni utilizzate dal modello con le tue istruzioni; consulta Controlla l'utilizzo di Pro.

Opzione	Descrizione
text_query	Obbligatorio. La query di ricerca, ad esempio coffee shops near Golden Gate Park. La query deve contenere dati sulla posizione sufficienti per essere univoca oppure la richiesta deve includere location_bias.
location_bias	Un cerchio (center e radius_meters facoltativo, fino a 50.000 metri) verso cui orientare i risultati. Se text_query indica una località esplicita, viene utilizzata quest'ultima.
language_code	La lingua del riepilogo, ad esempio en o ja. Il valore predefinito è l'inglese.
region_code	Il codice regione CLDR dell'utente, ad esempio US. Influisce sui nomi dei luoghi specifici della regione e può influire sui risultati in base alla legge vigente.
page_size	Il numero massimo di luoghi da restituire. Il valore predefinito è 5. I valori da 6 a 10 sono un'opzione Pro. I valori superiori a 10 restituiscono un errore INVALID_ARGUMENT. Il servizio potrebbe restituire meno luoghi di quelli richiesti.
include_extended_details	Quando true, il riepilogo include i dettagli estesi del luogo. Questa è un'opzione Pro. Il valore predefinito è false.

Opzioni Pro

Due opzioni selezionano lo SKU Pro. Una richiesta che utilizza uno o entrambi i parametri viene fatturata con lo SKU Pro:

Opzione Pro	Quando utilizzarla
include_extended_details impostato su true	La richiesta dell'utente richiede Place Details estesi, ad esempio approfondimenti dalle recensioni, piatti in evidenza del menu, atmosfera o suggerimenti dei visitatori.
page_size da 6 a 10	L'utente vuole confrontare più di 5 luoghi.

Le richieste che non utilizzano nessuna delle due opzioni, incluse quelle con un page_size compreso tra 1 e 5, vengono fatturate in base allo SKU Essentials.

Dettagli estesi del luogo

Imposta include_extended_details su true quando la richiesta dell'utente richiede insight qualitativi, condizioni in tempo reale o attributi specializzati, ad esempio:

• Cosa dicono i recensori: approfondimenti basati sulle recensioni, sentiment dei clienti e feedback.
• Offerte specifiche: voci di menu, piatti, specialità gastronomiche, bevande o caratteristiche dell'attività.
• Atmosfera: arredamento, estetica, ambiente o atmosfera.
• Consigli pratici per i visitatori: se è necessario prenotare in anticipo, norme per l'ingresso senza prenotazione, tempi di attesa, affollamento del luogo, parcheggio e servizi.
• Vicinanza: distanza o tempo di percorrenza dalla località della query o dal centro di location_bias, quando l'utente chiede cosa si trova nelle vicinanze o più vicino.

Gli approfondimenti di un riepilogo dipendono dalla query e dai dati disponibili per ogni luogo. Non tutti i tipi di insight vengono visualizzati in ogni risposta.

Lascia false (impostazione predefinita) per le ricerche standard: tipi di cucina o di negozio, indirizzi, dati di contatto, orari di apertura e servizi standard. Le richieste con dettagli estesi richiedono più tempo per essere completate.

I dettagli estesi non modificano la struttura della risposta. Senza, il riepilogo descrive ogni luogo in una o due frasi. In questo modo, ogni luogo riceve una descrizione più lunga che si basa su più dati di Google Maps, tra cui gli approfondimenti delle recensioni. Le voci places strutturate sono le stesse per entrambi gli SKU.

Nota: i riepiloghi che includono approfondimenti dalle recensioni sono soggetti ai requisiti di attribuzione per le fonti di Google Maps. Ogni luogo nella risposta include googleMapsLinks.reviewsUrl, che rimanda alle recensioni del luogo su Google Maps.

Esempio

La seguente richiesta richiede fino a 8 luoghi con dettagli estesi. Viene fatturato con lo SKU Pro:

{
  "method": "tools/call",
  "params": {
    "name": "search_places",
    "arguments": {
      "text_query": "date night Italian restaurants in Chicago",
      "page_size": 8,
      "include_extended_details": true
    }
  },
  "jsonrpc": "2.0",
  "id": 1
}

Senza dettagli estesi, il riepilogo descrive ogni luogo in una o due frasi:

Trattoria di esempio [0] (4,6★ (1250) · 123 W Example St · $$$) A neighborhood trattoria known for handmade pasta and a long wine list.

With extended details, the summary adds what reviewers highlight and practical tips:

Example Trattoria [0] (4.6★ (1,250) · 123 W Example St · $$$) Una sala da pranzo intima a lume di candela che i recensori descrivono come romantica, ma rumorosa nei fine settimana. I piatti più apprezzati sono le tagliatelle al ragù, la burrata e il tiramisù. È consigliata la prenotazione. I clienti senza prenotazione possono aspettarsi un'attesa di 30-45 minuti il venerdì e il sabato sera. Il parcheggio in strada è limitato.

Risposta

La risposta contiene:

• summary: un riepilogo in linguaggio naturale dei risultati di ricerca. Può contenere citazioni basate su zero, come [0], che rimandano alle voci in places.
• places[]: i luoghi menzionati nel riepilogo. Ogni luogo include:
  • place: il nome della risorsa del luogo, nel formato places/{id}.
  • id: l'ID luogo. Puoi utilizzarlo con altre API di Google Maps Platform, ad esempio per mostrare il luogo su una mappa.
  • location: la latitudine e la longitudine del luogo.
  • googleMapsLinks: link di Google Maps per il luogo (placeUrl), le indicazioni stradali (directionsUrl), le recensioni (reviewsUrl), le foto (photosUrl) e la scrittura di una recensione (writeAReviewUrl).
  • attribution: l'attribuzione che devi mostrare con il luogo. Consulta i requisiti di attribuzione.

La risposta ha la stessa struttura per entrambi gli SKU. Per i dettagli dei campi, consulta il riferimento search_places.

Opzioni Pro durante la disponibilità generale limitata

Durante la fase di disponibilità generale limitata, le opzioni Pro sono disponibili solo per i progetti inclusi nella lista consentita Pro. Se il tuo progetto non è ancora nella lista consentita, le opzioni Pro vengono ignorate anziché rifiutate:

• include_extended_details viene trattato come false.
• I valori page_size superiori a 5, inclusi quelli superiori a 10, vengono ridotti a 5.

La richiesta viene fatturata in base allo SKU Essentials. Per richiedere l'accesso, consulta Opzioni Pro durante la disponibilità generale limitata.

Fatturazione e quote

Ogni richiesta search_places è un evento fatturabile:

• Una richiesta che non utilizza opzioni Pro viene fatturata in base allo SKU Essentials.
• Una richiesta che utilizza un'opzione Pro viene fatturata in base allo SKU Pro. L'utilizzo di entrambe le opzioni in un'unica richiesta non modifica l'addebito. Per i prezzi di Pro, consulta Confronta Essentials, Pro e Grounding con Google Maps.

La quota di search_places è di 300 query al minuto per progetto, condivisa da entrambi gli SKU. Per i prezzi, consulta la tabella dei prezzi principale e la tabella dei prezzi per l'India.