MCP Tools Reference: mapstools.googleapis.com

Outil : resolve_names

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

Exigences d'entrée (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 :
      • text (chaîne, OBLIGATOIRE) : requête textuelle représentant le nom ou l'adresse d'un lieu spécifique à 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 prioriser les 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 au format Unicode (code pays à deux lettres, par exemple US, CA) de l'utilisateur pour biaiser 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 comme 'Starbucks' ne sont pas acceptés.
  • N'appelez PAS cet outil si les outils en aval que vous prévoyez d'appeler acceptent déjà directement les chaînes d'adresse ou de nom de lieu brutes.

Enregistrer dans Google Maps

  • La réponse inclut un champ save_to_maps_url : un seul lien Google Maps contenant tous les lieux résolus avec succès.
  • 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 exceptions (CRITIQUE) :

  • Il s'agit d'un outil de traitement par lot. Une requête peut renvoyer des "résultats mitigés" (par exemple, certaines requêtes aboutissent, tandis que d'autres échouent).
  • La liste de sortie de results est garantie de correspondre à 1:1 avec les indices queries d'entrée. 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é. Ne partez pas du principe que l'intégralité de l'appel par lot 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 de localisation à résoudre. Vous pouvez spécifier jusqu'à 20 requêtes.
locationBias

object (LocationBias)

Facultatif. Région facultative pour biaiser les résultats de la résolution. Si cette option 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 location_bias et region_code sont spécifiés, location_bias est prioritaire sur region_code.
regionCode

string

Facultatif. Code de région facultatif pour biaiser les résultats de la résolution. Si spécifié, les résultats de la résolution seront biaisés en faveur des entités qui se trouvent dans la région spécifiée ou à proximité. 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 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 pour une entité géospatiale spécifique sur Google Maps, comme un lieu ou une adresse. Plus la requête est spécifique, plus la résolution 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 positions générales telles que le nom d'une chaîne (par exemple, Starbucks) ou une requête de recherche comme "restaurants" ne sont pas acceptées.

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 le plus 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 de localisation. Correspondance exacte garantie avec les indices 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. Une carte indiquant les échecs partiels. La clé est l'index de la requête ayant échoué dans le champ queries. La valeur est l'état d'erreur détaillant la raison de l'échec de la résolution.

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 correctement 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 d'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 de début. N'écrivez pas de schéma sur ces références d'URI afin que les clients n'essaient pas de les contacter.

Le préfixe est arbitraire et les implémentations Protobuf sont censées simplement supprimer tout ce qui précède et inclut le dernier / pour identifier le type. type.googleapis.com/ est un préfixe par défaut courant requis par certaines anciennes implémentations. 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 d'URI légales avec la restriction supplémentaire (pour le format texte) que le contenu de la référence ne doit être composé que de caractères alphanumériques, de caractères d'échappement encodés en pourcentage et de caractères de l'ensemble suivant (sans inclure les accents graves externes) : /-.~_!$&()*+,;=. Bien que nous autorisions les encodages en pourcentage, les implémentations ne doivent pas les déséchapper 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 types à 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 problème de sécurité potentiel. 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 Une confiance moyenne 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 considèrent ces indications comme non fiables, mais elles peuvent être utilisées pour décider quand envoyer une invite de confirmation à un utilisateur.

En plus de la chaîne de titre, les indices booléens suivants sont définis 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", l'appel répété de l'outil 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 sur le Web serait en monde ouvert, tandis qu'un outil de mémoire ne le serait pas.

Destructive Hint: ❌ | Idempotent Hint: ❌ | Read Only Hint: ✅ | Open World Hint: ❌