Wyszukiwanie w pobliżu (nowe)

Wybierz platformę: Android iOS JavaScript Usługa internetowa

Wyszukiwanie w pobliżu (nowość) żądanie przyjmuje co najmniej jeden typ miejsca i zwraca listę pasujących miejsc w w określonym obszarze. Maska pola określająca co najmniej 1 typ danych jest wymagane. 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 Opcje interfejsu API:

Wypróbuj

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

Żądania wyszukiwania w pobliżu (nowe)

Żądanie Wyszukiwanie w pobliżu (nowe) to żądanie HTTP POST wysyłane do formularz:

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

Przekazuj wszystkie parametry w treści żądania JSON lub w nagłówkach jako część żądanie 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

Odpowiedzi Wyszukiwanie w pobliżu (nowe)

Wyszukiwanie w pobliżu (Nowość) zwraca błąd Obiekt JSON jako odpowiedź. W odpowiedzi:

  • Tablica places zawiera wszystkie pasujące miejsca.
  • Każde miejsce w tablicy jest reprezentowane przez Place obiektu. Obiekt Place zawiera szczegółowe informacje o jednym miejsce.
  • FieldMask przekazana w żądaniu określa listę pól zwracaną 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 za pomocą nagłówka HTTP X-Goog-FieldMask Odpowiedź nie zawiera domyślnej listy zwróconych pól. Jeśli pominiesz maskę pola, metoda zwróci błąd.

    Dobrą metodą projektowania jest maskowanie pól, dzięki którym zbędnych danych, co pozwala uniknąć niepotrzebnego czasu przetwarzania opłaty rozliczeniowe.

    Podaj oddzieloną przecinkami listę typów danych miejsc do zwrócenia. Przykład: aby pobrać wyświetlaną nazwę i adres miejsca.

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

    Użyj *, aby pobrać wszystkie pola.

    X-Goog-FieldMask: *

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

    • Te pola aktywują kod SKU Wyszukiwanie w pobliżu (podstawowe):

      places.accessibilityOptions, places.addressComponents, places.adrFormatAddress, places.attributions, 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, places.types, places.utcOffsetMinutes, places.viewport

      * Pole places.name zawiera miejsce nazwa zasobu w formie: places/PLACE_ID. Użyj formatu: places.displayName aby uzyskać dostęp do tekstowej nazwy miejsca.

    • Te pola aktywują kod SKU Wyszukiwanie w pobliżu (zaawansowane):

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

    • Te pola aktywują kod SKU (preferowany) funkcji 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.servesBeer, places.servesBreakfast, places.servesBrunch, places.servesCocktails, places.servesCoffee, places.servesDessert, places.servesDinner, places.servesLunch, places.servesVegetarianFood, places.servesWine, places.takeout

  • locationRestriction

    Region do przeszukania 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 ustaw go w żądaniu na 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 listy typów Tabela A używana do filtrowania w wynikach wyszukiwania. W każdej kategorii ograniczeń typu można określić maksymalnie 50 typów.

    Miejsce może mieć tylko jeden typ główny Tabela A powiązana z . Na przykład typ podstawowy to "mexican_restaurant" lub "steak_house". Używaj includedPrimaryTypes i excludedPrimaryTypes, według których filtrować wyniki główny typ miejsca.

    Miejsce może też mieć wiele wartości typów z typów Tabela A i powiązane z nią. Na przykład restauracja może mieć następujące typy: "seafood_restaurant", "restaurant", "food" "point_of_interest", "establishment". Użyj formatu: includedTypes i excludedTypes, aby filtrować wyniki na liście typów powiązanych z danego miejsca.

    Gdy określisz ogólny typ podstawowy, na przykład "restaurant" lub "hotel", odpowiedź może zawierać miejsca o bardziej konkretnym typie głównym niż określony przez Ciebie. Na przykład określasz, że ma być uwzględniony główny typ "restaurant" Odpowiedź może wtedy zawierać miejsca o głównym typie "restaurant", ale odpowiedź może też zawierać miejsca o bardziej szczegółowych typ główny, na przykład "chinese_restaurant" lub "seafood_restaurant".

    Jeśli wyszukiwanie jest określone z ograniczeniami wielu typów, tylko miejsca które są zgodne ze wszystkimi ograniczeniami. Jeśli na przykład wpiszesz {"includedTypes": ["restaurant"], "excludedPrimaryTypes": ["steak_house"]}, zwrócone miejsca świadczą 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 pominiesz ten parametr, zwracane będą miejsca wszystkich typów.

    excludedTypes

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

    Jeśli podasz zarówno includedTypes ( np. "school"), jak i excludedTypes (np. "primary_school") w żądaniu, wtedy odpowiedź zawiera miejsca zaklasyfikowane jako "school", ale nie jako "primary_school" Odpowiedź zawiera miejsca pasujące do co najmniej jednego z tych atrybutów includedTypes i żadne z excludedTypes.

    Jeśli występują kolidujące typy, takie jak typ występujący w obiekcie includedTypes i excludedTypes, zwracany jest błąd INVALID_REQUEST.

    includedPrimaryTypes

    Rozdzielona przecinkami lista głównych typów miejsc z tabeli A do uwzględnienia do wyszukiwania.

    excludedPrimaryTypes

    Rozdzielona przecinkami lista głównych typów miejsc z tabeli A do wykluczenia z wyników wyszukiwania.

    Jeśli występują sprzeczne typy główne, takie jak typ występujący w obu includedPrimaryTypes i excludedPrimaryTypes, Zwracany jest INVALID_ARGUMENT błąd.

  • languageCode

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

    • Zobacz listę obsługiwanych języków. Często Google aktualizuje obsługiwane języki, więc ta lista może nie być wyczerpująca.
    • Jeśli nie podano languageCode, domyślną wartością interfejsu API jest en. Jeśli jeśli określisz nieprawidłowy kod języka, API zwróci INVALID_ARGUMENT .
    • Staramy się, aby adres interfejsu API był czytelny zarówno dla użytkownika, jak i lokalnych. Aby osiągnąć ten cel, funkcja zwraca adresy w języku lokalnym, transliterację na skrypt możliwy do odczytania przez użytkownika w razie potrzeby, przy jednoczesnym zachowaniu język. Pozostałe adresy są zwracane w preferowanym języku. Komponenty adresu są wszystkie zwrócone 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 zestaw wyników wybieranych przez interfejs API. oraz kolejność ich zwracania. Geokoder interpretuje skróty w zależności od języka, np. skróty typów ulic lub synonimy które mogą obowiązywać w jednym języku, ale nie w innym.

  • maxResultCount

    Określa maksymalną liczbę wyników miejsc do zwrócenia. Wymagana wartość z zakresu 1 i 20 (domyślnie) włącznie.

  • rankPreference

    Typ rankingu, który ma zostać użyty. Jeśli ten parametr zostanie pominięty, wyniki będą uporządkowane według popularności. Możliwe 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śloną lokalizację.

  • regionCode

    Kod regionu używany do formatowania odpowiedzi podany jako dwuznakową wartość kodu CLDR. Nie ma wartości domyślnej.

    Jeśli nazwa kraju w polu formattedAddress w odpowiedzi jest zgodna z nazwą kraju regionCode, kod kraju został pominięty w polu formattedAddress. Ten parametr nie ma wpływu na tabelę adrFormatAddress, która zawsze obejmuje kraj lub w domenie shortFormattedAddress, która nigdy jej nie zawiera.

    Większość kodów CLDR jest identycznych z kody ISO 3166-1, z kilkoma istotnymi wyjątkami. Na przykład domena ccTLD Wielkiej Brytanii to „uk” (co.uk), natomiast kod ISO 3166-1 to „gb”. (technicznie dla funkcji podmiotu „Wielkiej Brytanii i Irlandii Północnej”). Ten parametr może wpływać na wyniki w zależności od obowiązującego prawa.

Przykłady wyszukiwania w pobliżu (nowe)

Znajdowanie miejsc jednego typu

Poniższy przykład pokazuje żądanie wyszukiwania w pobliżu (nowe) dla wyświetlacza. nazwy wszystkich restauracji w promieniu 500 metrów, zdefiniowane 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

Pamiętaj, że nagłówek X-Goog-FieldMask określa, że odpowiedź zawiera następujące pola danych: places.displayName. Odpowiedź. ma postać:

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

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

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 format:

{
  "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 to żądanie wyszukiwania w pobliżu (Nowe) dla Wyświetlane nazwy wszystkich sklepów wielobranżowych i AGD w promieniu 1000 metrów od określono 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 elementy places.primaryType i places.types dzięki czemu odpowiedź będzie zawierać informacje o każdym miejscu, co ułatwi wybranie odpowiednie miejsce na stronie wyników.

Poniższy przykład pokazuje zapytanie Wyszukiwanie w pobliżu (nowe) dla wszystkich miejsc typu "school", z wyłączeniem wszystkich miejsc typu "primary_school", ranking wyników wg 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 zawiera zapytanie „Wyszukiwanie w pobliżu (nowe)” dla miejsc w pobliżu punktu w centrum San Francisco. W tym przykładzie uwzględniasz tag rankPreference. do sortowania wyników 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

API Explorer umożliwia wysyłanie przykładowych żądań, aby zapoznać się z interfejsem API i jego opcjami.

  1. Kliknij ikonę interfejsu API Rozwiń interfejs API Explorer.. w prawej części strony.
  2. Opcjonalnie rozwiń opcję Pokaż parametry standardowe i ustaw parametr fields do maski pola.
  3. Opcjonalnie edytuj Treść żądania.
  4. Kliknij przycisk Wykonaj. W wyskakującym okienku wybierz konto, z którego chcesz przesłać prośbę.

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