Orte suchen

Mit dem Tool search_places kann ein LLM Orte auf Google Maps anhand einer Anfrage in natürlicher Sprache finden. Das Tool gibt eine KI-generierte Zusammenfassung der übereinstimmenden Orte zurück. Für jeden Ort, der in der Zusammenfassung genannt wird, werden auch die Orts-ID, die Breiten- und Längengradkoordinaten, Google Maps-URLs und die Quellenangabe zurückgegeben.

Sie können search_places über den MCP-Server oder als REST-Methode searchText aufrufen. Auf dieser Seite werden die Anfrageoptionen, einschließlich der Pro-Optionen, der Inhalt der Antwort und die Abrechnung von Anfragen beschrieben. Die vollständigen Schemas finden Sie in der search_places-MCP-Referenz und der searchText-REST-Referenz.

Anfrageoptionen

Das LLM legt diese Optionen fest, wenn es das Tool aufruft, basierend auf der Anfrage des Nutzers und der Toolbeschreibung. Sie können mit Ihren eigenen Anweisungen beeinflussen, welche Optionen das Modell verwendet. Weitere Informationen finden Sie unter Nutzung von Pro steuern.

In der folgenden Tabelle werden die Anfrageoptionen für search_places beschrieben:

Option Beschreibung
text_query Erforderlich. Die Suchanfrage, z. B. coffee shops near Golden Gate Park. Die Abfrage muss genügend Standortinformationen enthalten, um eindeutig zu sein, oder die Anfrage muss location_bias enthalten.
location_bias Ein Kreis (center und optional radius_meters, bis zu 50.000 Meter), auf den die Ergebnisse ausgerichtet werden sollen. Wenn text_query einen expliziten Standort angibt, wird stattdessen dieser Standort verwendet.
language_code Die Sprache der Zusammenfassung, z. B. en oder ja. Die Standardeinstellung ist Englisch.
region_code Der CLDR-Regionscode des Nutzers, z. B. US. Wirkt sich auf regionsspezifische Ortsnamen und möglicherweise auf Ergebnisse gemäß geltendem Recht aus.
page_size Die maximale Anzahl der zurückzugebenden Orte. Der Standardwert ist 5. Werte von 6 bis 10 sind eine Pro-Option. Werte über 10 geben einen INVALID_ARGUMENT-Fehler zurück. Der Dienst gibt möglicherweise weniger Orte als angefordert zurück.
include_extended_details Wenn true, enthält die Zusammenfassung erweiterte Ortsdetails. Dies ist eine Pro-Option. Die Standardeinstellung ist false.

Pro-Optionen

Zwei Optionen wählen die Maps Grounding Pro-SKU aus. Eine Anfrage, bei der eine oder beide Optionen verwendet werden, wird über die Pro-SKU abgerechnet:

Pro-Option Anwendungsbereich
Standort „include_extended_details“ auf „true“ gesetzt Für die Anfrage des Nutzers sind erweiterte Ortsdetails erforderlich, z. B. Informationen aus Rezensionen, Highlights auf der Speisekarte, Atmosphäre oder Tipps für Besucher.
page_size von 6 bis 10 Der Nutzer möchte mehr als 5 Orte vergleichen.

Anfragen, bei denen keine der beiden Optionen verwendet wird, einschließlich Anfragen mit einem page_size von 1 bis 5, werden über die Essentials-SKU abgerechnet.

Erweiterte Ortsdetails

Setzen Sie include_extended_details auf true, wenn die Anfrage des Nutzers qualitative Informationen, Echtzeitbedingungen oder spezielle Attribute erfordert, z. B.:

  • Was Rezensenten sagen: Rezensionsbasierte Statistiken, Kundenstimmung und Feedback.
  • Spezifische Angebote: Menüpunkte, Gerichte, Spezialitäten, Getränke oder Highlights des Unternehmens.
  • Atmosphäre: Inneneinrichtung, Ästhetik, Ambiente oder Stimmung.
  • Praktische Tipps für Besucher: ob eine Vorabreservierung erforderlich ist, Richtlinien für spontane Besuche, Wartezeiten, Besucheraufkommen, Parkmöglichkeiten und Einrichtungen.
  • Nähe: Entfernung oder Fahrtzeit vom Ort der Anfrage oder vom location_bias-Zentrum, wenn der Nutzer fragt, was in der Nähe oder am nächsten ist.

Die Informationen in einer Zusammenfassung hängen von der Anfrage und den für den jeweiligen Ort verfügbaren Daten ab. Nicht jede Art von Statistik wird in jeder Antwort angezeigt.

Lassen Sie den Wert auf false (Standard), um nach Standardinformationen zu suchen: Küchen oder Geschäftstypen, Adressen, Kontaktdaten, Öffnungszeiten und Standardausstattung. Anfragen mit erweiterten Details dauern länger.

Erweiterte Details ändern die Struktur der Antwort nicht. Ohne sie wird jeder Ort in der Zusammenfassung in ein oder zwei Sätzen beschrieben. Damit erhält jeder Ort eine längere Beschreibung, die auf mehr Google Maps-Daten basiert, einschließlich Informationen aus Rezensionen. Die strukturierten places-Einträge sind für beide SKUs identisch.

Beispiel

In der folgenden MCP-Anfrage werden bis zu 8 Orte mit erweiterten Details angefordert. Die Abrechnung erfolgt unter der Pro-SKU:

{
  "method": "tools/call",
  "params": {
    "name": "search_places",
    "arguments": {
      "text_query": "date night Italian restaurants in Chicago",
      "page_size": 8,
      "include_extended_details": true
    }
  },
  "jsonrpc": "2.0",
  "id": 1
}

Im folgenden Beispiel wird dieselbe Anfrage an die REST-Methode searchText gesendet:

curl -X POST \
-H "Content-Type: application/json" \
-H "X-Goog-Api-Key: API_KEY" \
-d '{
  "textQuery": "date night Italian restaurants in Chicago",
  "pageSize": 8,
  "includeExtendedDetails": true
}' \
"https://mapstools.googleapis.com/v1:searchText"

Ersetzen Sie dabei API_KEY durch Ihren eigenen API-Schlüssel.

Ohne erweiterte Details wird jeder Ort in ein oder zwei Sätzen beschrieben:

Beispiel-Trattoria [0] (4,6★ (1.250) · 123 W Beispielstraße · $$$) A neighborhood trattoria known for handmade pasta and a long wine list.

With extended details, the summary adds what reviewers highlight and practical tips:

Example Trattoria [0] (4.6★ (1,250) · 123 W Example St · $$$) Ein gemütlicher Speiseraum mit Kerzenlicht, der von Rezensenten als romantisch, aber am Wochenende als laut beschrieben wird. Zu den herausragenden Gerichten gehören die Tagliatelle al Ragù, die Burrata und das Tiramisu. Reservierungen werden empfohlen. Ohne Reservierung müssen Sie am Freitag- und Samstagabend mit einer Wartezeit von 30 bis 45 Minuten rechnen. Parkplätze an der Straße sind begrenzt.

Antwort

Die Antwort umfasst die folgenden Felder:

  • summary: Eine Zusammenfassung der Suchergebnisse in natürlicher Sprache. Sie kann nullbasierte Zitate wie [0] enthalten, die Einträgen in places zugeordnet sind.
  • places[]: Die in der Zusammenfassung erwähnten Orte. Jeder Ort enthält:
    • place: Der Ressourcenname des Ortes im Format places/{id}.
    • id: Die Orts-ID. Sie können sie mit anderen Google Maps Platform APIs verwenden, z. B. um den Ort auf einer Karte anzuzeigen.
    • location: Die Breiten- und Längengradkoordinaten des Ortes.
    • googleMapsLinks: Google Maps-URLs für den Ort (placeUrl), die Wegbeschreibung (directionsUrl), Rezensionen (reviewsUrl), Fotos (photosUrl) und das Verfassen einer Rezension (writeAReviewUrl).
    • attribution: Die Zuordnung, die Sie für den Ort angeben müssen. Weitere Informationen finden Sie unter Anforderungen an die Quellenangabe.
  • contentToken: Ein agentisches Datenvisualisierungstoken (Vorabversion), mit dem Sie die Orte in der Antwort ohne zusätzliche Kosten mit dem Places UI Kit anzeigen können. Wird zurückgegeben, wenn die Antwort mindestens einen Ort enthält.

Die Antwort hat für beide SKUs sowie für MCP und REST dieselbe Struktur. Weitere Informationen zu den Feldern finden Sie in der Referenz zu search_places.

Abrechnung und Kontingente

Jede search_places-Anfrage ist ein abrechenbares Ereignis:

Wenn Sie die Orte aus einer search_places-Antwort mit dem Places UI Kit anzeigen, können Sie das agentische Datenvisualisierungstoken (Vorabversion) verwenden, damit diese Places UI Kit-Anfragen nicht in Rechnung gestellt werden.

Das search_places-Kontingent beträgt 300 Abfragen pro Minute für jedes Projekt, die von beiden SKUs gemeinsam genutzt werden. Informationen zu den Preisen finden Sie in der Hauptpreistabelle und in der Preistabelle für Indien.