Parametry żądania

Ten dokument opisuje parametry żądania interfejsu Places Aggregate API oraz zawiera statystyki i sprawdzone metody korzystania z tej usługi.

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, status działalności, poziom cen i oceny.
• Pobieranie informacji o miejscu: uzyskaj nazwy miejsc, które spełniają określone filtry, a następnie pobierz bardziej szczegółowe informacje za pomocą interfejsu Places API.
• Elastyczne filtrowanie: stosuj kompleksowe filtry, aby uzyskiwać precyzyjne dane zbiorcze. Dostępne filtry:
  • obszar geograficzny (okrąg, region lub niestandardowy wielokąt);
  • Typy miejsc
  • Status działalności
  • Poziomy cenowe
  • Zakresy ocen

Wymagane parametry

W tej sekcji opisano 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ące 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 ze środkiem i promieniem.
• region: definiuje obszar jako region.
• customArea: definiuje obszar jako niestandardowy wielokąt.

Ważne: obszar filtra lokalizacji musi mieć od 1556,86 m² (mniej więcej wielkość małego kwartału ulic) do 2 bilionów m² (mniej więcej wielkość Alaski). Żądania z obszarami spoza tego zakresu zwrócą błąd INVALID_ARGUMENT.

Uwaga: w przypadku elementów ze zdefiniowanymi granicami wielokątnymi, takich jak parki czy lotniska, element jest uznawany za znajdujący się w obszarze wyszukiwania, jeśli jakakolwiek część jego wielokąta przecina się ze zdefiniowanym obszarem wyszukiwania (okręgiem, regionem lub niestandardowym wielokątem). Punkt środkowy elementu nie musi znajdować się w obszarze wyszukiwania.

Okrąg

Jeśli wybierzesz obszar geograficzny w postaci okręgu, musisz podać center i radius. Parametr center może być szerokością i długością geograficzną lub identyfikatorem miejsca w centrum okręgu. Ta metoda umożliwia precyzyjne i 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 prefiksu 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 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, że region nie jest obsługiwany. Dodatkowo w przypadku złożonych regionów geograficznych optymalizacje przetwarzania wewnętrznego mogą prowadzić do nieznacznego zawyżenia przybliżonego obszaru (do 2–3%) reprezentującego dany 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, w których granice lub roszczenia terytorialne różnych krajów lub podmiotów są sprzeczne. Sporne granice są oznaczone w Mapach Google szarymi liniami przerywanymi.

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ż identyfikator miejsca w żądaniu do interfejsu Geocoding API. Odpowiedź zawiera tablicę type z listą typów miejsc powiązanych z identyfikatorem miejsca, takich jak locality, neighborhood lub country. Miejsce zostanie odrzucone w przypadku filtrowania według regionu, jeśli dowolny z jego typów pasuje do tej listy.

Nieobsługiwane typy miejsc:

• establishment: zwykle oznacza 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: niektóre miejsca niewymienione powyżej mogą zostać odrzucone, jeśli nie mają dobrze zdefiniowanej geometrii wielokąta. Zdarza się to częściej w przypadku typów takich jak neighborhood, locality, sublocality i ich wariantów liczbowych (sublocality_level_1, sublocality_level_2, sublocality_level_3, sublocality_level_4). W takim przypadku zwracany jest kod błędu 400.

Obszar niestandardowy

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

Ważne: współrzędne definiujące wierzchołki wielokąta muszą być podane w kolejności w lewo. Jest to zgodne ze standardową konwencją branżową 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 granicznych.

Ważne: obszary niestandardowe mogą mieć maksymalnie 7000 wierzchołków.

Możesz wejść na stronę https://geojson.io/, aby narysować niestandardowy wielokąt i wpisać jego współrzędne w żądaniu. Wielokąt musi mieć co najmniej 4 współrzędne, przy czym pierwsza i ostatnia muszą być identyczne. Co najmniej 3 z podanych współrzędnych muszą być unikalne.

Identyczne współrzędne występujące po sobie będą traktowane jako pojedyncze współrzędne. Jednak nieprzylegające do siebie powtarzające się współrzędne (inne niż wymagane identyczne współrzędne pierwszego i ostatniego punktu) spowodują błąd.

Dodatkowo krawędzie, które nie są przyległe, nie mogą się przecinać, a krawędzie o długości 180 stopni są niedozwolone (czyli przyległe wierzchołki nie mogą być przeciwległe).

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 typów

Określa typy miejsc, które mają zostać uwzględnione lub wykluczone. Listę głównych i dodatkowych typów miejsc obsługiwanych przez Places Aggregate API znajdziesz w tabeli A w sekcji Typy miejsc w dokumentacji 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 głównych typów miejsc.
• excludedPrimaryTypes: lista wykluczonych głównych typów miejsc.

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

Uwaga: filtry typów automatycznie uwzględniają podtypy określonych typów. Jeśli na przykład filtrujesz według kategorii gym, wyniki będą też obejmować miejsca należące do jej podtypów, takich jak yoga_studio.

Parametry opcjonalne

Te filtry są opcjonalne:

• operatingStatus: określa stany miejsc, które mają zostać 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ą zostać uwzględnione. Domyślnie nie stosuje się filtrowania według poziomu cen i zwracane są wszystkie miejsca (w tym te, które nie zawierają informacji o poziomie cen).
• ratingFilter: określa zakres ocen miejsc. Domyślnie nie ma filtrowania (w wynikach uwzględniane są wszystkie oceny).

Status działalności

Filtr operatingStatus umożliwia filtrowanie na podstawie statusu działalności, np. 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 o statusie 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 na podstawie 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 następujący sposób:

• Jeśli nie podasz ż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 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ą uwzględniać 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.