Anfrageparameter

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

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

• Orte zählen: Ermitteln Sie die Anzahl der Orte, die bestimmten Kriterien entsprechen, z. B. Ortstyp, Öffnungsstatus, 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 beschrieben, wenn Sie eine Anfrage an die Places Aggregate API senden. Jede Anfrage muss Folgendes enthalten:

• Einen Statistiktyp.
• Einen Standortfilter und einen Typfilter.

Statistiktyp

Gibt den Statistiktyp an, den Sie berechnen möchten. Die folgenden Statistiktypen 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 Aggregate API Orts-IDs nur zurück, wenn count 100 oder weniger ist.

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 Mittelpunkt und Radius.
• region: Definiert einen Bereich als Region.
• customArea: Definiert einen Bereich als benutzerdefiniertes Polygon.

Wichtig: Die Fläche für einen Standortfilter muss zwischen 1.556,86 Quadratmetern (ungefähr die Größe eines kleinen Häuserblocks) und 2 Billionen Quadratmetern (ungefähr die Größe von Alaska) liegen. Bei Anfragen mit Bereichen außerhalb dieses Bereichs wird ein INVALID_ARGUMENT Fehler zurückgegeben.

Hinweis: Bei Entitäten mit definierten polygonalen Grenzen wie Parks oder Flughäfen gilt die Entität als innerhalb des Suchbereichs, wenn sich ein Teil des Polygons mit dem definierten Suchbereich (Kreis, Region oder benutzerdefiniertes Polygon) überschneidet. Der Mittelpunkt der Entität muss sich nicht im Suchbereich befinden.

Kreis

Wenn Sie Ihr geografisches Gebiet als Kreis auswählen, müssen Sie einen center und einen radius angeben. Der center kann entweder ein Breiten- und Längengrad oder die Orts-ID des Mittelpunkts des Kreises sein. Diese Methode ermöglicht eine präzise und genaue Filterung basierend auf Ihrer definierten kreisförmigen Region.

• center:
  • latLng: Breiten- und Längengrad des Mittelpunkts des Kreises. Die Breitengrade müssen eine Zahl zwischen -90 und 90 (einschließlich) sein. Die Längengrade müssen eine Zahl zwischen -180 und 180 (einschließlich) sein.
  • place: Orts-ID des Mittelpunkts des Kreises. 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 einen 400-Fehlercode mit einer Meldung zurück, die angibt, dass die Region nicht unterstützt wird. Außerdem kann es bei komplexen geografischen Regionen aufgrund interner Verarbeitungsoptimierungen zu einer leichten Überschätzung des Bereichs (bis zu 2–3%) kommen, der die Region darstellt.

Wichtig: Wenn Sie den Filter region mit dem Statistiktyp INSIGHT_PLACES verwenden, werden Anfragen mit umstrittenen Gebieten automatisch abgelehnt, um die Genauigkeit und Neutralität der Google-Dienste zu gewährleisten. Umstrittene Gebiete sind Regionen mit widersprüchlichen Grenzen oder Gebietsansprüchen verschiedener Länder oder Entitäten. Umstrittene Grenzen werden in Google Maps als gestrichelte graue Linie angezeigt.

Weitere Informationen dazu, wie umstrittene Regionen identifiziert werden, finden Sie unter Ländergrenzen und -namen.

Wichtig:Google unterstützt bestimmte Orts-IDs nicht, die zu den folgenden Arten von Regionstypen gehören:

• Regionstypen, die so groß sind, dass sie zu einer hohen Latenz führen.
• Regionstypen, die so klein sind, dass sie die Einhaltung der Datenschutzbestimmungen gefährden.

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 Array type 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 sind unter anderem:

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

Hinweis: Auch einige Orte, die nicht oben aufgeführt sind, können abgelehnt werden, wenn sie keine genau definierte Polygongeometrie haben. Dies ist häufiger bei Typen wie neighborhood, locality, sublocality und den nummerierten Varianten (sublocality_level_1, sublocality_level_2, sublocality_level_3, sublocality_level_4) der Fall. In diesem Fall wird ein 400-Fehlercode zurückgegeben.

Benutzerdefinierter Bereich

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

Wichtig: Die Koordinaten, die die Eckpunkte des Polygons definieren, müssen in entgegen dem Uhrzeigersinn angegeben werden. Dies entspricht der Branchenkonvention für die Definition von Polygonen, bei der die Reihenfolge entgegen dem Uhrzeigersinn angibt, dass sich das Innere des Polygons links von den Begrenzungskanten befindet.

Wichtig: Benutzerdefinierte Bereiche dürfen maximal 7.000 Eckpunkte haben.

Unter https://geojson.io/ können Sie ein benutzerdefiniertes Polygon zeichnen und diese Koordinaten in die Anfrage eingeben. Ein Polygon muss mindestens 4 Koordinaten haben, wobei die erste und die letzte Koordinate identisch sind. Mindestens 3 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 Eckpunkte 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
   }
]

Filtertyp

Gibt die Typen 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 (neu). Sie müssen mindestens einen Typ für includedTypes oder includedPrimaryTypes angeben.

• includedTypes: Liste der eingeschlossenen 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 finden Sie unter more on type filters.

Hinweis:Typfilter umfassen automatisch Untertypen der angegebenen Typen. Wenn Sie beispielsweise nach gym filtern, enthalten die Ergebnisse auch Orte, die unter den Untertypen kategorisiert sind, z. B. yoga_studio.

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 von Orten an, die eingeschlossen werden sollen. Standardmäßig wird keine Filterung nach Preisniveau angewendet und alle Orte (einschließlich derer 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 Öffnungsstatus filtern, z. B. OPERATIONAL oder TEMPORARILY_CLOSED. Das Verhalten des Filters operatingStatus ist wie folgt:

• Wenn keine Filter angegeben wurden, werden nur Orte mit dem Öffnungsstatus OPERATING_STATUS_OPERATIONAL in die Ergebnisse aufgenommen.
• Wenn ein oder mehrere Filter angegeben werden, müssen Sie gültige Werte für den Öffnungsstatus angeben (OPERATING_STATUS_OPERATIONAL, OPERATING_STATUS_PERMANENTLY_CLOSED oder OPERATING_STATUS_TEMPORARILY_CLOSED).

Preisniveau

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

Das Verhalten des Filters priceLevels ist wie folgt:

• Wenn keine Filter angegeben werden:Alle Orte werden zurückgegeben, unabhängig davon, ob ihnen ein Preisniveau zugewiesen ist. Dazu gehören Orte ohne Informationen zum Preisniveau, die möglicherweise nicht zurückgegeben werden, wenn nach bestimmten Preisniveaus gefiltert wird.
• Wenn ein oder mehrere Filter angegeben werden:Nur Orte, die dem/den angegebenen Preisniveau(s) entsprechen, werden zurückgegeben.

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: Mindestdurchschnittliche Nutzerbewertung (zwischen 1,0 und 5,0).
• maxRating: Höchstdurchschnittliche Nutzerbewertung (zwischen 1,0 und 5,0).

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