MCP Tools Reference: mapstools.googleapis.com

Strumento: resolve_maps_urls

Risolve un elenco di URL di Google Maps in ID luogo canonici di Google Maps.

Quando chiamare questo strumento (CRITICO):

  • Utilizza questo strumento quando l'utente fornisce uno o più link o URL di condivisione di Google Maps (ad es. "https://maps.app.goo.gl/...", "https://www.google.com/maps/place/..." o "https://maps.google.com/...") e devi estrarre gli ID luogo canonici sottostanti.
  • Puoi specificare fino a 20 URL da risolvere in una singola richiesta batch.

Requisiti di input (CRITICI):

  • urls (array di stringhe - OBBLIGATORIO): l'elenco degli URL di Google Maps da risolvere. Ogni URL deve essere un URL di Google Maps valido per un singolo luogo.

Gestione degli errori (CRITICA):

  • Questo è uno strumento di elaborazione batch. Una richiesta potrebbe restituire "risultati misti" (ad es. alcuni URL vengono risolti correttamente, mentre altri non riescono a essere risolti).
  • L'elenco di output di entities è garantito per mappare 1:1 con gli indici urls di input. La risoluzione di un URL non riuscita comporterà un messaggio Entity vuoto (nessun campo è impostato) nel relativo indice nell'elenco entities.
  • DEVI controllare il campo della mappa failed_requests nella risposta per identificare l'indice dell'URL specifico non riuscito. La chiave di failed_requests rappresenta l'indice in base 0 dell'URL non riuscito nella richiesta. Non dare per scontato 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_maps_urls.

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

Schema di input

Messaggio di richiesta per ResolveMapsUrls.

ResolveMapsUrlsRequest

Rappresentazione JSON 
{
  "urls": [
    string
  ]
}
Campi
urls[]

string

Obbligatorio. Gli URL di Google Maps da risolvere. Ogni URL deve essere un URL di Google Maps valido, ad esempio https://maps.app.goo.gl/..., https://www.google.com/maps/place/... o https://maps.google.com/.... Al momento sono supportati solo gli URL che rimandano a un singolo luogo. Puoi specificare fino a 20 URL.

Schema di output

Messaggio di risposta per ResolveMapsUrls.

ResolveMapsUrlsResponse

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

object (Entity)

Solo output. L'elenco delle entità risolte dagli URL di Google Maps. È garantito che la mappatura sia 1:1 con gli indici urls della richiesta. Un messaggio vuoto all'indice i (dove non è impostata alcuna entity) indica che la risoluzione non è riuscita per quell'URL. Se la risoluzione non è riuscita, controlla il campo failed_requests per lo stato di errore.
failedRequests

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

Solo output. Una mappa che comunica gli errori parziali per gli URL di Google Maps. La chiave è l'indice della richiesta non riuscita nel campo urls. 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" }.

Entity

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à risolta. 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)

Status

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" }.

Any

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

string

Identifica il tipo del messaggio Protobuf serializzato con un riferimento URI composto 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 formato canonico, 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 eventuali richieste.

Tutte le stringhe URL del tipo devono essere riferimenti URI validi con la limitazione aggiuntiva (per il formato di testo) che il contenuto del riferimento deve essere composto solo da caratteri alfanumerici, escape con codifica percentuale e caratteri nel seguente insieme (senza includere i backtick esterni): /-.~_!$&()*+,;=. Nonostante consentiamo le codifiche percentuali, 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 a questi URL di tipo, ma Protobuf non ne ha mai implementato uno e considera problematico e un potenziale problema di sicurezza contattare questi URL. 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.

Annotazioni dello strumento

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