Wyszukiwanie w pobliżu (nowe)

Żądanie Wyszukiwanie w pobliżu (nowe) przyjmuje co najmniej jeden typ miejsca i zwraca listę pasujących miejsc na określonym obszarze. Wymagana jest maska pola określająca co najmniej 1 typ danych. Wyszukiwanie w pobliżu (nowe) obsługuje tylko żądania POST.

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

Wypróbuj

Prośby o wyszukiwanie w pobliżu (nowe)

Żądanie wyszukiwania w pobliżu (nowe) to żądanie HTTP POST kierowane na adres URL w formacie:

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

Przekazuj wszystkie parametry w treści żądania JSON lub w nagłówkach w ramach żą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 (nowe) odpowiedzi

Wyszukiwanie w pobliżu (nowe) 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 jednym miejscu.
  • Wartość FieldMask przekazana 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 zwróconych pól. Jeśli pominiesz maskę pola, metoda zwróci błąd.

    Maskowanie pól to dobra praktyka projektowa, która pozwala uniknąć żądania zbędnych danych, co pozwala uniknąć niepotrzebnego czasu przetwarzania i opłat.

    Określ rozdzieloną przecinkami listę typów danych miejsc do zwrócenia. Na przykład, aby pobrać wyświetlaną nazwę i adres miejsca.

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

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

    X-Goog-FieldMask: *

    Określ co najmniej jedno z tych pól:

    • Następujące pola aktywują kod SKU wyszukiwania w pobliżu (podstawowe):

      places.accessibilityOptions, places.addressComponents, places.adrFormatAddress, places.businessStatus, places.displayName, places.formattedAddress, places.googleMapsUri, places.iconBackgroundColor, places.iconMaskBaseUri, places.id, places.location, places.name*, places.photos, places.plusCode, places.primaryType, places.primaryTypeDisplayName, places.shortFormattedAddress, places.subDestinations, w tym polu: /}, w tym polu: places.subDestinations, places.nameplaces.typesplaces.utcOffsetMinutesplaces.viewport

      places/PLACE_ID Użyj opcji places.displayName, by uzyskać dostęp do tekstowej nazwy miejsca.

    • Następujące pola aktywują kod SKU wyszukiwania w pobliżu (zaawansowane):

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

    • Następujące pola wywołują kod SKU wyszukiwania w pobliżu (preferowane):

      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.delivery, places.delivery, places.delivery, places.delivery, places.delivery, places.delivery,
      places.servesBeerplaces.servesBreakfastplaces.servesBrunchplaces.servesCocktailsplaces.servesCoffeeplaces.servesDessertsplaces.servesDinnerplaces.servesLunchplaces.servesVegetarianFoodplaces.servesWineplaces.takeout

  • locationRestriction

    Region do wyszukiwania określony jako okrąg, zdefiniowany przez punkt środkowy i promień 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ć w żądaniu wartość większą niż 0,0.

    Na przykład:

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

Parametry opcjonalne

  • includeTypes/excludedTypes, includePrimaryTypes/excludedPrimaryTypes

    Umożliwia określenie listy typów z typów Tabela A służących do filtrowania wyników wyszukiwania. W każdej kategorii ograniczeń typu można określić do 50 typów.

    Miejsce może mieć tylko jeden typ podstawowy z powiązanych z nim typów tabeli A. Typem podstawowym może być na przykład "mexican_restaurant" lub "steak_house". Użyj właściwości includedPrimaryTypes i excludedPrimaryTypes, aby filtrować wyniki według podstawowego typu miejsca.

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

    Jeśli wyszukiwanie jest określone z wieloma ograniczeniami typów, zwracane są tylko miejsca, które spełniają wszystkie te ograniczenia. Jeśli na przykład określisz {"includedTypes": ["restaurant"], "excludedPrimaryTypes": ["steak_house"]}, zwrócone miejsca świadczą usługi powiązane z "restaurant", ale nie działają głównie jako "steak_house".

    includedTypes

    Rozdzielona przecinkami lista typów miejsc z tabeli A do wyszukania. W przypadku pominięcia tego parametru zwracane są 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 właściwość includedTypes ( np. "school"), jak i excludedTypes (np. "primary_school"), odpowiedź będzie zawierała miejsca zaklasyfikowane jako "school", ale nie jako "primary_school". Odpowiedź zawiera miejsca pasujące do co najmniej 1 z parametrów includedTypes i żadnego z podanych parametrów excludedTypes.

    Jeśli wystąpią jakiekolwiek sprzeczne typy, np. typy występujące zarówno w includedTypes, jak i w excludedTypes, zostanie zwrócony błąd INVALID_REQUEST.

    includedPrimaryTypes

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

    excludedPrimaryTypes

    Rozdzielona przecinkami lista głównych typów miejsc z tabeli A, które mają zostać wykluczone z wyszukiwania.

    Jeśli wystąpią jakiekolwiek sprzeczne typy podstawowe, takie jak typ występujący zarówno w atrybutach 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ć pełna.
    • Jeśli nie zostanie podany languageCode, interfejs API przyjmuje domyślnie wartość en. Jeśli podasz nieprawidłowy kod języka, interfejs API zwróci błąd INVALID_ARGUMENT.
    • Interfejs API staramy się, aby adres był czytelny zarówno dla użytkownika, jak i dla lokalnych lokalizacji. W tym celu funkcja zwraca adresy w języku lokalnym, transliterację do skryptu zrozumiałego dla użytkownika w razie potrzeby z uwzględnieniem preferowanego języka. Wszystkie inne 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 używa najbliższego dopasowania.
    • Preferowany język ma niewielki wpływ na zbiór wyników, które interfejs API wybiera do zwrócenia, oraz na kolejność ich zwracania. Geokoder interpretuje skróty w różny sposób w zależności od języka, np. angażowanie rodzaju ulic lub synonimów, które mogą być prawidłowe w jednym języku, ale nie w innym.
  • maxResultCount

    Określa maksymalną liczbę zwracanych wyników wyszukiwania miejsc. Wartość musi mieścić się w przedziale od 1 do 20 (domyślnie) włącznie.

  • rankPreference

    Typ rankingu, który ma zostać użyty. Jeśli pominiesz ten parametr, wyniki będą uporządkowane według popularności. Może mieć jedną z tych wartości:

    • POPULARITY (domyślnie) – sortuje wyniki na podstawie ich popularności.
    • DISTANCE sortuje wyniki w kolejności rosnącej według odległości od określonej lokalizacji.
  • regionCode

    Kod regionu używany do formatowania odpowiedzi, określony jako dwuznakowy kod CLDR. Brak wartości domyślnej.

    Jeśli nazwa kraju w polu formattedAddress w odpowiedzi jest zgodna z wartością regionCode, kod kraju jest pomijany w polu formattedAddress. Ten parametr nie ma wpływu na element adrFormatAddress, który zawsze zawiera nazwę kraju, lub na shortFormattedAddress, który nigdy go nie uwzględnia.

    Większość kodów CLDR jest identyczna z kodami ISO 3166-1 z kilkoma wyjątkami. Na przykład domena ccTLD w Wielkiej Brytanii to „uk” (.co.uk), a kod ISO 3166-1 to „gb” (technicznie oznaczający jednostkę „Wielka Brytania i Irlandia Północna”). Parametr może wpływać na wyniki w zależności od obowiązującego prawa.

Przykłady wyszukiwania w pobliżu (nowe)

Znajdź miejsca jednego typu

Poniższy przykład przedstawia żądanie Wyszukiwanie w pobliżu (nowe) dotyczące wyświetlanych nazw wszystkich restauracji w promieniu 500 metrów zdefiniowanych przez funkcję 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

Pamiętaj, ż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"
      }
    },
...
}

Aby zwrócić dodatkowe informacje, do maski pola dodaj więcej typów danych. Na przykład dodaj places.formattedAddress,places.types,places.websiteUri, aby umieścić w odpowiedzi adres, typ i adres internetowy restauracji:

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

Poniższy przykład przedstawia żądanie Wyszukiwanie w pobliżu (nowe) dotyczące wyświetlanych nazw wszystkich sklepów osiedlowych i alkoholi w promieniu 1000 metrów od określonego zakresu 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 dodano wartości places.primaryType i places.types, dzięki czemu odpowiedź będzie zawierać informacje o typie każdego miejsca, co ułatwi wybranie odpowiedniego miejsca z wyników.

Ten przykład przedstawia żądanie Wyszukiwania w pobliżu (nowego) dla wszystkich miejsc typu "school" z wyłączeniem wszystkich miejsc typu "primary_school", które porządkują wyniki 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

Wyszukaj wszystkie miejsca w pobliżu danego obszaru, uporządkuj według odległości

Poniższy przykład przedstawia nowe wyszukiwanie w pobliżu miejsc w pobliżu punktu w centrum San Francisco. W tym przykładzie użyjesz parametru 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

Eksplorator interfejsów API umożliwia wykonywanie przykładowych żądań, aby ułatwić Ci zapoznanie się z interfejsem API i jego opcjami.

  1. Opcjonalnie rozwiń opcję Pokaż parametry standardowe i ustaw parametr fields na maskę pola.
  2. Opcjonalnie zmodyfikuj treść żądania.
  3. Kliknij przycisk Wykonaj. W wyskakującym okienku wybierz konto, którego chcesz użyć, aby przesłać prośbę.