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 generato dall'AI dei luoghi corrispondenti.
Per ogni luogo citato nel riepilogo, restituisce anche l'ID luogo, le coordinate di latitudine/longitudine, i link a Google Maps e l'attribuzione.
Puoi chiamare search_places tramite il server MCP o come metodo REST searchText. Questa pagina descrive le opzioni di richiesta, incluse le opzioni Pro, i contenuti della risposta e la modalità di fatturazione delle richieste. Per gli schemi completi, consulta il riferimento MCP search_places e il riferimento REST searchText.
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.
La tabella seguente descrive le opzioni di richiesta per search_places:
| 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 quella località. |
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 Place Details estesi. Questa è un'opzione Pro. Il valore predefinito è false. |
Opzioni Pro
Due opzioni selezionano lo SKU Maps Grounding Pro. Una richiesta che utilizza uno o entrambi 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, punti salienti del menu, atmosfera o suggerimenti per i 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.
Extended Place Details
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 insight 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 attinge a più dati di Google Maps, inclusi gli approfondimenti delle recensioni. Le voci places strutturate sono le stesse per entrambi gli SKU.
Esempio
La seguente richiesta MCP 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
}
L'esempio seguente invia la stessa richiesta al metodo REST searchText:
curl -X POST \
-H "Content-Type: application/json" \
-H "X-Goog-Api-Key: API_KEY" \
-d '{
"textQuery": "date night Italian restaurants in Chicago",
"pageSize": 8,
"includeExtendedDetails": true
}' \
"https://mapstools.googleapis.com/v1:searchText"
Sostituisci API_KEY con la tua chiave API.
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 i seguenti campi:
summary: un riepilogo in linguaggio naturale dei risultati di ricerca. Potrebbe contenere citazioni in base zero, come[0], che corrispondono alle voci inplaces.places[]: i luoghi menzionati nel riepilogo. Ogni luogo include:place: il nome della risorsa del luogo, nel formatoplaces/{id}.id: l'ID luogo. Puoi utilizzarlo con altre API di Google Maps Platform, ad esempio per mostrare il luogo su una mappa.location: le coordinate di latitudine/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.
contentToken: un token di visualizzazione dei dati agentico (anteprima) che ti consente di visualizzare i luoghi nella risposta con Places UI Kit senza costi aggiuntivi. Viene restituito quando la risposta include almeno un luogo.
La risposta ha la stessa struttura per entrambi gli SKU e per MCP e REST. Per i dettagli dei campi, consulta il riferimento search_places.
Fatturazione e quote
Ogni richiesta search_places è un evento fatturabile:
- Una richiesta che non utilizza opzioni Pro viene fatturata in base allo SKU Maps Grounding Essentials.
- Una richiesta che utilizza un'opzione Pro viene fatturata in base allo SKU Maps Grounding 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.
Se mostri i luoghi di una risposta search_places con Places UI Kit, puoi utilizzare il token di visualizzazione dei dati agentica (anteprima) in modo che le richieste di Places UI Kit non vengano fatturate.
La quota di search_places è di 300 query al minuto per ogni progetto, condivisa da entrambi gli SKU. Per i prezzi, consulta la tabella dei prezzi principale e la tabella dei prezzi per l'India.