Wyszukiwanie w pobliżu (nowe)

Wybierz platformę: Android iOS JavaScript Usługa internetowa

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

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

Wypróbuj

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 (nowy format) zwraca w odpowiedzi obiekt JSON. 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 poszczególnych miejscach.
  • FieldMask przekazana w żądaniu określa listę pól zwróconych w obiekcie Place.

Pełny obiekt JSON ma następujący format:

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

Wymagane parametry

  • FieldMask

    Określ listę pól, które mają być zwracane w odpowiedzi, tworząc maskę pola odpowiedzi. Przekaż maskę pola odpowiedzi do metody, 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 parametru *.

    X-Goog-FieldMask: *

    Wypełnij co najmniej jedno z tych pól:

    • Te pola powodują użycie identyfikatora SKU wyszukiwania w pobliżu (podstawowego):

      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 przed GA Preview i nie jest płatne, co oznacza, że za korzystanie z niego w fazie Preview nie jest naliczana opłata.

      ** 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ą wyświetlenie elementu wyszukiwania w pobliżu (zaawansowanego):

      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ą wyświetlenie kodu SKU wyszukiwania w pobliżu (preferowany):

      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 wyszukiwanie tekstowe i wyszukiwanie w pobliżu

  • locationRestriction

    Region do wyszukiwania określony jako okrąg z punktami środkowymi i promieniem w metrach. Promień musi mieścić się w zakresie 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 tabeli Tabela A, która służy do filtrowania wyników wyszukiwania. W każdej kategorii ograniczeń typu można określić maksymalnie 50 typów.

    Miejsce może mieć tylko jeden typ główny z typów powiązanych z tabelą A. Na przykład typ podstawowy może być "mexican_restaurant" lub "steak_house". Aby filtrować wyniki według głównego typu miejsca, użyj właściwości includedPrimaryTypes i excludedPrimaryTypes.

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

    Jeśli podasz ogólny typ podstawowy, taki jak "restaurant" lub "hotel", odpowiedź może zawierać miejsca o konkretnym typie podstawowym niż podany. Możesz na przykład określić, że chcesz uwzględnić główny typ: "restaurant". Odpowiedź może wtedy zawierać miejsca o podstawowym typie "restaurant", ale może też zawierać miejsca o bardziej szczegółowym typie podstawowym, takim jak "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 do wyszukania. Jeśli ten parametr zostanie pominięty, zwrócone zostaną miejsca wszystkich typów.

    excludedTypes

    Rozdzielona przecinkami lista typów miejsc z tabeli A, które mają zostać wykluczone 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 jako "primary_school". Odpowiedź zawiera miejsca, które pasują do co najmniej 1 z wartości includedTypes i żadnego z wartości excludedTypes.

    Jeśli występują kolidujące typy, takie jak typ występujący zarówno w polu includedTypes, jak i w excludedTypes, zostanie zwrócony błąd INVALID_REQUEST.

    includedPrimaryTypes

    Rozdzielona przecinkami lista głównych typów miejsc z tabeli A, które mają zostać uwzględnione w wyszukiwaniu.

    excludedPrimaryTypes

    Lista rozdzielana przecinkami typów głównych miejsc z tabeli A, które mają zostać wykluczone 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 obsługiwane języki, więc ta lista może nie być wyczerpująca.
    • 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. Pozostałe adresy są zwracane w preferowanym języku. Komponenty adresu są zwracane w tym samym języku, który jest wybierany z pierwszego komponentu.
    • 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 używanego rankingu. 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 określonej 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 (nowa wersja) – przykłady

Znajdowanie miejsc jednego typu

Poniższy przykład pokazuje żądanie Wyszukiwania w pobliżu (nowe) o wyświetlane nazwy wszystkich restauracji w promieniu 500 metrów (zgodnie z definicją za pomocą funkcji 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. Na przykład dodaj atrybut places.formattedAddress,places.types,places.websiteUri, aby w odpowiedzi uwzględnić adres restauracji, jej typ i adres internetowy:

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ź ma teraz postać:

{
  "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 osiedleńskich 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.primaryType i places.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 obszaru, ranking według 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ędniamy parametr rankPreference, aby uporządkować 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 API 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 Rozwiń narzędzie API Explorer..
  2. Opcjonalnie rozwiń sekcję Pokaż parametry standardowe i ustaw parametr fields na maskę pola.
  3. Opcjonalnie edytuj Treść żądania.
  4. Kliknij przycisk Wykonaj. W wyskakującym okienku wybierz konto, którego chcesz użyć do wysłania prośby.

  5. W panelu API Explorer kliknij ikonę rozwijania Rozwiń interfejs API Explorer., aby rozwinąć okno API Explorer.