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.

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 de manière un-à-un avec les index queries d'entrée. Une requête ayant échoué générera 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 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 tool's MCP 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 orienter 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. L'inclusion de location_bias ou region_code permet souvent d'obtenir de meilleurs résultats en limitant l'espace de recherche.

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

string

Facultatif. Code régional facultatif pour orienter 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". L'inclusion de location_bias ou region_code permet souvent d'obtenir de meilleurs résultats en limitant l'espace de recherche.

Si les deux 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é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 lieux généraux, comme le nom d'une chaîne (par exemple, Starbucks) ou une requête de recherche (par exemple, "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)
    },
    ...
  }
}
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 le champ failed_requests pour connaître l'état de l'erreur.
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" }.

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 /. Le contenu après le dernier caractère / doit correspondre au 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 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 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é un et considère que la prise de contact avec 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 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

Indication de destruction : ❌ | Indication d'idempotence : ❌ | Indication de lecture seule : ✅ | Indication de monde ouvert : ❌