MCP Tools Reference: mapstools.googleapis.com

Tool: resolve_names

Löst eine Batchliste mit bestimmten Standortanfragen (Namen von Sehenswürdigkeiten oder genaue Adressen) in kanonische Google Maps-Orts-IDs auf.

Anforderungen an die Eingabe (WICHTIG):

  1. queries (Array von Objekten – ERFORDERLICH): Eine Liste der Standortanfragen, die aufgelöst werden sollen. Sie können bis zu 20 Abfragen angeben.

    • Jedes Abfrageobjekt muss Folgendes enthalten:
      • text (String – ERFORDERLICH): Die Textanfrage, die einen bestimmten Ortsnamen oder eine bestimmte Adresse darstellt, die aufgelöst werden soll.
        • Beispiele: 'Googleplex, Mountain View, CA', '1600 Amphitheatre Pkwy, Mountain View, CA', 'Eiffel Tower, Paris'.

  2. location_bias (Objekt – OPTIONAL): Damit können Sie Ergebnisse in der Nähe eines bestimmten geografischen Gebiets priorisieren.

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

  3. region_code (String – OPTIONAL): Der Unicode-CLDR-Regionscode (zweistelliger Ländercode, z.B. US, CA) des Nutzers, um die Ergebnisse zu gewichten.

Anleitung für Tool-Aufruf:

  • Spezifität (WICHTIG): Anfragen müssen einen bestimmten Ortsnamen oder eine bestimmte Adresse enthalten. Allgemeine Suchanfragen wie 'restaurants' oder Kettennamen wie 'Starbucks' werden nicht unterstützt.
  • Rufen Sie dieses Tool NICHT auf, wenn die Downstream-Tools, die Sie aufrufen möchten, bereits Rohadressen oder Ortsnamenstrings direkt akzeptieren.

Fehlerbehandlung (KRITISCH):

  • Es handelt sich um ein Tool für die Batchverarbeitung. Eine Anfrage kann „gemischte Ergebnisse“ zurückgeben, z.B. wenn einige Anfragen erfolgreich aufgelöst werden, andere jedoch fehlschlagen.
  • Die Ausgabeliste von results wird garantiert 1:1 den Eingabeindexen von queries zugeordnet. Bei einer fehlgeschlagenen Abfrage wird am entsprechenden Index in der Liste results eine leere Result-Nachricht zurückgegeben (kein entity festgelegt).
  • Sie MÜSSEN das Kartenfeld failed_requests in der Antwort prüfen, um herauszufinden, welcher bestimmte Abfrageindex fehlgeschlagen ist. Der Schlüssel von failed_requests stellt den 0-basierten Index der fehlgeschlagenen Anfrage in der Anfrage dar. Gehen Sie nicht davon aus, dass der gesamte Batchaufruf aufgrund eines teilweisen Fehlers fehlgeschlagen ist.

Im folgenden Beispiel wird gezeigt, wie Sie mit curl das MCP-Tool resolve_names aufrufen.

Curl-Anfrage 
                  
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
}'

Eingabeschema

Anfragenachricht für ResolveNames

ResolveNamesRequest

JSON-Darstellung 
{
  "queries": [
    {
      object (LocationQuery)
    }
  ],
  "locationBias": {
    object (LocationBias)
  },
  "regionCode": string
}
Felder
queries[]

object (LocationQuery)

Erforderlich. Eine Liste der Standortanfragen, die aufgelöst werden sollen. Sie können bis zu 20 Abfragen angeben.
locationBias

object (LocationBias)

Optional. Eine optionale Region, um die Auflösungsergebnisse zu beeinflussen. Wenn angegeben, werden die Auflösungsergebnisse auf die Einheiten ausgerichtet, die sich näher an dieser Region befinden. Wenn Sie location_bias oder region_code einfügen, werden die Ergebnisse oft besser, da der Suchbereich eingegrenzt wird.

Wenn sowohl location_bias als auch region_code angegeben sind, hat location_bias Vorrang vor region_code.
regionCode

string

Optional. Ein optionaler Regionscode, um die Auflösungsergebnisse zu beeinflussen. Wenn angegeben, werden die Auflösungsergebnisse auf die Entitäten ausgerichtet, die sich in oder in der Nähe der angegebenen Region befinden. Dies sollte ein CLDR-Regionscode sein. Beispiel: „US“ oder „CA“. Wenn Sie location_bias oder region_code einfügen, werden die Ergebnisse oft besser, da der Suchbereich eingegrenzt wird.

Wenn sowohl location_bias als auch region_code angegeben sind, hat location_bias Vorrang vor region_code.

LocationQuery

JSON-Darstellung 
{
  "text": string
}
Felder
text

string

Erforderlich. Die Textanfrage, die in Google Maps in eine bestimmte geografische Einheit wie einen Ort oder eine Adresse aufgelöst werden soll. Je spezifischer die Anfrage, desto genauer die Auflösung. Zum Beispiel „San Francisco“, „Googleplex, Mountain View, CA“, „1600 Amphitheatre Parkway, Mountain View, CA“ oder „Eiffelturm, Paris“. Abfragen müssen eine bestimmte Adresse oder einen bestimmten Ortsnamen enthalten. Allgemeine Standorte wie ein Kettenname (z.B. Starbucks) oder eine Suchanfrage wie „Restaurants“ werden nicht unterstützt.

LocationBias

JSON-Darstellung 
{

  // Union field type can be only one of the following:
  "viewport": {
    object (Viewport)
  }
  // End of list of possible types for union field type.
}
Felder
Union-Feld type. Der Typ des Standort-Bias. Für type ist nur einer der folgenden Werte zulässig:
viewport

object (Viewport)

Ein Darstellungsbereich, der durch einen Begrenzungsrahmen definiert wird.

Darstellungsbereich

JSON-Darstellung 
{
  "low": {
    object (LatLng)
  },
  "high": {
    object (LatLng)
  }
}
Felder
low

object (LatLng)

Erforderlich. Der niedrigste Punkt des Darstellungsbereichs.
high

object (LatLng)

Erforderlich. Der höchste Punkt des Darstellungsbereichs.

LatLng

JSON-Darstellung 
{
  "latitude": number,
  "longitude": number
}
Felder
latitude

number

Der Breitengrad in Grad. Er muss im Bereich [-90,0, +90,0] liegen.
longitude

number

Der Längengrad in Grad. Er muss im Bereich [-180,0, +180,0] liegen.

Ausgabeschema

Antwortnachricht für ResolveNames.

ResolveNamesResponse

JSON-Darstellung 
{
  "results": [
    {
      object (Result)
    }
  ],
  "failedRequests": {
    integer: {
      object (Status)
    },
    ...
  }
}
Felder
results[]

object (Result)

Nur Ausgabe. Die Liste der aufgelösten Entitäten aus den Standortabfragen. Die Zuordnung zu den queries-Indexen der Anfrage ist garantiert 1:1. Ein leerer String am Index i gibt an, dass die Auflösung für diese Anfrage fehlgeschlagen ist. Wenn die Auflösung fehlgeschlagen ist, sehen Sie im Feld failed_requests nach dem Fehlerstatus.
failedRequests

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

Nur Ausgabe. Eine Karte, die teilweise Fehler anzeigt. Der Schlüssel ist der Index der fehlgeschlagenen Anfrage im Feld queries. Der Wert ist der Fehlerstatus, der angibt, warum die Auflösung fehlgeschlagen ist.

Ein Objekt, das eine Liste von "key": value-Paaren enthält. Beispiel: { "name": "wrench", "mass": "1.3kg", "count": "3" }.

Ergebnis

JSON-Darstellung 
{
  "entity": {
    object (Entity)
  },
  "confidence": enum (Confidence)
}
Felder
entity

object (Entity)

Nur Ausgabe. Die aufgelöste Entität aus der Standortanfrage.
confidence

enum (Confidence)

Nur Ausgabe. Das Konfidenzniveau für die Lösung.

Entität

JSON-Darstellung 
{

  // Union field entity can be only one of the following:
  "place": string
  // End of list of possible types for union field entity.
}
Felder
Union-Feld entity. Der aufgelöste Entitätstyp. Für entity ist nur einer der folgenden Werte zulässig:
place

string

Der Ressourcenname des aufgelösten Orts.

FailedRequestsEntry

JSON-Darstellung 
{
  "key": integer,
  "value": {
    object (Status)
  }
}
Felder
key

integer
value

object (Status)

Status

JSON-Darstellung 
{
  "code": integer,
  "message": string,
  "details": [
    {
      "@type": string,
      field1: ...,
      ...
    }
  ]
}
Felder
code

integer

Der Statuscode, der idealerweise ein ENUM-Wert von google.rpc.Code ist.
message

string

Eine an Entwickler gerichtete Fehlermeldung, die englischsprachig sein sollte. Jede für Nutzer sichtbare Fehlermeldung sollte lokalisiert und im Feld google.rpc.Status.details gesendet werden. Sie kann auch clientseitig lokalisiert werden.
details[]

object

Eine Auflistung aller Meldungen, die die Fehlerdetails enthalten. Es gibt einen gemeinsamen Satz von Nachrichtentypen, die APIs verwenden können.

Ein Objekt, das Felder eines beliebigen Typs enthält. Ein zusätzliches Feld "@type" enthält einen URI zur Identifizierung des Typs. Beispiel: { "id": 1234, "@type": "types.example.com/standard/id" }.

Alle

JSON-Darstellung 
{
  "typeUrl": string,
  "value": string
}
Felder
typeUrl

string

Gibt den Typ der serialisierten Protobuf-Nachricht mit einem URI-Verweis an, der aus einem Präfix, das mit einem Schrägstrich endet, und dem vollständig qualifizierten Typnamen besteht.

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

Dieser String muss mindestens ein /-Zeichen enthalten. Der Inhalt nach dem letzten / muss der vollständig qualifizierte Name des Typs in kanonischer Form ohne führenden Punkt sein. Schreiben Sie kein Schema in diese URI-Referenzen, damit Clients nicht versuchen, sie zu kontaktieren.

Das Präfix ist beliebig und Protobuf-Implementierungen sollen einfach alles bis zum letzten / (einschließlich) entfernen, um den Typ zu identifizieren. type.googleapis.com/ ist ein gängiges Standardpräfix, das für einige Legacy-Implementierungen erforderlich ist. Dieses Präfix gibt nicht den Ursprung des Typs an und URIs, die es enthalten, sollen nicht auf Anfragen reagieren.

Alle Typ-URL-Strings müssen gültige URI-Referenzen sein. Für das Textformat gilt die zusätzliche Einschränkung, dass der Inhalt der Referenz nur aus alphanumerischen Zeichen, prozentual codierten Escape-Sequenzen und Zeichen aus der folgenden Menge bestehen darf (ohne die äußeren Backticks): /-.~_!$&()*+,;=. Obwohl wir Prozentcodierungen zulassen, sollten Implementierungen sie nicht decodieren, um Verwechslungen mit vorhandenen Parsern zu vermeiden. Beispiel: type.googleapis.com%2FFoo sollte abgelehnt werden.

Im ursprünglichen Design von Any wurde die Möglichkeit in Betracht gezogen, einen Dienst zur Typauflösung unter diesen Typ-URLs zu starten. Protobuf hat jedoch nie einen solchen Dienst implementiert und betrachtet das Kontaktieren dieser URLs als problematisch und als potenzielles Sicherheitsproblem. Versuchen Sie nicht, URLs vom Typ „Kontakt“ aufzurufen.
value

string (bytes format)

Enthält eine Protobuf-Serialisierung des Typs, der durch „type_url“ beschrieben wird.

Ein base64-codierter String.

Zuverlässigkeit

Das Konfidenzniveau für die Lösung.

Enums
CONFIDENCE_UNSPECIFIED Standardwert. Dieser Wert wird nicht verwendet.
MEDIUM „Mittlere Zuverlässigkeit“ bedeutet, dass die Lösung wahrscheinlich richtig ist, es aber auch andere Möglichkeiten gibt.
HIGH Ein hohes Konfidenzniveau bedeutet, dass die Auflösung korrekt ist und ein bestimmtes geografisches Objekt (z.B. ein bestimmter Ort) darstellt.

Tool-Annotationen

Destruktiver Hinweis: ❌ | Idempotenter Hinweis: ❌ | Hinweis „Nur lesen“: ✅ | Hinweis „Offene Welt“: ❌