Parametry żądania

Z tego dokumentu dowiesz się więcej o parametrach żądania w interfejsie Places Aggregate API oraz znajdziesz wskazówki i sprawdzone metody korzystania z tej usługi.

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

• Count places (Zlicz miejsca): określa liczbę miejsc, które spełniają określone kryteria, takie jak typ lokalizacji, status działalności, poziom cen i oceny.
• Retrieve place details (Pobierz szczegóły miejsca): pobiera nazwy miejsc, które spełniają określone filtry, a następnie pobiera bardziej szczegółowe informacje za pomocą interfejsu Places API.
• Elastyczne filtrowanie: stosuje kompleksowe filtry, aby uzyskać dokładne 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 opisujemy 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 pasujących do kryteriów filtra.
• INSIGHT_PLACES: zwraca identyfikatory miejsc pasujących do kryteriów filtra.

Uwaga: jeśli wybierzesz INSIGHT_PLACES, interfejs Places Aggregate API zwróci identyfikatory miejsc tylko wtedy, gdy wartość count wynosi 100 lub mniej.

Filtry

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

Filtr lokalizacji

Filtr lokalizacji może mieć jeden 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.

Ważne: obszar dla dowolnego filtra lokalizacji musi mieć powierzchnię od 1556,86 m² (mniej więcej wielkość małego bloku miejskiego) do 2 bilionów m² (mniej więcej wielkość Alaski). Żądania dotyczące obszarów poza tym zakresem będą zwracać błąd INVALID_ARGUMENT.

Uwaga: w przypadku elementów z określonymi granicami wielokątnymi, takimi jak parki lub lotniska, element jest uznawany za znajdujący się w obszarze wyszukiwania, jeśli jakakolwiek część jego wielokąta przecina zdefiniowany obszar wyszukiwania (okrąg, region lub niestandardowy wielokąt). Punkt środkowy elementu nie musi znajdować się w obszarze wyszukiwania.

Okrąg

Jeśli wybierzesz obszar geograficzny jako okrąg, musisz podać center i radius. Właściwość center może być szerokością i długością geograficzną lub identyfikatorem miejsca środka okręgu. Ta metoda umożliwia dokładne filtrowanie na podstawie zdefiniowanego regionu kołowego.

• 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 punktowe. Ten ciąg znaków musi zaczynać się od przedrostka places/.
• radius: promień okręgu w metrach. Ta liczba musi być dodatnia.

Region

Aby zdefiniować obszar jako region, przekaż 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 na Florydzie 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 wskazującym, że region nie jest obsługiwany. Ponadto w przypadku złożonych regionów geograficznych wewnętrzne optymalizacje przetwarzania mogą prowadzić do niewielkiego przeszacowania obszaru (do 2–3%) reprezentującego region.

Ważne: gdy używasz filtra region z typem statystyk INSIGHT_PLACES, żądania obejmujące obszary sporne są automatycznie odrzucane, aby zapewnić dokładność i neutralność usług Google. Obszary sporne to regiony o sprzecznych granicach lub roszczeniach terytorialnych różnych krajów lub podmiotów. Sporne granice są oznaczone na Mapach Google szarą linią przerywaną.

Więcej informacji o tym, jak identyfikowane są regiony sporne, znajdziesz w artykule Granice i nazwy państw.

Ważne: Google nie obsługuje niektórych identyfikatorów miejsc, które należą do tych typów regionów:

• Typy regionów, które są tak duże, że powodują duże opóźnienia.
• Typy regionów, które są tak małe, że naruszają zgodność z zasadami ochrony prywatności.

Aby sprawdzić, czy identyfikator miejsca reprezentuje nieobsługiwany typ miejsca, przekaż go w żądaniu do interfejsu Geocoding API. Odpowiedź zawiera tablicę type z listą typów miejsc powiązanych z identyfikatorem miejsca, takich jak locality, neighborhood czy 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 wskazuje miejsce, które nie zostało jeszcze skategoryzowane.
• intersection: wskazuje główne skrzyżowanie, zwykle 2 głównych dróg.
• subpremise: wskazuje adresowalny element poniżej poziomu lokalu, np. mieszkanie, lokal lub apartament.

Uwaga: nawet niektóre miejsca nie wymienione powyżej mogą zostać odrzucone, jeśli nie mają dobrze zdefiniowanej geometrii wielokąta. Jest to częstsze w przypadku typów takich jak neighborhood, locality, sublocality i ich wariantów numerowanych (sublocality_level_1, sublocality_level_2, sublocality_level_3, sublocality_level_4). W takim przypadku zwracany jest kod błędu 400.

Obszar niestandardowy

Definiuje obszar niestandardowego wielokąta za pomocą współrzędnych geograficznych.

Ważne: współrzędne określające wierzchołki wielokąta muszą być podane w kolejności przeciwnej do ruchu wskazówek zegara.

Jest to zgodne z przyjętą w branży konwencją definiowania wielokątów, w której kolejność przeciwna do ruchu wskazówek zegara oznacza, że wnętrze wielokąta znajduje się po lewej stronie krawędzi granicy.Ważne:obszary niestandardowe muszą mieć nie więcej niż 7000 wierzchołków.

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

Kolejne identyczne współrzędne będą traktowane jako jedna współrzędna. Jednak niekolejne duplikaty współrzędnych (inne niż wymagane identyczne współrzędne pierwsza i ostatnia) spowodują błąd.

Ponadto nie są dozwolone przecinające się krawędzie nieprzylegające ani 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ędnione lub wykluczone. Listę typów miejsc podstawowych i dodatkowych obsługiwanych przez interfejs Places Aggregate API znajdziesz w tabeli A w sekcji Typy miejsc w dokumentacji interfejsu Places API (nowego). 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 podstawowych 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 artykule Filtry typu.

Uwaga: Filtry typu automatycznie uwzględniają podtypy określonych typów. Jeśli na przykład filtrujesz według gym, wyniki będą też obejmować miejsca, które są skategoryzowane w podtypach, takich jak yoga_studio.

Parametry opcjonalne

Te filtry są opcjonalne:

• operatingStatus: określa statusy miejsc, które mają być uwzględnione lub wykluczone. Domyślnie filtrowanie odbywa się według operatingStatus: OPERATING_STATUS_OPERATIONAL (jedna konkretna wartość).
• 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 jest stosowane filtrowanie (w wynikach uwzględniane są wszystkie oceny).

Status działalności

Za pomocą filtra operatingStatus możesz filtrować według statusu działalności takiego jak OPERATIONAL lub TEMPORARILY_CLOSED. Filtr operatingStatus działa w ten sposób:

• Jeśli nie podano żadnych filtrów, w wynikach uwzględniane są tylko miejsca ze statusem działalności OPERATING_STATUS_OPERATIONAL.
• Jeśli podano co najmniej 1 filtr, musisz określić prawidłowe wartości statusu działalności (OPERATING_STATUS_OPERATIONAL, OPERATING_STATUS_PERMANENTLY_CLOSED lub OPERATING_STATUS_TEMPORARILY_CLOSED).

Poziom cen

Za pomocą filtra priceLevels możesz filtrować miejsca według ich 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.

Filtr priceLevels działa w ten sposób:

• Jeśli nie podano żadnych filtrów: zwracane są wszystkie miejsca, niezależnie od tego, czy mają przypisany poziom cen. Obejmuje to miejsca bez informacji o poziomie cen, które mogą nie zostać zwrócone 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 ich średnich ocen użytkowników. Oba te pola są opcjonalne, więc jeśli je pominiesz, domyślnie będą też uwzględniane 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).

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