Anfrageparameter

In diesem Dokument werden die Anfrageparameter für die Places Insights API beschrieben. Außerdem finden Sie hier Statistiken 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 mit 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 eine center und eine 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 zwischen -90 und 90 liegen. 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. Hinweis: Nicht alle Orts-IDs haben eine klar definierte Geometrie. In diesen Fällen gibt die Places Insights API den Fehlercode 400 mit der Meldung zurück, dass die Region nicht unterstützt wird.

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

Zu den nicht unterstützten Ortstypen gehören:

  • establishment gibt normalerweise einen Ort an, der noch nicht kategorisiert wurde.
  • street_number: gibt die genaue Hausnummer an.
  • floor: Gibt das Stockwerk innerhalb einer Gebäudeadresse an.
  • post_box: gibt einen bestimmten Briefkasten an.
  • street_address: gibt eine genaue Adresse an.
  • room: gibt den Raum innerhalb einer Gebäudeadresse an.
  • intersection: Gibt eine größere Kreuzung, üblicherweise von zwei Hauptstraßen an.
  • landmark: Gibt einen Ort in der Nähe an, der als Referenz zur Orientierung dient.
  • subpremise: Gibt eine adressierbare Entität unterhalb der Standortebene an, z. B. eine Wohnung, eine Einheit oder eine Suite.
  • sublocality_level_5: Die spezifischeste Ebene der untergeordneten Ortsteiladressen. Sie steht in der Regel für eine sehr kleine Ortsteilunterteilung oder einen hyperlokalen Bereich innerhalb einer Stadt.
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.

Hintereinander identische Koordinaten werden als einzelne Koordinate behandelt. Nicht aufeinanderfolgende doppelte Koordinaten (außer den 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. Das bedeutet, dass benachbarte Eckpunkte nicht antipodal 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

Mit dem Filter operatingStatus können Sie nach Betriebsstatus filtern, z. B. „Geöffnet“ oder „Vorübergehend geschlossen“. Wenn der operatingStatus-Filter nicht festgelegt ist, werden nur Orte mit dem Betriebsstatus OPERATING_STATUS_OPERATIONAL in die Ergebnisse aufgenommen.

Preisniveau

Mit dem Filter price_levels können Sie nach Preisniveau filtern, z. B. „Kostenlos“, „Mittel“ oder „Teuer“. Wenn der Filter price_levels nicht festgelegt ist, werden alle Preisstufen in die Ergebnisse einbezogen.

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).

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.