Parametry żądania

W tym dokumencie opisujemy parametry żądań interfejsu Places Aggregate API oraz podajemy wskazówki i sprawdzone metody korzystania z tej usługi.

Interfejs Places Aggregate API umożliwia wykonywanie kilku kluczowych funkcji:

• Zliczanie miejsc: określanie liczby miejsc, które spełniają określone kryteria, takie jak typ lokalizacji, stan działania, poziom cen i oceny.
• Pobieranie szczegółów miejsca: pobieranie nazw miejsc, które spełniają określone filtry, a następnie uzyskiwanie bardziej szczegółowych informacji za pomocą interfejsu Places API.
• Elastyczne filtrowanie: stosuj kompleksowe filtry, aby uzyskiwać precyzyjne agregacje. Dostępne filtry:
  • Obszar geograficzny (okrąg, region lub niestandardowy wielokąt)
  • Typy miejsc
  • Status działalności
  • Poziomy cen
  • Zakresy ocen

Wymagane parametry

W tej sekcji omawiamy parametry wymagane podczas wysyłania żądania do interfejsu Places Aggregate API. Każde żądanie musi zawierać te informacje:

• Typ statystyk.
• filtr lokalizacji i filtr typu;

Typ statystyk

Określa typ statystyk, które chcesz obliczyć. Obsługiwane są te typy statystyk:

• INSIGHT_COUNT: zwraca liczbę miejsc spełniających kryteria filtra.
• INSIGHT_PLACES: zwraca identyfikatory miejsc pasujące do kryteriów filtra.

Filtry

Określa kryteria filtrowania miejsc. Musisz podać co najmniej atrybuty LocationFilter i TypeFilter.

Filtr lokalizacji

Filtr lokalizacji może być jednego z tych typów:

• circle: definiuje obszar jako okrąg o określonym środku i promieniu.
• region: definiuje obszar jako region.
• customArea: definiuje obszar jako niestandardowy wielokąt.

Okrąg

Jeśli wybierzesz obszar geograficzny w postaci okręgu, musisz podać center i radius. center może być szerokością i długością geograficzną lub identyfikatorem miejsca środka okręgu. Ta metoda umożliwia precyzyjne i dokładne filtrowanie na podstawie zdefiniowanego przez Ciebie regionu w kształcie koła.

• center:
  • latLng: szerokość i długość geograficzna środka okręgu. Szerokość geograficzna musi być liczbą z zakresu od -90 do 90 (włącznie). Długość geograficzna musi być liczbą z zakresu od -180 do 180 (włącznie).
  • place: identyfikator miejsca środka okręgu. Pamiętaj, że obsługiwane są tylko miejsca typu punkt. Ten ciąg znaków musi zaczynać się od przedrostka places/.
• radius: promień okręgu w metrach. Ta liczba musi być dodatnia.

Region

Zdefiniuj obszar jako region, przekazując identyfikator miejsca do parametru place. Identyfikator miejsca reprezentuje obszar geograficzny (np. obszar, który można przedstawić za pomocą wielokąta). Na przykład identyfikator miejsca Tampa, FL to places/ChIJ4dG5s4K3wogRY7SWr4kTX6c. Pamiętaj, że nie wszystkie identyfikatory miejsc mają dobrze zdefiniowaną geometrię. W takich przypadkach interfejs Places Aggregate API zwraca kod błędu 400 z komunikatem informującym, że region nie jest obsługiwany. Dodatkowo w przypadku złożonych regionów geograficznych wewnętrzne optymalizacje przetwarzania mogą prowadzić do niewielkiego zawyżenia obszaru (do 2–3%) reprezentującego region.

Aby sprawdzić, czy identyfikator miejsca reprezentuje nieobsługiwany typ miejsca, przekaż identyfikator miejsca w żądaniu do interfejsu Geocoding API. Odpowiedź zawiera tablicę type z listą typów miejsc powiązanych z identyfikatorem miejsca, np. locality, neighborhood lub country. Miejsce zostanie odrzucone w przypadku filtrowania według regionu, jeśli którykolwiek z jego typów pasuje do tej listy.

Nieobsługiwane typy miejsc:

• establishment: zwykle oznacza miejsce, które nie zostało jeszcze skategoryzowane.
• intersection: oznacza duże skrzyżowanie, zwykle dwóch dróg głównych.
• subpremise: wskazuje adresowalny obiekt poniżej poziomu lokalu, np. mieszkanie, lokal lub apartament.

Obszar niestandardowy

Określa obszar niestandardowego wielokąta za pomocą współrzędnych geograficznych.

Aby narysować niestandardowy wielokąt i wpisać te współrzędne w żądaniu, otwórz stronę https://geojson.io/. Wielokąt musi mieć co najmniej 4 współrzędne, przy czym pierwsza i ostatnia muszą być identyczne. Co najmniej 3 podane współrzędne muszą być unikalne.

Kolejne identyczne współrzędne będą traktowane jako pojedyncze współrzędne. Jednak niekolejne zduplikowane współrzędne (inne niż wymagane identyczne współrzędne pierwszego i ostatniego punktu) spowodują błąd.

Ponadto niedozwolone są przecinające się krawędzie nieprzylegające oraz krawędzie o długości 180 stopni (tzn. sąsiednie wierzchołki nie mogą być antypodalne).

Na przykład:

"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
   }
]

Filtr typu

Określa typy miejsc, które mają być uwzględniane lub wykluczane. Listę podstawowych i dodatkowych typów miejsc obsługiwanych przez Places Aggregate API znajdziesz w tabeli A w sekcji Typy miejsc w artykule o interfejsie Places API (nowym). Musisz podać co najmniej 1 typ includedTypes lub includedPrimaryTypes.

• includedTypes: lista uwzględnionych typów miejsc.
• excludedTypes: Lista wykluczonych typów miejsc.
• includedPrimaryTypes: lista uwzględnionych głównych typów miejsc.
• excludedPrimaryTypes: lista wykluczonych podstawowych typów miejsc.

Więcej informacji o tym, jak działają filtry typu i typy miejsc, znajdziesz w tym artykule.

Parametry opcjonalne

Te filtry są opcjonalne:

• operatingStatus: określa stany miejsc, które mają być uwzględnione lub wykluczone. Domyślnie filtrowanie odbywa się według operatingStatus: OPERATING_STATUS_OPERATIONAL (jednej konkretnej wartości).
• priceLevels: określa poziomy cen miejsc, które mają być uwzględnione. Domyślnie nie jest stosowane filtrowanie według poziomu cen i zwracane są wszystkie miejsca (w tym te, które nie mają informacji o poziomie cen).
• ratingFilter: określa zakres ocen miejsc. Domyślnie nie ma filtrowania (wszystkie oceny są uwzględniane w wynikach).

Status działalności

Za pomocą filtra operatingStatus możesz filtrować według stanu operacyjnego, np. OPERATIONAL lub TEMPORARILY_CLOSED. Działanie filtra operatingStatus jest następujące:

• Jeśli nie podano żadnych filtrów, w wynikach uwzględniane są tylko miejsca o stanie działaniaOPERATING_STATUS_OPERATIONAL.
• Jeśli podasz co najmniej 1 filtr, musisz określić prawidłowe wartości stanu operacyjnego (OPERATING_STATUS_OPERATIONAL, OPERATING_STATUS_PERMANENTLY_CLOSED lub OPERATING_STATUS_TEMPORARILY_CLOSED).

Poziom cen

Za pomocą filtra priceLevels możesz filtrować miejsca na podstawie poziomu cen. Prawidłowe wartości poziomu cen to: PRICE_LEVEL_FREE, PRICE_LEVEL_INEXPENSIVE, PRICE_LEVEL_MODERATE, PRICE_LEVEL_EXPENSIVE i PRICE_LEVEL_VERY_EXPENSIVE.

Działanie filtra priceLevels jest następujące:

• Jeśli nie podano filtrów: zwracane są wszystkie miejsca, niezależnie od tego, czy mają przypisany poziom cen. Dotyczy to miejsc bez informacji o poziomie cen, które mogą nie być zwracane podczas filtrowania według określonych poziomów cen.
• Jeśli podano co najmniej 1 filtr: zwracane są tylko miejsca pasujące do określonych poziomów cen.

Filtr: oceny

Filtruje miejsca na podstawie średnich ocen użytkowników. Oba te pola są opcjonalne, więc jeśli zostaną pominięte, domyślnie będą obejmować również miejsca, które nie mają oceny.

• minRating: minimalna średnia ocena użytkowników (od 1,0 do 5,0).
• maxRating: maksymalna średnia ocena użytkowników (od 1,0 do 5,0).

Dodatkowo wartość minRating musi być zawsze mniejsza lub równa wartości maxRating. Jeśli wartość minRating jest większa niż maxRating, zwracany jest błąd INVALID_ARGUMENT.