MCP Tools Reference: mapstools.googleapis.com

Strumento: search_places

Chiama questo strumento quando la richiesta dell'utente è di trovare luoghi, attività, indirizzi, località, punti di interesse o qualsiasi altra ricerca correlata a Google Maps.

Requisiti di input (CRITICI):

  1. text_query (stringa - OBBLIGATORIO): la query di ricerca principale. Deve definire chiaramente ciò che l'utente sta cercando.

    • Esempi: 'restaurants in New York', 'coffee shops near Golden Gate Park', 'SF MoMA', '1600 Amphitheatre Pkwy, Mountain View, CA, USA', 'pets friendly parks in Manhattan, New York', 'date night restaurants in Chicago', 'accessible public libraries in Los Angeles'.
    • Per dettagli specifici del luogo:includi l'attributo richiesto (ad es. 'Google Store Mountain View opening hours', 'SF MoMa phone number', 'Shoreline Park Mountain View address').

  2. location_bias (oggetto - FACOLTATIVO): utilizzalo per dare la priorità ai risultati vicini a un'area geografica specifica.

    • Formato: {"location_bias": {"circle": {"center": {"latitude": [value], "longitude": [value]}, "radius_meters": [value (optional)]}}}
    • Utilizzo:
      • Per dare la priorità a un raggio di 5 km: {"location_bias": {"circle": {"center": {"latitude": 34.052235, "longitude": -118.243683}, "radius_meters": 5000}}}
      • Per dare una forte preferenza al punto centrale: {"location_bias": {"circle": {"center": {"latitude": 34.052235, "longitude": -118.243683}}}} (omettendo radius_meters).

  3. language_code (stringa - FACOLTATIVO): la lingua in cui mostrare il riepilogo dei risultati di ricerca.

    • Formato:un codice lingua di due lettere (ISO 639-1), facoltativamente seguito da un trattino basso e da un codice paese di due lettere (ISO 3166-1 alpha-2), ad esempio en, ja, en_US, zh_CN, es_MX. Se il codice lingua non viene fornito, i risultati saranno in inglese.

  4. region_code (stringa - FACOLTATIVO): il codice regione CLDR Unicode dell'utente. Questo parametro viene utilizzato per visualizzare i dettagli del luogo, come il nome del luogo specifico per la regione, se disponibile. Il parametro può influire sui risultati in base alla legge vigente.

    • Formato:un codice paese di due lettere (ISO 3166-1 alpha-2), ad es. US, CA.

Istruzioni per la chiamata allo strumento:

  • Informazioni sulla posizione (CRITICHE): la ricerca deve contenere informazioni sulla posizione sufficienti. Se la posizione è ambigua (ad es. solo "pizzerie"), devi specificarla in text_query (ad es. "pizzerie a New York") o utilizza il parametro location_bias. Includi il nome della città, dello stato/provincia e della regione/paese, se necessario per la disambiguazione.

  • Fornisci sempre il text_query più specifico e ricco di contesto possibile.

  • Utilizza location_bias solo se le coordinate sono fornite esplicitamente o se dedurre una posizione dal contesto noto di un utente è appropriato e necessario per ottenere risultati migliori.

Il seguente esempio mostra come utilizzare curl per richiamare lo strumento MCP search_places.

Curl Request 
                  
curl --location 'https://mapstools.googleapis.com/mcp' \
--header 'content-type: application/json' \
--header 'accept: application/json, text/event-stream' \
--data '{
  "method": "tools/call",
  "params": {
    "name": "search_places",
    "arguments": {
      // provide these details according to the tool's MCP specification
    }
  },
  "jsonrpc": "2.0",
  "id": 1
}'

Schema di input

Messaggio di richiesta per SearchText.

SearchTextRequest

Rappresentazione JSON 
{
  "textQuery": string,
  "languageCode": string,
  "regionCode": string,
  "pageSize": integer,
  "pageToken": string,

  // Union field _location_bias can be only one of the following:
  "locationBias": {
    object (LocationBias)
  }
  // End of list of possible types for union field _location_bias.
}
Campi
textQuery

string

Obbligatorio. La query di testo.
languageCode

string

Facoltativo. La lingua in cui richiedere la restituzione del riepilogo. Se il codice lingua non è specificato o non è riconosciuto, verrà restituito il riepilogo con una preferenza per l'inglese.

Ad esempio, "en" per l'inglese.

Elenco attuale delle lingue supportate: https://developers.google.com/maps/faq#languagesupport.
regionCode

string

Facoltativo. Il codice Unicode paese/regione (CLDR) della località da cui proviene la richiesta. Questo parametro viene utilizzato per visualizzare i dettagli del luogo, come il nome del luogo specifico per la regione, se disponibile. Il parametro può influire sui risultati in base alla legge vigente.

Ad esempio, "US" per gli Stati Uniti.

Per ulteriori informazioni, visita la pagina https://www.unicode.org/cldr/charts/latest/supplemental/territory_language_information.html.

Tieni presente che i codici regione a tre cifre non sono attualmente supportati.
pageSize

integer

Facoltativo. Il numero massimo di luoghi da restituire. Il servizio potrebbe restituire un numero inferiore a questo valore.
pageToken

string

Facoltativo. Un token di pagina, ricevuto da una precedente chiamata SearchText. Forniscilo per recuperare la pagina successiva.

Campo unione _location_bias.

_location_bias può essere solo uno dei seguenti tipi:
locationBias

object (LocationBias)

Una regione facoltativa per orientare i risultati di ricerca. Se in text_query è presente una località esplicita, questa verrà utilizzata per orientare i risultati di ricerca anziché questo campo.

LocationBias

Rappresentazione JSON 
{
  "circle": {
    object (Circle)
  }
}
Campi
circle

object (Circle)

Facoltativo. Un cerchio definito dal punto centrale e dal raggio. L'elemento radius_meters è facoltativo. Se non viene impostato, i risultati saranno orientati verso il punto centrale.

Cerchio

Rappresentazione JSON 
{
  "center": {
    object (google.type.LatLng)
  },

  // Union field _radius_meters can be only one of the following:
  "radiusMeters": number
  // End of list of possible types for union field _radius_meters.
}
Campi
center

object (google.type.LatLng)

Obbligatorio. Il punto centrale del cerchio.

Campo unione _radius_meters.

_radius_meters può essere solo uno dei seguenti tipi:
radiusMeters

number

Il raggio del cerchio in metri. Il raggio deve essere inferiore a 50.000 metri.

LatLng

Rappresentazione JSON 
{
  "latitude": number,
  "longitude": number
}
Campi
latitude

number

La latitudine in gradi. Deve essere compresa nell'intervallo [-90,0, +90,0].
longitude

number

La longitudine in gradi. Deve essere compreso nell'intervallo [-180.0, +180.0].

Schema di output

Messaggio di risposta per SearchText.

SearchTextResponse

Rappresentazione JSON 
{
  "places": [
    {
      object (PlaceView)
    }
  ],
  "summary": string,
  "nextPageToken": string
}
Campi
places[]

object (PlaceView)

Solo output. L'elenco dei luoghi menzionati nel riepilogo.
summary

string

Solo output. Un riepilogo in linguaggio naturale dei risultati di ricerca. Il riepilogo può contenere citazioni basate su zero come "[0]", "[1]", "[2]" e così via. Queste citazioni corrispondono ai luoghi corrispondenti nel campo places.
nextPageToken

string

Facoltativo. Un token che può essere inviato come page_token per recuperare la pagina successiva.

PlaceView

Rappresentazione JSON 
{
  "place": string,
  "id": string,
  "googleMapsLinks": {
    object (GoogleMapsLinks)
  },

  // Union field _location can be only one of the following:
  "location": {
    object (google.type.LatLng)
  }
  // End of list of possible types for union field _location.
}
Campi
place

string

Il nome della risorsa del luogo sottostante, nel formato "places/{id}".
id

string

L'ID luogo del luogo sottostante.
googleMapsLinks

object (GoogleMapsLinks)

Link per attivare diverse azioni di Google Maps.

Campo unione _location.

_location può essere solo uno dei seguenti tipi:
location

object (google.type.LatLng)

La posizione di questo luogo.

LatLng

Rappresentazione JSON 
{
  "latitude": number,
  "longitude": number
}
Campi
latitude

number

La latitudine in gradi. Deve essere compresa nell'intervallo [-90,0, +90,0].
longitude

number

La longitudine in gradi. Deve essere compreso nell'intervallo [-180.0, +180.0].
Rappresentazione JSON 
{
  "directionsUrl": string,
  "placeUrl": string,
  "writeAReviewUrl": string,
  "reviewsUrl": string,
  "photosUrl": string
}
Campi
directionsUrl

string

Un link per mostrare le indicazioni stradali per raggiungere il luogo. Il link compila solo la località di destinazione e utilizza la modalità di viaggio predefinita DRIVE.
placeUrl

string

Un link per mostrare questo luogo.
writeAReviewUrl

string

Un link per scrivere una recensione su questo luogo su Google Maps.
reviewsUrl

string

Un link per mostrare le recensioni di questo luogo su Google Maps.
photosUrl

string

Un link per mostrare le recensioni di questo luogo su Google Maps.

Annotazioni dello strumento

Suggerimento distruttivo: ❌ | Suggerimento idempotente: ❌ | Suggerimento di sola lettura: ✅ | Suggerimento open world: ❌