MCP Tools Reference: mapstools.googleapis.com

Outil : resolve_names

Résout une liste de requêtes de localisation spécifiques (noms de points de repère ou adresses exactes) en identifiants de lieu Google Maps canoniques.

Exigences concernant les entrées (CRITIQUES) :

  1. queries (tableau d'objets – OBLIGATOIRE) : liste des requêtes de localisation à résoudre. Vous pouvez spécifier jusqu'à 20 requêtes.

    • Chaque objet de requête doit comporter les éléments suivants :
      • text (chaîne – OBLIGATOIRE) : requête textuelle représentant un nom de lieu ou une adresse spécifiques à résoudre.
        • Exemples : 'Googleplex, Mountain View, CA', '1600 Amphitheatre Pkwy, Mountain View, CA', 'Eiffel Tower, Paris'.

  2. location_bias (objet, FACULTATIF) : utilisez ce paramètre pour donner la priorité aux résultats à proximité d'une zone géographique spécifique.

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

  3. region_code (chaîne – FACULTATIF) : code de région CLDR Unicode (code pays à deux lettres, par exemple US ou CA) de l'utilisateur pour orienter les résultats.

Instructions pour l'appel d'outil :

  • Spécificité (CRITIQUE) : les requêtes doivent représenter un nom de lieu ou une adresse spécifiques. Les recherches générales telles que 'restaurants' ou les noms de chaînes tels que 'Starbucks' ne sont pas acceptées.
  • N'appelez PAS cet outil si les outils en aval que vous prévoyez d'appeler acceptent déjà directement les chaînes brutes d'adresses ou de noms de lieux.

Enregistrer dans Google Maps :

  • La réponse inclut un champ save_to_maps_url, qui est un lien Google Maps unique contenant tous les lieux résolus.
  • Lorsque l'utilisateur souhaite enregistrer, partager ou ouvrir les lieux résolus sous forme de liste dans Google Maps, présentez-lui ce lien. NE créez PAS ce lien vous-même.

Gestion des erreurs (CRITIQUE) :

  • Il s'agit d'un outil de traitement par lot. Une requête peut renvoyer des "résultats mixtes" (par exemple, certaines requêtes sont résolues, tandis que d'autres échouent).
  • La liste de sortie de results est garantie d'être mappée 1:1 avec les index d'entrée queries. Une requête ayant échoué génère un message Result vide (aucun entity n'est défini) à l'index correspondant dans la liste results.
  • Vous DEVEZ vérifier le champ de mappage failed_requests dans la réponse pour identifier l'index de requête spécifique qui a échoué. La clé de failed_requests représente l'index de base 0 de la requête ayant échoué dans la requête. Ne partez pas du principe que l'appel par lot entier a échoué en raison d'un échec partiel.

L'exemple de code suivant montre comment utiliser curl pour appeler l'outil MCP resolve_names.

Requête 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_names",
    "arguments": {
      // Provide these details according to the MCP tool specification.
    }
  },
  "jsonrpc": "2.0",
  "id": 1
}'

Schéma d'entrée

Message de requête pour ResolveNames.

ResolveNamesRequest

Représentation JSON 
{
  "queries": [
    {
      object (LocationQuery)
    }
  ],
  "locationBias": {
    object (LocationBias)
  },
  "regionCode": string
}
Champs
queries[]

object (LocationQuery)

Obligatoire. Liste des requêtes d'emplacement à résoudre. Vous pouvez spécifier jusqu'à 20 requêtes.
locationBias

object (LocationBias)

Facultatif. Région facultative permettant de biaiser les résultats de la résolution. Si elle est spécifiée, les résultats de la résolution seront biaisés en faveur des entités les plus proches de cette région. Inclure location_bias ou region_code permet souvent d'obtenir de meilleurs résultats en limitant l'espace de recherche.

Si les champs location_bias et region_code sont spécifiés, location_bias est prioritaire sur region_code.
regionCode

string

Facultatif. Code régional facultatif permettant de biaiser les résultats de la résolution. Si elle est spécifiée, les résultats de la résolution seront biaisés en faveur des entités qui se trouvent dans ou à proximité de la région spécifiée. Il doit s'agir d'un code de région CLDR. Par exemple, "US" ou "CA". Inclure location_bias ou region_code permet souvent d'obtenir de meilleurs résultats en limitant l'espace de recherche.

Si les champs location_bias et region_code sont spécifiés, location_bias est prioritaire sur region_code.

LocationQuery

Représentation JSON 
{
  "text": string
}
Champs
text

string

Obligatoire. Requête textuelle à résoudre en une entité géospatiale spécifique sur Google Maps, telle qu'un lieu ou une adresse. Plus la requête est spécifique, plus la réponse est précise. Par exemple, "San Francisco", "Googleplex, Mountain View, CA", "1600 Amphitheatre Parkway, Mountain View, CA" ou "Tour Eiffel, Paris". Les requêtes doivent correspondre à une adresse ou à un nom de lieu spécifiques. Les lieux généraux, comme le nom d'une chaîne (par exemple, Starbucks) ou une requête de recherche comme "restaurants", ne sont pas acceptés.

LocationBias

Représentation JSON 
{

  // Union field type can be only one of the following:
  "viewport": {
    object (Viewport)
  }
  // End of list of possible types for union field type.
}
Champs
Champ d'union type. Type de biais de localisation. type ne peut être qu'un des éléments suivants :
viewport

object (Viewport)

Fenêtre d'affichage définie par un cadre de délimitation.

Fenêtre d'affichage

Représentation JSON 
{
  "low": {
    object (LatLng)
  },
  "high": {
    object (LatLng)
  }
}
Champs
low

object (LatLng)

Obligatoire. Point bas de la fenêtre d'affichage.
high

object (LatLng)

Obligatoire. Point haut de la fenêtre d'affichage.

LatLng

Représentation JSON 
{
  "latitude": number,
  "longitude": number
}
Champs
latitude

number

Latitude en degrés. Elle doit être comprise dans la plage [-90.0, +90.0].
longitude

number

Longitude en degrés. Elle doit être comprise dans la plage [-180.0, +180.0].

Schéma de sortie

Message de réponse pour ResolveNames.

ResolveNamesResponse

Représentation JSON 
{
  "results": [
    {
      object (Result)
    }
  ],
  "failedRequests": {
    integer: {
      object (Status)
    },
    ...
  },
  "saveToMapsUrl": string
}
Champs
results[]

object (Result)

Uniquement en sortie. Liste des entités résolues à partir des requêtes sur les lieux. Garantit une correspondance exacte avec les index queries de la requête. Une chaîne vide à l'index i indique que la résolution a échoué pour cette requête. Si la résolution a échoué, veuillez vérifier l'état de l'erreur dans le champ failed_requests.
failedRequests

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

Uniquement en sortie. Carte indiquant les échecs partiels. La clé correspond à l'index de la requête ayant échoué dans le champ queries. La valeur correspond à l'état d'erreur expliquant pourquoi la résolution a échoué.

Objet contenant une liste de paires "key": value. Exemple : { "name": "wrench", "mass": "1.3kg", "count": "3" }.
saveToMapsUrl

string

Uniquement en sortie. Un lien permettant d'enregistrer toutes les entités résolues dans Google Maps.

Résultat

Représentation JSON 
{
  "entity": {
    object (Entity)
  },
  "confidence": enum (Confidence)
}
Champs
entity

object (Entity)

Uniquement en sortie. Entité résolue à partir de la requête de localisation.
confidence

enum (Confidence)

Uniquement en sortie. Niveau de confiance de la résolution.

Entité

Représentation JSON 
{

  // Union field entity can be only one of the following:
  "place": string
  // End of list of possible types for union field entity.
}
Champs
Champ d'union entity. Type d'entité résolu. entity ne peut être qu'un des éléments suivants :
place

string

Nom de ressource du lieu résolu.

FailedRequestsEntry

Représentation JSON 
{
  "key": integer,
  "value": {
    object (Status)
  }
}
Champs
key

integer
value

object (Status)

État

Représentation JSON 
{
  "code": integer,
  "message": string,
  "details": [
    {
      "@type": string,
      field1: ...,
      ...
    }
  ]
}
Champs
code

integer

Code d'état, qui doit être une valeur d'énumération de google.rpc.Code.
message

string

Message d'erreur destiné au développeur, qui doit être en anglais. Tout message d'erreur destiné aux utilisateurs doit être localisé et envoyé dans le champ google.rpc.Status.details, ou localisé par le client.
details[]

object

Liste de messages comportant les détails de l'erreur. Il existe un ensemble commun de types de message utilisable par les API.

Objet contenant des champs d'un type arbitraire. Un champ supplémentaire "@type" contient un URI identifiant le type. Exemple : { "id": 1234, "@type": "types.example.com/standard/id" }.

Tous

Représentation JSON 
{
  "typeUrl": string,
  "value": string
}
Champs
typeUrl

string

Identifie le type du message Protobuf sérialisé avec une référence URI composée d'un préfixe se terminant par une barre oblique et du nom de type complet.

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

Cette chaîne doit contenir au moins un caractère /, et le contenu après le dernier / doit être le nom complet du type sous forme canonique, sans point au début. N'écrivez pas de schéma sur ces références d'URI afin que les clients ne tentent pas de les contacter.

Le préfixe est arbitraire et les implémentations Protobuf sont censées supprimer tout ce qui précède le dernier / (inclus) pour identifier le type. type.googleapis.com/ est un préfixe par défaut courant que certaines anciennes implémentations requièrent. Ce préfixe n'indique pas l'origine du type, et les URI qui le contiennent ne sont pas censés répondre aux requêtes.

Toutes les chaînes d'URL de type doivent être des références URI valides, avec la restriction supplémentaire (pour le format texte) que le contenu de la référence ne doit comporter que des caractères alphanumériques, des séquences d'échappement encodées en pourcentage et des caractères de l'ensemble suivant (sans les accents graves extérieurs) : /-.~_!$&()*+,;=. Bien que nous autorisions les encodages en pourcentage, les implémentations ne doivent pas les décoder pour éviter toute confusion avec les analyseurs existants. Par exemple, type.googleapis.com%2FFoo doit être rejeté.

Dans la conception d'origine de Any, la possibilité de lancer un service de résolution de type à ces URL de type a été envisagée, mais Protobuf n'en a jamais implémenté et considère que contacter ces URL est problématique et constitue un risque potentiel pour la sécurité. N'essayez pas de contacter les URL de type.
value

string (bytes format)

Contient une sérialisation Protobuf du type décrit par type_url.

Chaîne encodée en base64.

Confiance

Niveau de confiance de la résolution.

Enums
CONFIDENCE_UNSPECIFIED Valeur par défaut. Cette valeur n'est pas utilisée.
MEDIUM Un niveau de confiance moyen indique que la résolution est probablement correcte, mais qu'il peut y avoir d'autres candidats.
HIGH Un niveau de confiance élevé indique que la résolution est correcte et représente une entité géospatiale spécifique (par exemple, un lieu spécifique).

Annotations d'outils

Les annotations d'outil sont envoyées aux clients MCP pour décrire le risque de base d'un outil donné. La plupart des clients traitent ces indices comme non fiables, mais ils peuvent être utilisés pour déterminer quand un message de confirmation peut être envoyé à un utilisateur.

En plus de la chaîne de titre, les indications booléennes suivantes sont définies comme suit :

  • readOnlyHint : si la valeur est "true", l'outil ne modifie pas son environnement. Valeur par défaut : "false".
  • destructiveHint : si la valeur est "true", l'outil peut effectuer des actions destructrices. Si la valeur est "false", l'outil ne peut effectuer que des actions d'ajout. Valeur par défaut : "true".
  • idempotentHint : si la valeur est "true", appeler l'outil à plusieurs reprises avec les mêmes arguments n'aura aucun effet supplémentaire sur son environnement. Valeur par défaut : "false".
  • openWorldHint : si la valeur est "true", l'outil peut interagir avec un "monde ouvert" d'entités externes. Si la valeur est "false", l'outil ne peut interagir qu'avec des entités internes. Par exemple, un outil de recherche Web serait en monde ouvert, tandis qu'un outil de mémoire ne le serait pas.

Indication destructive : ❌ | Indication idempotente : ❌ | Indication en lecture seule : ✅ | Indication Open World : ❌