MCP Tools Reference: mapstools.googleapis.com

Strumento: resolve_names

Risolve un elenco batch di query su località specifiche (nomi di punti di riferimento o indirizzi esatti) in ID luogo canonici di Google Maps.

Requisiti di input (CRITICI):

  1. queries (array di oggetti - OBBLIGATORIO): un elenco di query sulla posizione da risolvere. Puoi specificare fino a 20 query.

    • Ogni oggetto query deve avere:
      • text (stringa - OBBLIGATORIO): la query di testo che rappresenta un nome di luogo o un indirizzo specifico da risolvere.
        • Esempi: 'Googleplex, Mountain View, CA', '1600 Amphitheatre Pkwy, Mountain View, CA', 'Eiffel Tower, Paris'.

  2. location_bias (oggetto - FACOLTATIVO): utilizza questo campo per dare la priorità ai risultati vicino a un'area geografica specifica.

    • Formato: {"viewport": {"low": {"latitude": [value], "longitude": [value]}, "high": {"latitude": [value], "longitude": [value]}}}

  3. region_code (stringa - FACOLTATIVO): il codice regione Unicode CLDR (codice paese di due lettere, ad es. US, CA) dell'utente per orientare i risultati.

Istruzioni per la chiamata allo strumento:

  • Specificità (CRITICO): le query devono rappresentare un nome o un indirizzo di un luogo specifico. Le ricerche generiche come 'restaurants' o i nomi di catene come 'Starbucks' non sono supportate.
  • NON chiamare questo strumento se gli strumenti downstream che prevedi di richiamare accettano già direttamente stringhe di indirizzi o nomi di luoghi non elaborate.

Gestione degli errori (CRITICO):

  • Si tratta di uno strumento di elaborazione batch. Una richiesta potrebbe restituire "risultati misti" (ad esempio, alcune query vengono risolte correttamente, mentre altre non riescono).
  • È garantito che l'elenco di output di results corrisponda in modo univoco agli indici di input queries. Una query non riuscita genererà un messaggio Result vuoto (non è impostato alcun entity) nel relativo indice dell'elenco results.
  • DEVI controllare il campo della mappa failed_requests nella risposta per identificare l'indice di query specifico non riuscito. La chiave di failed_requests rappresenta l'indice in base zero della query non riuscita nella richiesta. Non presupporre che l'intera chiamata batch non sia riuscita a causa di un errore parziale.

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

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": "resolve_names",
    "arguments": {
      // provide these details according to the tool's MCP specification
    }
  },
  "jsonrpc": "2.0",
  "id": 1
}'

Schema di input

Messaggio di richiesta per ResolveNames.

ResolveNamesRequest

Rappresentazione JSON 
{
  "queries": [
    {
      object (LocationQuery)
    }
  ],
  "locationBias": {
    object (LocationBias)
  },
  "regionCode": string
}
Campi
queries[]

object (LocationQuery)

Obbligatorio. Un elenco di query sulla posizione da risolvere. Puoi specificare fino a 20 query.
locationBias

object (LocationBias)

Facoltativo. Una regione facoltativa per orientare i risultati della risoluzione. Se specificato, i risultati della risoluzione saranno orientati verso le entità più vicine a questa regione. L'inclusione di location_bias o region_code spesso fornisce risultati migliori restringendo lo spazio di ricerca.

Se vengono specificati sia location_bias che region_code, location_bias ha la precedenza su region_code.
regionCode

string

Facoltativo. Un codice regione facoltativo per influenzare i risultati della risoluzione. Se specificato, i risultati della risoluzione saranno orientati verso le entità che si trovano all'interno o nelle vicinanze della regione specificata. Deve essere un codice regione CLDR. Ad esempio, "US" o "CA". L'inclusione di location_bias o region_code spesso fornisce risultati migliori restringendo lo spazio di ricerca.

Se vengono specificati sia location_bias che region_code, location_bias ha la precedenza su region_code.

LocationQuery

Rappresentazione JSON 
{
  "text": string
}
Campi
text

string

Obbligatorio. La query di testo da risolvere in un'entità geospaziale specifica su Google Maps, ad esempio un luogo o un indirizzo. Più specifica è la query, più accurata è la risoluzione. Ad esempio, "San Francisco", "Googleplex, Mountain View, CA", "1600 Amphitheatre Parkway, Mountain View, CA" o "Torre Eiffel, Parigi". Le query devono essere un indirizzo o il nome di un luogo specifici. Le località generiche come il nome di una catena (ad es. Starbucks) o una query di ricerca come "ristoranti" non sono supportate.

LocationBias

Rappresentazione JSON 
{

  // Union field type can be only one of the following:
  "viewport": {
    object (Viewport)
  }
  // End of list of possible types for union field type.
}
Campi
Campo unione type. Il tipo di aggiustamento della località. type può essere solo uno dei seguenti tipi:
viewport

object (Viewport)

Un viewport definito da un riquadro di delimitazione.

Area visibile

Rappresentazione JSON 
{
  "low": {
    object (LatLng)
  },
  "high": {
    object (LatLng)
  }
}
Campi
low

object (LatLng)

Obbligatorio. Il punto più basso del viewport.
high

object (LatLng)

Obbligatorio. Il punto più alto dell'area visibile.

LatLng

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

number

La latitudine in gradi. Deve essere compreso 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 ResolveNames.

ResolveNamesResponse

Rappresentazione JSON 
{
  "results": [
    {
      object (Result)
    }
  ],
  "failedRequests": {
    integer: {
      object (Status)
    },
    ...
  }
}
Campi
results[]

object (Result)

Solo output. L'elenco delle entità risolte dalle query sulla posizione. Garantito per mappare 1:1 con gli indici della richiesta queries. Una stringa vuota all'indice i indica che la risoluzione non è riuscita per quella query. Se la risoluzione non è riuscita, controlla il campo failed_requests per lo stato dell'errore.
failedRequests

map (key: integer, value: object (Status))

Solo output. Una mappa che comunica errori parziali. La chiave è l'indice della richiesta non riuscita nel campo queries. Il valore è lo stato di errore che indica il motivo per cui la risoluzione non è riuscita.

Un oggetto contenente un elenco di coppie "key": value. Esempio: { "name": "wrench", "mass": "1.3kg", "count": "3" }.

Risultato

Rappresentazione JSON 
{
  "entity": {
    object (Entity)
  },
  "confidence": enum (Confidence)
}
Campi
entity

object (Entity)

Solo output. L'entità risolta dalla query sulla posizione.
confidence

enum (Confidence)

Solo output. Il livello di confidenza per la risoluzione.

Entità

Rappresentazione JSON 
{

  // Union field entity can be only one of the following:
  "place": string
  // End of list of possible types for union field entity.
}
Campi
Campo unione entity. Il tipo di entità risolto. entity può essere solo uno dei seguenti tipi:
place

string

Il nome della risorsa del luogo risolto.

FailedRequestsEntry

Rappresentazione JSON 
{
  "key": integer,
  "value": {
    object (Status)
  }
}
Campi
key

integer
value

object (Status)

Stato

Rappresentazione JSON 
{
  "code": integer,
  "message": string,
  "details": [
    {
      "@type": string,
      field1: ...,
      ...
    }
  ]
}
Campi
code

integer

Il codice di stato, che deve essere un valore enum di google.rpc.Code.
message

string

Un messaggio di errore rivolto agli sviluppatori, che deve essere in inglese. Qualsiasi messaggio di errore rivolto agli utenti deve essere localizzato e inviato nel campo google.rpc.Status.details o localizzato dal client.
details[]

object

Un elenco di messaggi contenenti i dettagli dell'errore. Esiste un insieme comune di tipi di messaggi da utilizzare per le API.

Un oggetto contenente campi di tipo arbitrario. Un campo aggiuntivo "@type" contenente un URI che identifica il tipo. Esempio: { "id": 1234, "@type": "types.example.com/standard/id" }.

Qualsiasi

Rappresentazione JSON 
{
  "typeUrl": string,
  "value": string
}
Campi
typeUrl

string

Identifica il tipo di messaggio Protobuf serializzato con un riferimento URI costituito da un prefisso che termina con una barra e il nome del tipo completo.

Esempio: type.googleapis.com/google.protobuf.StringValue

Questa stringa deve contenere almeno un carattere / e il contenuto dopo l'ultimo / deve essere il nome completo del tipo in forma canonica, senza un punto iniziale. Non scrivere uno schema su questi riferimenti URI in modo che i client non tentino di contattarli.

Il prefisso è arbitrario e le implementazioni di Protobuf devono semplicemente rimuovere tutto fino all'ultimo / incluso per identificare il tipo. type.googleapis.com/ è un prefisso predefinito comune richiesto da alcune implementazioni legacy. Questo prefisso non indica l'origine del tipo e non è previsto che gli URI che lo contengono rispondano a richieste.

Tutte le stringhe URL di tipo devono essere riferimenti URI validi con l'ulteriore limitazione (per il formato di testo) che il contenuto del riferimento deve essere costituito solo da caratteri alfanumerici, sequenze di escape codificate in percentuale e caratteri del seguente insieme (senza includere gli apici inversi esterni): /-.~_!$&()*+,;=. Nonostante consentiamo le codifiche in percentuale, le implementazioni non devono decodificarle per evitare confusione con i parser esistenti. Ad esempio, type.googleapis.com%2FFoo deve essere rifiutato.

Nella progettazione originale di Any, è stata presa in considerazione la possibilità di avviare un servizio di risoluzione dei tipi in questi URL di tipo, ma Protobuf non ne ha mai implementato uno e considera il contatto con questi URL problematico e un potenziale problema di sicurezza. Non tentare di contattare gli URL di tipo.
value

string (bytes format)

Contiene una serializzazione Protobuf del tipo descritto da type_url.

Una stringa con codifica in base64.

Confidenza

Il livello di confidenza per la risoluzione.

Enum
CONFIDENCE_UNSPECIFIED Valore predefinito. Questo valore non viene utilizzato.
MEDIUM Una confidenza media indica che la risoluzione è probabilmente corretta, ma potrebbero esserci altri candidati.
HIGH Un'alta confidenza indica che la risoluzione è corretta e rappresenta un'entità geospaziale specifica (ad es. un luogo specifico).

Annotazioni dello strumento

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