Parametry żądania

Ten dokument zawiera opis parametrów żądań interfejsu API Places Insights oraz statystyki i zalecenia 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.

    Uwaga: jeśli wybierzesz INSIGHT_PLACES, interfejs Places Insights API zwróci identyfikatory miejsc tylko wtedy, gdy count jest równa 100 lub mniejsza.

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. Środek może być określony przez współrzędne geograficzne lub identyfikator miejsca.

  • 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 404.

Tabela poniżej zawiera listę nieobsługiwanych typów regionów. Aby sprawdzić, czy identyfikator miejsca reprezentuje nieobsługiwany typ regionu, prześlij identyfikator miejsca w żądaniu Geokodowania API. Odpowiedź zawiera tablicę type z listą regionów powiązanych z identyfikatorem miejsca, np. city, neighborhood lub country.

Nieobsługiwane typy regionów
establishment place_of_worship
floor post_box
food postal_code_suffix
general_contractor room
geocode street_address
health street_number
intersection sublocality_level_5
landmark subpremise
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 żądaniu, 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. Poza pierwszymi i ostatnimi współrzędnymi nie może być żadnych innych zduplikowanych współrzędnych. Ponadto krawędzie niesąsiadujące nie mogą się przecinać, a krawędzie o długości 180° są niedozwolone (czyli sąsiadujące 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 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 (nowy). 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 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 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 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

Filtrowanie według stanu działania (np. działające lub tymczasowo zamknięte).

Poziom cen

Filtrowanie według poziomu ceny (np. bezpłatne, średnie lub drogie).

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).