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 Koordinaten, Google Maps-URLs und die Quellenangabe zurückgegeben.

Auf dieser Seite werden die Anfrageoptionen, einschließlich der Pro-Optionen, der Inhalt der Antwort und die Abrechnung von Anfragen beschrieben. Das vollständige Toolschema finden Sie in der search_places-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 Pro-Nutzung steuern.

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 aus, die auf geltendem Recht basieren.
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 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-Wert 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 Informationen, 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 Standort der Anfrage oder vom Zentrum von location_bias, wenn der Nutzer nach Orten in der Nähe oder am nächsten gelegenen Orten fragt.

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) für Standardsuchen: 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 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
}

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

Beispiel-Trattoria [0] (4,6★ (1.250) · Beispielstraße 123 · $$$) 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 enthält Folgendes:

  • 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 Orts im Format places/{id}.
    • id: Die Orts-ID. Sie können sie mit anderen Google Maps Platform APIs verwenden, um den Ort beispielsweise auf einer Karte anzuzeigen.
    • location: Der Breiten- und Längengrad 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.

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

Pro-Optionen während der eingeschränkten GA

Während der eingeschränkten GA sind Pro-Optionen nur für Projekte auf der Pro-Zulassungsliste verfügbar. Wenn Ihr Projekt noch nicht auf der Zulassungsliste steht, werden Pro-Optionen ignoriert und nicht abgelehnt:

  • include_extended_details wird als false behandelt.
  • page_size-Werte über 5, einschließlich Werte über 10, werden auf 5 reduziert.

Die Anfrage wird über die Essentials-SKU abgerechnet. Informationen zum Anfordern des Zugriffs finden Sie unter Pro-Optionen während der eingeschränkten GA.

Abrechnung und Kontingente

Jede search_places-Anfrage ist ein abrechenbares Ereignis:

  • Eine Anfrage, für die keine Pro-Optionen verwendet werden, wird über die Essentials-SKU abgerechnet.
  • Eine Anfrage, für die eine Pro-Option verwendet wird, wird über die Pro-SKU abgerechnet. Wenn Sie beide Optionen in einer Anfrage verwenden, ändert sich die Gebühr nicht. Informationen zu den Preisen für die Pro-Version finden Sie unter Essentials, Pro und Fundierung mit Google Maps vergleichen.

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