Parametry żądania

Ten dokument zawiera opis parametrów żądań interfejsu Places Insights API oraz statystyki i sprawdzone metody dotyczące korzystania z tej usługi.

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

  • Liczba miejsc: określa liczbę miejsc pasujących do określonych kryteriów, takich 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 pobieranie bardziej szczegółowych informacji za pomocą interfejsu Places API.
  • Elastyczne filtrowanie: możesz stosować kompleksowe filtry, aby uzyskiwać dokładne statystyki. Dostępne filtry:
    • Obszar geograficzny (okrąg, region lub niestandardowy wielokąt)
    • Typy miejsc
    • Stan działania
    • Poziomy cen
    • Zakresy ocen

Wymagane parametry

W tej sekcji omawiamy parametry wymagane do wysłania żądania do interfejsu Places Insights 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.

Filtry

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

Filtr lokalizacji

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

  • circle: definiuje obszar jako okrąg z środkiem i promieniem.
  • region: definiuje obszar jako region.
  • customArea: definiuje obszar jako niestandardowy wielokąt.
Okrąg

Jeśli wybierzesz obszar geograficzny w postaci koła, musisz podać center i radius. Wartość center może być współrzędną geograficzną lub identyfikatorem miejsca odpowiadającym środkowi okręgu. Ta metoda umożliwia dokładne filtrowanie na podstawie zdefiniowanego obszaru kołowego.

  • center:
    • latLng: szerokość i długość geograficzna środka koła. Szerokość geograficzna musi być liczbą z zakresu od -90 do 90. Długość geograficzna musi być liczbą z zakresu od –180 do 180.
    • place: identyfikator miejsca w środku koła. Pamiętaj, że obsługiwane są tylko punkty sprzedaży. Ten ciąg musi się zaczynać od przedrostka places/.
  • radius: promień koła w metrach. Liczba musi być dodatnia.
Region

Określ obszar jako region, przekazując identyfikator miejsca do parametru place. Identyfikator miejsca reprezentuje obszar geograficzny (np. obszar reprezentowany przez wielokąt). Na przykład identyfikator miejsca Tampa w stanie Floryda to places/ChIJ4dG5s4K3wogRY7SWr4kTX6c. Pamiętaj, że nie wszystkie identyfikatory miejsc mają dobrze zdefiniowaną geometrię. W takich przypadkach interfejs Places Insights API zwraca kod błędu 400 z komunikatem, który wskazuje, że region nie jest obsługiwany. Dodatkowo w przypadku złożonych regionów geograficznych wewnętrzne optymalizacje przetwarzania mogą prowadzić do nieznacznego zawyżania wielkości obszaru (o 2–3%), który reprezentuje dany region.

Aby sprawdzić, czy identyfikator miejsca reprezentuje obsługiwany typ miejsca, prześlij identyfikator miejsca w żądaniu interfejsu Geokodowania API. Odpowiedź zawiera tablicę type z typami miejsc powiązanymi z identyfikatorem miejsca, np. city, neighborhood lub country.

Nieobsługiwane typy miejsc:

  • establishment: zwykle oznacza miejsce, które nie zostało jeszcze skategoryzowane.
  • street_number: wskazuje dokładny numer budynku.
  • floor: wskazuje piętro budynku.
  • post_box: wskazuje konkretny skrypt pocztowy.
  • street_address: wskazuje dokładny adres.
  • room: wskazuje pokój w budynku.
  • intersection: oznacza duże skrzyżowanie, zwykle dwóch głównych dróg.
  • landmark: wskazuje miejsce w pobliżu, które służy jako punkt odniesienia ułatwiający nawigację.
  • subpremise: wskazuje element adresowalny poniżej poziomu obiektu, taki jak mieszkanie, pokój lub apartament.
  • sublocality_level_5: najbardziej szczegółowy poziom szczegółowości komponentów adresu w subregionie, zazwyczaj reprezentujący bardzo mały obszar sąsiedztwa lub obszar hiperlokalny w mieście.
Obszar niestandardowy

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

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

Kolejne identyczne współrzędne będą traktowane jako pojedyncza współrzędna. Jednak nieciągłe zduplikowane współrzędne (inne niż wymagane identyczne współrzędne pierwszego i ostatniego punktu) spowodują błąd.

Ponadto krawędzie niesąsiadujące nie mogą się przecinać, a krawędzie o długości 180 stopni są niedozwolone (czyli sąsiadujące wierzchołki nie mogą być antypodami).

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 do uwzględnienia lub wykluczenia. Listę typów miejsc głównych i dodatkowych obsługiwanych przez Places Insights API znajdziesz w tabeli A w sekcji Typy miejsc w interfejsie Places API (nowa wersja). 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 Więcej informacji o filtrach typu.

Parametry opcjonalne

Filtry te są opcjonalne:

  • operatingStatus: określa stany miejsc do uwzględnienia lub wykluczenia. Domyślnie filtrowanie według parametru operatingStatus: OPERATING_STATUS_OPERATIONAL (jedna konkretna wartość).
  • priceLevels: określa poziomy cen miejsc, które mają być uwzględnione. Domyślnie nie stosuje się filtrowania poziomu ceny i zwracane są wszystkie miejsca (w tym te bez informacji o poziomie ceny).
  • ratingFilter: określa zakres ocen miejsc. Domyślnie nie jest stosowane filtrowanie (w wynikach uwzględniane są wszystkie oceny).

Stan działania

Za pomocą filtra operatingStatus możesz filtrować według stanu działania, np. OPERATIONAL lub TEMPORARILY_CLOSED. Filtr operatingStatus działa w ten sposób:

  • Jeśli nie podano żadnych filtrów, w wynikach uwzględnione są tylko miejsca o stanie działania OPERATING_STATUS_OPERATIONAL.
  • Jeśli podano co najmniej 1 filtr, musisz podać prawidłowe wartości stanu działania (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 ceny. Dozwolone wartości poziomu ceny 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ą przypisane poziomy cen. Dotyczy to miejsc bez informacji o poziomie ceny, które mogą nie zostać zwrócone podczas filtrowania według określonych poziomów cen.
  • Jeśli podano co najmniej 1 filtr: zwrócone zostaną tylko miejsca pasujące do podanych 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 uwzględnią też 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.