Anfrageparameter

In diesem Dokument werden die Anfrageparameter für die Places Insights API beschrieben. Außerdem finden Sie hier Informationen und Best Practices für die Nutzung dieses Dienstes.

Mit der Places Insights API können Sie mehrere wichtige Funktionen ausführen:

  • Orte zählen: Sie können die Anzahl der Orte ermitteln, die bestimmten Kriterien entsprechen, z. B. Standorttyp, Betriebsstatus, Preisniveau und Bewertungen.
  • Ortsdetails abrufen: Sie können die Namen von Orten abrufen, die den angegebenen Filtern entsprechen, und dann mithilfe der Places API detailliertere Informationen abrufen.
  • Flexible Filterung: Sie können umfassende Filter anwenden, um präzise Statistiken zu erhalten. Folgende Filter sind verfügbar:
    • Geografisches Gebiet (Kreis, Region oder benutzerdefiniertes Polygon)
    • Ortstypen
    • Öffnungsstatus
    • Preisniveaus
    • Altersfreigabebereiche

Erforderliche Parameter

In diesem Abschnitt werden die erforderlichen Parameter für die Abgabe einer Anfrage an die Places Insights API beschrieben. Jede Anfrage muss Folgendes enthalten:

  • Eine Art von Statistik.
  • Standort- und Typfilter

Statistiktyp

Gibt an, welche Statistiken berechnet werden sollen. Die folgenden Typen von Informationen werden unterstützt:

  • INSIGHT_COUNT: Gibt die Anzahl der Orte zurück, die den Filterkriterien entsprechen.

  • INSIGHT_PLACES: Gibt die Orts-IDs zurück, die den Filterkriterien entsprechen.

    Hinweis: Wenn Sie INSIGHT_PLACES auswählen, gibt die Places Insights API nur Orts-IDs zurück, wenn die count 100 oder weniger beträgt.

Filter

Gibt die Kriterien für das Filtern von Orten an. Sie müssen mindestens LocationFilter und TypeFilter angeben.

Filter für Standort

Es gibt folgende Arten von Standortfiltern:

  • circle: Definiert einen Bereich als Kreis mit Mittelpunkt und Radius.
  • region: Damit wird ein Gebiet als Region definiert.
  • customArea: Hiermit wird ein Bereich als benutzerdefiniertes Polygon definiert.
Kreis

Wenn Sie Ihren geografischen Bereich als Kreis auswählen, müssen Sie einen center und einen radius angeben. Der Mittelpunkt kann entweder ein Breiten- und Längengrad oder die Orts-ID des Mittelpunkts des Kreises sein.

  • center:
    • latLng: Breiten- und Längengrad des Mittelpunkts des Kreises. Breitengrade müssen eine Zahl zwischen -90 und 90 sein. Der Längengrad muss eine Zahl zwischen -180 und 180 sein.
    • place: Die Orts-ID des Mittelpunkts des Kreises. Es werden nur Orte unterstützt, die sich an einem Punkt befinden. Dieser String muss mit dem Präfix places/ beginnen.
  • radius: Radius des Kreises in Metern. Diese Zahl muss positiv sein.
Region

Definieren Sie Ihren Bereich als Region, indem Sie dem Parameter place eine Orts-ID übergeben. Die Orts-ID steht für ein geografisches Gebiet, z. B. ein Gebiet, das durch ein Polygon dargestellt werden kann. Die Orts-ID von Tampa, FL, lautet beispielsweise places/ChIJ4dG5s4K3wogRY7SWr4kTX6c. Beachten Sie, dass nicht alle Orts-IDs eine klar definierte Geometrie haben. In diesen Fällen gibt die Places Insights API den Fehlercode 404 zurück.

In der folgenden Tabelle sind nicht unterstützte Regionstypen aufgeführt. Wenn Sie feststellen möchten, ob eine Orts-ID einen nicht unterstützten Regionstyp darstellt, geben Sie die Orts-ID in einer Geocoding API-Anfrage an. Die Antwort enthält das Array type mit den Regionen, die mit der Orts-ID verknüpft sind, z. B. city, neighborhood oder country.

Nicht unterstützte Regionstypen
establishment place_of_worship
floor post_box
food postal_code_suffix
general_contractor room
geocode street_address
health street_number
intersection sublocality_level_5
landmark subpremise
Benutzerdefinierter Bereich

Definiert die Fläche eines benutzerdefinierten Polygons anhand von Breiten- und Längengraden.

Unter https://geojson.io/ können Sie ein benutzerdefiniertes Polygon zeichnen und die entsprechenden Koordinaten in die Anfrage eingeben. Ein Polygon muss mindestens vier Koordinaten haben, wobei die erste und die letzte Koordinate identisch sind. Mindestens drei der angegebenen Koordinaten müssen eindeutig sein. Außer den ersten und letzten Koordinaten dürfen keine weiteren doppelten Koordinaten vorhanden sein. Außerdem dürfen sich nicht benachbarte Kanten nicht schneiden und Kanten mit einer Länge von 180 Grad sind nicht zulässig. Das bedeutet, dass benachbarte Eckpunkte nicht Antipoden sein dürfen.

Beispiel:

"coordinates":[
   {
      "latitude":37.776,
      "longitude":-122.666
   },
   {
      "latitude":37.130,
      "longitude":-121.898
   },
   {
      "latitude":37.326,
      "longitude":-121.598
   },
   {
      "latitude":37.912,
      "longitude":-122.247
   },
   {
      "latitude":37.776,
      "longitude":-122.666
   }
]

Typfilter

Gibt die Arten von Orten an, die ein- oder ausgeschlossen werden sollen. Eine Liste der primären und sekundären Ortstypen, die von der Places Insights API unterstützt werden, finden Sie in Tabelle A unter Ortstypen für die Places API (neu). Sie müssen mindestens einen includedTypes- oder includedPrimaryTypes-Typ angeben.

  • includedTypes: Liste der enthaltenen Ortstypen.
  • excludedTypes: Liste der ausgeschlossenen Ortstypen.
  • includedPrimaryTypes: Liste der enthaltenen primären Ortstypen.
  • excludedPrimaryTypes: Liste der ausgeschlossenen primären Ortstypen.

Weitere Informationen zur Funktionsweise von Typfiltern und Ortstypen finden Sie unter Weitere Informationen zu Typfiltern.

Optionale Parameter

Diese Filter sind optional:

  • operatingStatus: Gibt die Status der Orte an, die ein- oder ausgeschlossen werden sollen. Standardmäßig wird nach operatingStatus: OPERATING_STATUS_OPERATIONAL (ein bestimmter Wert) gefiltert.
  • priceLevels: Gibt die Preisstufen der Unterkünfte an. Standardmäßig ist keine Filterung aktiviert (alle Preisstufen sind in den Ergebnissen enthalten).
  • ratingFilter: Gibt den Bewertungsbereich der Orte an. Standardmäßig ist kein Filter aktiviert (alle Bewertungen sind in den Ergebnissen enthalten).

Öffnungsstatus

Filtern Sie nach Betriebsstatus (z. B. „Geöffnet“ oder „Vorübergehend geschlossen“).

Preisniveau

Filtern Sie nach Preisniveau (z. B. kostenlos, mäßig oder teuer).

Filter „Bewertung“

Orte werden anhand ihrer durchschnittlichen Nutzerbewertungen gefiltert. Beide Felder sind optional. Wenn sie weggelassen werden, werden standardmäßig auch Orte ohne Bewertung berücksichtigt.

  • minRating: Mindestens durchschnittliche Nutzerbewertung (zwischen 1,0 und 5,0).
  • maxRating: Die höchste durchschnittliche Nutzerbewertung (zwischen 1,0 und 5,0).