Wyszukiwanie w pobliżu (nowość)

Wyszukiwanie w pobliżu (nowa wersja) przyjmuje co najmniej 1 typ miejsca i zwraca listę pasujących miejsc w określonym obszarze. Wymagane jest podanie maski pola określającej co najmniej 1 typ danych. Wyszukiwanie w pobliżu (nowy) obsługuje tylko żądania POST.

Narzędzie APIs Explorer umożliwia wysyłanie żądań na żywo, dzięki czemu możesz zapoznać się z interfejsem API i jego opcjami:

Wypróbuj interaktywne demo, aby zobaczyć wyniki wyszukiwania w pobliżu (Nowe) wyświetlane na mapie.

Wyszukiwanie w pobliżu (nowe)

Żądanie wyszukiwania w pobliżu (nowa wersja) to żądanie HTTP POST wysłane na adres URL w formie:

https://places.googleapis.com/v1/places:searchNearby

Przekazać wszystkie parametry w treści żądania JSON lub w nagłówkach jako część żądania POST. Na przykład:

curl -X POST -d '{
  "includedTypes": ["restaurant"],
  "maxResultCount": 10,
  "locationRestriction": {
    "circle": {
      "center": {
        "latitude": 37.7937,
        "longitude": -122.3965},
      "radius": 500.0
    }
  }
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: places.displayName" \
https://places.googleapis.com/v1/places:searchNearby

Wyszukiwanie w pobliżu (nowy) – odpowiedzi

Wyszukiwanie w pobliżu (nowa wersja) zwraca obiekt JSON jako odpowiedź. W odpowiedzi:

  • Tablica places zawiera wszystkie pasujące miejsca.
  • Każde miejsce w tablicy jest reprezentowane przez obiekt Place. Obiekt Place zawiera szczegółowe informacje o pojedynczym miejscu.
  • FieldMask przekazany w żądaniu określa listę pól zwracanych w obiekcie Place.

Pełny obiekt JSON ma postać:

{
  "places": [
    {
      object (Place)
    }
  ]
}

Wymagane parametry

  • FieldMask

    Określ listę pól, które mają być zwracane w odpowiedzi, tworząc maskę pola odpowiedzi. Przekaż do metody maskę pola odpowiedzi, używając parametru adresu URL $fields lub fields albo nagłówka HTTP X-Goog-FieldMask. W odpowiedzi nie ma domyślnej listy zwracanych pól. Jeśli pominiesz maskę pola, metoda zwróci błąd.

    Maskowanie pól to dobra praktyka projektowania, która pozwala uniknąć żądania niepotrzebnych danych, co pomaga uniknąć niepotrzebnego czasu przetwarzania i opłat rozliczeniowych.

    Podaj rozdzieloną przecinkami listę typów danych o miejscach, które mają zostać zwrócone. Na przykład: aby pobrać nazwę wyświetlaną i adres miejsca.

    X-Goog-FieldMask: places.displayName,places.formattedAddress

    Aby pobrać wszystkie pola, użyj zapytania *.

    X-Goog-FieldMask: *

    Podaj co najmniej 1 z tych pól:

    • Te pola powodują użycie kodu SKU „Wyszukiwanie w pobliżu Pro”:

      places.accessibilityOptions
      places.addressComponents
      places.adrFormatAddress
      places.attributions
      places.businessStatus
      places.containingPlaces
      places.displayName
      places.formattedAddress
      places.googleMapsLinks*
      places.googleMapsUri
      places.iconBackgroundColor
      places.iconMaskBaseUri
      places.id
      places.location
      places.name**
      places.photos
      places.plusCode
      places.primaryType
      places.primaryTypeDisplayName
      places.pureServiceAreaBusiness
      places.shortFormattedAddress
      places.subDestinations
      places.types
      places.utcOffsetMinutes
      places.viewport

      * Pole places.googleMapsLinks znajduje się w fazie wstępnej przed GA i nie jest objęte opłatami, co oznacza, że za korzystanie z niego w trakcie tej fazy nie są naliczane żadne opłaty.

      ** Pole places.name zawiera nazwę zasobu miejsca w formie: places/PLACE_ID. Użyj places.displayName, aby wyświetlić nazwę tekstową miejsca.

    • Te pola powodują uruchomienie kodu SKU wyszukiwania w pobliżu w Enterprise:

      places.currentOpeningHours
      places.currentSecondaryOpeningHours
      places.internationalPhoneNumber
      places.nationalPhoneNumber
      places.priceLevel
      places.priceRange
      places.rating
      places.regularOpeningHours
      places.regularSecondaryOpeningHours
      places.userRatingCount
      places.websiteUri

    • Te pola powodują użycie poziomu Enterprise Plus usługi wyszukiwania w pobliżu:

      places.allowsDogs
      places.curbsidePickup
      places.delivery
      places.dineIn
      places.editorialSummary
      places.evChargeOptions
      places.fuelOptions
      places.goodForChildren
      places.goodForGroups
      places.goodForWatchingSports
      places.liveMusic
      places.menuForChildren
      places.parkingOptions
      places.paymentOptions
      places.outdoorSeating
      places.reservable
      places.restroom
      places.reviews
      places.routingSummaries*
      places.servesBeer
      places.servesBreakfast
      places.servesBrunch
      places.servesCocktails
      places.servesCoffee
      places.servesDessert
      places.servesDinner
      places.servesLunch
      places.servesVegetarianFood
      places.servesWine
      places.takeout

      * Tylko w wyszukiwarce tekstowej i wyszukiwarce w pobliżu

  • locationRestriction

    Region do wyszukiwania określony jako okrąg z punktami środkowymi i promieniem w metrach. Promień musi się mieścić w przedziale od 0,0 do 50 000,0 (włącznie). Domyślny promień to 0,0. Musisz ustawić go w prośbie na wartość większą niż 0,0.

    Na przykład:

    "locationRestriction": {
      "circle": {
        "center": {
          "latitude": 37.7937,
          "longitude": -122.3965
        },
        "radius": 500.0
      }
    }

Parametry opcjonalne

  • includedTypes/excludedTypes, includedPrimaryTypes/excludedPrimaryTypes

    Umożliwia określenie listy typów z tabel tabeli A, których można użyć do filtrowania wyników wyszukiwania. W każdej kategorii ograniczeń typu możesz określić maksymalnie 50 typów.

    Miejsce może mieć tylko jeden podstawowy typ z typów wymienionych w tabeli A. Na przykład typ podstawowy może być "mexican_restaurant" lub "steak_house". Użyj właściwości includedPrimaryTypesexcludedPrimaryTypes, aby filtrować wyniki według głównego typu miejsca.

    Miejsce może też mieć wiele wartości typu z typów wymienionych w tabeli A powiązanych z tym miejscem. Na przykład restauracja może mieć te typy:"seafood_restaurant", "restaurant", "food","point_of_interest", "establishment". Użyj znaków includedTypes i excludedTypes, aby filtrować wyniki na liście typów powiązanych z miejscem.

    Jeśli określisz ogólny podstawowy typ, np. "restaurant" lub "hotel", odpowiedź może zawierać miejsca o bardziej szczegółowym podstawowym typie niż podany. Możesz na przykład określić, że chcesz uwzględnić główny typ: "restaurant". Odpowiedź może zawierać miejsca o podstawowym typie "restaurant", ale może też zawierać miejsca o bardziej szczegółowym typie podstawowym, np. "chinese_restaurant" lub "seafood_restaurant".

    Jeśli wyszukiwanie jest określone z wieloma ograniczeniami typu, zwracane są tylko miejsca, które spełniają wszystkie ograniczenia. Jeśli np. podasz wartość{"includedTypes": ["restaurant"], "excludedPrimaryTypes": ["steak_house"]}, zwrócone miejsca oferują usługi związane z "restaurant", ale nie działają głównie jako "steak_house".

    includedTypes

    Rozdzielona przecinkami lista typów miejsc z tabeli A, których szukać. Jeśli ten parametr zostanie pominięty, zwrócone zostaną miejsca wszystkich typów.

    excludedTypes

    Rozdzielana przecinkami lista typów miejsc z tabeli A do wykluczenia z wyszukiwania.

    Jeśli w żądaniu podasz zarówno parametr includedTypes ( np. "school"), jak i excludedTypes (np. "primary_school"), odpowiedź będzie zawierać miejsca zakwalifikowane jako "school", ale nie "primary_school". Odpowiedź zawiera miejsca, które pasują do co najmniej jednegoincludedTypesżadnegoexcludedTypes.

    Jeśli występują jakieś sprzeczne typy, np. typ występujący zarówno w opcji includedTypes, jak i excludedTypes, zwracany jest błąd INVALID_REQUEST.

    includedPrimaryTypes

    Lista oddzielonych przecinkami typów głównych miejsc z tabeli A do uwzględnienia w wyszukiwaniu.

    excludedPrimaryTypes

    Lista rozdzielana przecinkami typów głównych miejsc z tabeli A do wykluczenia z wyszukiwania.

    Jeśli występują jakieś sprzeczne typy podstawowe, np. typ występujący zarówno w includedPrimaryTypes, jak i excludedPrimaryTypes, zwracany jest błąd INVALID_ARGUMENT.

  • languageCode

    Język, w którym mają być zwracane wyniki.

    • Zobacz listę obsługiwanych języków. Google często aktualizuje listę obsługiwanych języków, więc może ona nie być kompletna.
    • Jeśli nie podasz parametru languageCode, interfejs API użyje domyślnej wartości en. Jeśli określisz nieprawidłowy kod języka, API zwróci błąd INVALID_ARGUMENT.
    • Interfejs API stara się podać adres ulicy, który jest czytelny zarówno dla użytkownika, jak i dla mieszkańców. Aby to osiągnąć, zwraca adresy ulicy w języku lokalnym, transliterowane do postaci czytelnej dla użytkownika w odpowiednim języku. Wszystkie inne adresy są zwracane w preferowanym języku. Wszystkie elementy adresu są zwracane w tym samym języku, który jest wybierany na podstawie pierwszego elementu.
    • Jeśli nazwa nie jest dostępna w preferowanym języku, interfejs API stosuje najbliższe dopasowanie.
    • Preferowany język ma niewielki wpływ na zestaw wyników zwracanych przez interfejs API oraz na ich kolejność. Geokoder interpretuje skróty w różny sposób w zależności od języka, np. skróty nazw typów ulic lub synonimy, które mogą być prawidłowe w jednym języku, ale nie w innym.
  • maxResultCount

    Określa maksymalną liczbę wyników wyszukiwania miejsc do zwrócenia. Musi mieścić się w zakresie od 1 do 20 (domyślnie).

  • rankPreference

    Typ rankingu do użycia. Jeśli ten parametr zostanie pominięty, wyniki zostaną posortowane według popularności. Może być jedną z tych wartości:

    • POPULARITY (ustawienie domyślne) – sortuje wyniki według ich popularności.
    • DISTANCE Sortuje wyniki w kolejności rosnącej według odległości od wybranej lokalizacji.
  • regionCode

    Kod regionu użyty do sformatowania odpowiedzi, podany jako 2-znakowy kod CLDR. Nie ma wartości domyślnej.

    Jeśli nazwa kraju w polu formattedAddress w odpowiedzi pasuje do wartości w polu regionCode, kod kraju jest pomijany w polu formattedAddress. Ten parametr nie ma wpływu na adrFormatAddress, który zawsze zawiera nazwę kraju, ani na shortFormattedAddress, która nigdy nie zawiera nazwy kraju.

    Większość kodów CLDR jest identyczna z kodami ISO 3166-1, z niektórymi wyjątkami. Na przykład ccTLD Wielkiej Brytanii to „uk” (.co.uk), a jej kod ISO 3166-1 to „gb” (technicznie dla podmiotu „Zjednoczone Królestwo Wielkiej Brytanii i Irlandii Północnej”). Parametr może wpływać na wyniki w zależności od obowiązujących przepisów.

Wyszukiwanie w pobliżu (nowy) – przykłady

Znajdowanie miejsc jednego typu

Ten przykład pokazuje zapytanie „Szukaj w pobliżu (nowa wersja)” dotyczące wyświetlania nazw wszystkich restauracji w promieniu 500 metrów, zdefiniowanych przez circle:

curl -X POST -d '{
  "includedTypes": ["restaurant"],
  "maxResultCount": 10,
  "locationRestriction": {
    "circle": {
      "center": {
        "latitude": 37.7937,
        "longitude": -122.3965},
      "radius": 500.0
    }
  }
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: places.displayName" \
https://places.googleapis.com/v1/places:searchNearby

Zwróć uwagę, że nagłówek X-Goog-FieldMask określa, że odpowiedź zawiera te pola danych: places.displayName. Odpowiedź ma wtedy postać:

{
  "places": [
    {
      "displayName": {
        "text": "La Mar Cocina Peruana",
        "languageCode": "en"
      }
    },
    {
      "displayName": {
        "text": "Kokkari Estiatorio",
        "languageCode": "en"
      }
    },
    {
      "displayName": {
        "text": "Harborview Restaurant & Bar",
        "languageCode": "en"
      }
    },
...
}

Dodaj do maski pola dodatkowe typy danych, aby zwracać dodatkowe informacje. Aby na przykład uwzględnić adres, typ i adres internetowy restauracji w odpowiedzi, dodaj places.formattedAddress,places.types,places.websiteUri:

curl -X POST -d '{
  "includedTypes": ["restaurant"],
  "maxResultCount": 10,
  "locationRestriction": {
    "circle": {
      "center": {
        "latitude": 37.7937,
        "longitude": -122.3965},
      "radius": 500.0
    }
  }
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: places.displayName,places.formattedAddress,places.types,places.websiteUri" \
https://places.googleapis.com/v1/places:searchNearby

Odpowiedź jest teraz w tym formularzu:

{
  "places": [
    {
      "types": [
        "seafood_restaurant",
        "restaurant",
        "food",
        "point_of_interest",
        "establishment"
      ],
      "formattedAddress": "PIER 1 1/2 The Embarcadero N, San Francisco, CA 94105, USA",
      "websiteUri": "http://lamarsf.com/",
      "displayName": {
        "text": "La Mar Cocina Peruana",
        "languageCode": "en"
      }
    },
    {
      "types": [
        "greek_restaurant",
        "meal_takeaway",
        "restaurant",
        "food",
        "point_of_interest",
        "establishment"
      ],
      "formattedAddress": "200 Jackson St, San Francisco, CA 94111, USA",
      "websiteUri": "https://kokkari.com/",
      "displayName": {
        "text": "Kokkari Estiatorio",
        "languageCode": "en"
      }
    },
...
}

Znajdowanie miejsc różnych typów

Ten przykład pokazuje zapytanie „Szukaj w pobliżu” (Nowe) dotyczące wyświetlania nazw wszystkich sklepów osiedlowych i sklepów z alkoholem w promieniu 1000 metrów od określonej lokalizacji:circle

curl -X POST -d '{
  "includedTypes": ["liquor_store", "convenience_store"],
  "maxResultCount": 10,
  "locationRestriction": {
    "circle": {
      "center": {
        "latitude": 37.7937,
        "longitude": -122.3965
      },
      "radius": 1000.0
    }
  }
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: places.displayName,places.primaryType,places.types" \
https://places.googleapis.com/v1/places:searchNearby
W tym przykładzie do maski pola dodaję places.primaryTypeplaces.types, aby odpowiedź zawierała informacje o typie każdego miejsca, co ułatwia wybranie odpowiedniego miejsca w wynikach.

Ten przykład pokazuje zapytanie „W pobliżu” (Nowe) dotyczące wszystkich miejsc typu "school", z wyłączeniem miejsc typu "primary_school", z rankingiem wyników według odległości:

curl -X POST -d '{
  "includedTypes": ["school"],
  "excludedTypes": ["primary_school"],
  "maxResultCount": 10,
  "locationRestriction": {
    "circle": {
      "center": {
        "latitude": 37.7937,
        "longitude": -122.3965
      },
      "radius": 1000.0
    }
  },
  "rankPreference": "DISTANCE"
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: places.displayName" \
https://places.googleapis.com/v1/places:searchNearby

wyszukiwanie wszystkich miejsc w pobliżu danego obszaru z uwzględnieniem odległości;

Poniższy przykład przedstawia żądanie wyszukiwania w pobliżu (Nowe) dotyczące miejsc w pobliżu punktu w centrum San Francisco. W tym przykładzie uwzględniasz parametr rankPreference, aby uszeregować wyniki według odległości:

curl -X POST -d '{
  "maxResultCount": 10,
  "rankPreference": "DISTANCE",
  "locationRestriction": {
    "circle": {
      "center": {
        "latitude": 37.7937,
        "longitude": -122.3965
      },
      "radius": 1000.0
    }
  }
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: places.displayName" \
https://places.googleapis.com/v1/places:searchNearby

Wypróbuj

Narzędzie APIs Explorer umożliwia wysyłanie przykładowych żądań, dzięki czemu możesz zapoznać się z interfejsem API i jego opcjami.

  1. Po prawej stronie strony kliknij ikonę interfejsu API api.

  2. Opcjonalnie możesz zmodyfikować parametry żądania.

  3. Kliknij przycisk Wykonaj. W oknie wybierz konto, którego chcesz użyć do wysłania prośby.

  4. W panelu narzędzia APIs Explorer kliknij ikonę pełnego ekranu Pełny ekran, aby rozwinąć okno narzędzia APIs Explorer.