Anfrageparameter

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

Mit der Places Aggregate API können Sie verschiedene wichtige Funktionen ausführen:

  • Orte zählen: Ermitteln Sie die Anzahl der Orte, die bestimmten Kriterien entsprechen, z. B. Standorttyp, Betriebsstatus, Preisniveau und Bewertungen.
  • Ortsdetails abrufen: Rufen Sie die Namen von Orten ab, die den angegebenen Filtern entsprechen, und rufen Sie dann mit der Places API detailliertere Informationen ab.
  • Flexible Filterung: Wenden Sie umfassende Filter an, um genaue Aggregate zu erhalten. Folgende Filter sind verfügbar:
    • Geografisches Gebiet (Kreis, Region oder benutzerdefiniertes Polygon)
    • Ortstypen
    • Öffnungsstatus
    • Preisniveaus
    • Bewertungsbereiche

Erforderliche Parameter

In diesem Abschnitt werden die erforderlichen Parameter für eine Anfrage an die Places Aggregate API beschrieben. Für jede Anfrage müssen die folgenden Informationen angegeben werden:

  • Eine Art von Statistik.
  • Ein Standortfilter und ein Typfilter.

Statistiktyp

Gibt den Typ der zu berechnenden Statistiken an. 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.

Filter

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

Filter für Standort

Ein Standortfilter kann einen der folgenden Typen haben:

  • circle: Definiert einen Bereich als Kreis mit einem Mittelpunkt und einem Radius.
  • region: Definiert einen Bereich als Region.
  • customArea: Definiert einen Bereich als benutzerdefiniertes Polygon.
Kreis

Wenn Sie Ihren geografischen Bereich als Kreis auswählen, müssen Sie einen center und einen radius angeben. center kann entweder ein Breiten- und Längengrad oder die Orts-ID des Kreismittelpunkts sein. Diese Methode ermöglicht eine präzise und genaue Filterung basierend auf der von Ihnen definierten kreisförmigen Region.

  • center:
    • latLng: Breiten- und Längengrad des Kreismittelpunkts. Der Breitengrad muss eine Zahl zwischen -90 und 90 sein. Der Längengrad muss eine Zahl zwischen -180 und 180 (einschließlich) sein.
    • place: Orts-ID des Kreismittelpunkts. Es werden nur Orte mit einem Punkt unterstützt. 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 eine Orts-ID an den Parameter place ü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, Florida, ist beispielsweise places/ChIJ4dG5s4K3wogRY7SWr4kTX6c. Nicht alle Orts-IDs haben eine genau definierte Geometrie. In diesen Fällen gibt die Places Aggregate API den Fehlercode 400 mit einer Meldung zurück, die angibt, dass die Region nicht unterstützt wird. Bei komplexen geografischen Regionen kann es außerdem aufgrund interner Verarbeitungsoptimierungen zu einer leichten Überschätzung der Fläche (bis zu 2–3%) kommen, die die Region repräsentiert.

Wenn Sie feststellen möchten, ob eine Orts-ID einen nicht unterstützten Ortstyp darstellt, übergeben Sie die Orts-ID in einer Geocoding API-Anfrage. Die Antwort enthält das type-Array mit den Ortstypen, die mit der Orts-ID verknüpft sind, z. B. locality, neighborhood oder country. Ein Ort wird für die Regionsfilterung abgelehnt, wenn einer seiner Typen mit dieser Liste übereinstimmt.

Nicht unterstützte Ortstypen:

  • establishment gibt normalerweise einen Ort an, der noch nicht kategorisiert wurde.
  • intersection: Gibt eine größere Kreuzung, üblicherweise von zwei Hauptstraßen an.
  • subpremise: Gibt eine adressierbare Einheit unterhalb der Ebene des Grundstücks an, z. B. eine Wohnung, Einheit oder Suite.
Benutzerdefinierter Bereich

Definiert den Bereich eines benutzerdefinierten Polygons mithilfe von Breiten- und Längengradkoordinaten.

Unter https://geojson.io/ können Sie ein benutzerdefiniertes Polygon zeichnen und die Koordinaten in die Anfrage eingeben. Ein Polygon muss mindestens vier Koordinaten haben, wobei die erste und die letzte Koordinate identisch sein müssen. Mindestens drei der angegebenen Koordinaten müssen eindeutig sein.

Aufeinanderfolgende identische Koordinaten werden als eine einzelne Koordinate behandelt. Nicht aufeinanderfolgende doppelte Koordinaten (mit Ausnahme der erforderlichen identischen ersten und letzten Koordinaten) führen jedoch zu einem Fehler.

Außerdem dürfen sich nicht benachbarte Kanten nicht schneiden und Kanten mit einer Länge von 180 Grad sind nicht zulässig (d. h. benachbarte Knoten dürfen nicht antipodal sein).

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 Aggregate API unterstützt werden, finden Sie in Tabelle A unter Ortstypen für die Places API (New). Sie müssen mindestens einen includedTypes- oder includedPrimaryTypes-Typ angeben.

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

Weitere Informationen zu Typfiltern und Ortstypen

Optionale Parameter

Diese Filter sind optional:

  • operatingStatus: Gibt die Status von Orten an, die ein- oder ausgeschlossen werden sollen. Standardmäßig wird nach operatingStatus: OPERATING_STATUS_OPERATIONAL (einem bestimmten Wert) gefiltert.
  • priceLevels: Gibt die Preisniveaus der Orte an, die berücksichtigt werden sollen. Standardmäßig wird keine Filterung nach Preisniveau angewendet und alle Orte (auch solche ohne Informationen zum Preisniveau) werden zurückgegeben.
  • ratingFilter: Gibt den Bewertungsbereich der Orte an. Standardmäßig wird nicht gefiltert (alle Bewertungen sind in den Ergebnissen enthalten).

Öffnungsstatus

Mit dem Filter operatingStatus können Sie nach Betriebsstatus filtern, z. B. nach OPERATIONAL oder TEMPORARILY_CLOSED. So funktioniert das operatingStatus-Filterverhalten:

  • Wenn keine Filter angegeben wurden, werden in den Ergebnissen nur Orte mit dem Betriebsstatus OPERATING_STATUS_OPERATIONAL berücksichtigt.
  • Wenn ein oder mehrere Filter angegeben sind, müssen Sie gültige Werte für den Betriebsstatus angeben (OPERATING_STATUS_OPERATIONAL, OPERATING_STATUS_PERMANENTLY_CLOSED oder OPERATING_STATUS_TEMPORARILY_CLOSED).

Preisniveau

Mit dem Filter priceLevels können Sie Orte nach ihrem Preisniveau filtern. Gültige Werte für die Preisstufe sind: PRICE_LEVEL_FREE, PRICE_LEVEL_INEXPENSIVE, PRICE_LEVEL_MODERATE, PRICE_LEVEL_EXPENSIVE und PRICE_LEVEL_VERY_EXPENSIVE.

So funktioniert der Filter priceLevels:

  • Wenn keine Filter angegeben sind:Alle Orte werden zurückgegeben, unabhängig davon, ob ihnen ein Preisniveau zugewiesen ist. Dazu gehören auch Orte ohne Informationen zur Preisstufe, die möglicherweise nicht zurückgegeben werden, wenn nach bestimmten Preisstufen gefiltert wird.
  • Wenn ein oder mehrere Filter angegeben werden:Es werden nur Orte zurückgegeben, die dem angegebenen Preisniveau bzw. den angegebenen Preisniveaus entsprechen.

Filter „Bewertung“

Filtert Orte nach ihren durchschnittlichen Nutzerbewertungen. Beide Felder sind optional. Wenn sie weggelassen werden, werden standardmäßig auch Orte ohne Bewertung berücksichtigt.

  • minRating: Mindestdurchschnittsnutzerbewertung (zwischen 1,0 und 5,0).
  • maxRating: Maximale durchschnittliche Nutzerbewertung (zwischen 1,0 und 5,0).

Außerdem muss der Wert minRating immer kleiner oder gleich dem Wert maxRating sein. Wenn minRating größer als maxRating ist, wird der Fehler INVALID_ARGUMENT zurückgegeben.