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ć centerradius. Wartość center może być współrzędną geograficzną lub identyfikatorem miejsca odpowiadającym środkowi okręgu. Ta metoda umożliwia precyzyjne i 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 znaków 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 wskazującym, ż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 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 skrytka pocztowa.
  • street_address: wskazuje dokładny adres.
  • room: wskazuje pokój w adresie 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, wejdź na 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 niespójne 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 interfejs Places Insights API znajdziesz w tabeli A w sekcji Typy miejsc w interfejsie Places API (nowa wersja). Musisz podać co najmniej 1 typ atrybutu 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. Domyślnie nie jest stosowane żadne filtrowanie (w wynikach uwzględniane są wszystkie poziomy cen).
  • 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 (np. czynne lub tymczasowo zamknięte). Jeśli filtr operatingStatus nie jest ustawiony, w wynikach uwzględniane są tylko miejsca o stanie działania OPERATING_STATUS_OPERATIONAL.

Poziom cen

Filtr price_levels umożliwia filtrowanie według poziomu ceny (np. bezpłatne, średnie lub drogie). Jeśli filtr price_levels nie jest ustawiony, w wynikach uwzględnione są wszystkie poziomy 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.