Wyszukaj tekst (nowa funkcja)

Wybierz platformę: Android iOS JavaScript Usługa internetowa

Deweloperzy z Europejskiego Obszaru Gospodarczego (EOG)

Wprowadzenie

Wyszukiwanie tekstowe (nowe) zwraca informacje o zestawie miejsc na podstawie ciągu znaków, np. „pizza w Nowym Jorku”, „sklepy obuwnicze w pobliżu Ottawy” lub „ul. Główna 123”. Usługa odpowiada listą miejsc pasujących do ciągu tekstowego i wszelkich ustawionych preferencji lokalizacyjnych.

Usługa jest szczególnie przydatna do wykonywania niejednoznacznych zapytań o adres w systemie automatycznym. Składniki ciągu znaków, które nie są adresami, mogą pasować do firm i adresów. Przykłady niejednoznacznych zapytań o adres to źle sformatowane adresy lub zapytania zawierające elementy inne niż adres, takie jak nazwy firm. Zapytania takie jak pierwsze dwa przykłady w tabeli poniżej mogą nie zwracać żadnych wyników, chyba że ustawiona jest lokalizacja, np. region, ograniczenie lokalizacji lub odchylenie lokalizacji.

„10 High Street, UK” lub „123 Main Street, US” W Wielkiej Brytanii jest wiele ulic „High Street”, a w Stanach Zjednoczonych wiele ulic „Main Street”. Zapytanie nie zwraca oczekiwanych wyników, chyba że ustawione jest ograniczenie lokalizacji.
„ChainRestaurant New York” Wiele lokalizacji „ChainRestaurant” w Nowym Jorku; brak adresu ulicy lub nawet nazwy ulicy.
„10 High Street, Escher UK” lub „123 Main Street, Pleasanton US” Tylko jedna ulica „High Street” w mieście Escher w Wielkiej Brytanii i tylko jedna ulica „Main Street” w mieście Pleasanton w Kalifornii w Stanach Zjednoczonych.
„UniqueRestaurantName New York” Tylko 1 placówka o tej nazwie w Nowym Jorku; nie trzeba podawać adresu, aby ją odróżnić.
„pizzerie w Nowym Jorku” To zapytanie zawiera ograniczenie lokalizacji, a „pizzerie” to dobrze zdefiniowany typ miejsca. Zwraca wiele wyników.
"+1 514-670-8700"

To zapytanie zawiera numer telefonu. Zwraca wiele wyników dotyczących miejsc powiązanych z tym numerem telefonu.

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

Żądania wyszukiwania tekstowego (nowe)

Żądanie wyszukiwania tekstowego (nowego) to ��ądanie HTTP POST w tej postaci:

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

Przekaż wszystkie parametry w treści żądania JSON lub w nagłówkach w ramach żądania POST. Na przykład:

curl -X POST -d '{
  "textQuery" : "Spicy Vegetarian Food in Sydney, Australia"
}' \
-H 'Content-Type: application/json' -H 'X-Goog-Api-Key: API_KEY' \
-H 'X-Goog-FieldMask: places.displayName,places.formattedAddress,places.priceLevel' \
'https://places.googleapis.com/v1/places:searchText'

Odpowiedzi z wyszukiwania tekstowego (nowa wersja)

Wyszukiwanie tekstowe (nowe) 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 jednym 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ę pól odpowiedzi. Przekaż maskę pola odpowiedzi do metody za pomocą parametru adresu URL $fields lub fields albo za pomocą 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 z kolei pomaga uniknąć niepotrzebnego czasu przetwarzania i opłat.

    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

    Użyj *, aby pobrać wszystkie pola.

    X-Goog-FieldMask: *

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

    • Te pola wywołują Text Search Essentials ID Only SKU:

      places.attributions
      places.id
      places.name*
      nextPageToken

      * Pole places.name zawiera nazwę zasobu miejsca w formacie: places/PLACE_ID. Użyj places.displayName w kodzie SKU wersji Pro, aby uzyskać dostęp do nazwy tekstowej miejsca.

    • Te pola wywołują jednostkę SKU Text Search Pro:

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

      * Opisy adresów są ogólnie dostępne dla klientów w Indiach, a w innych krajach są w fazie eksperymentalnej.

      ** Pole places.googleMapsLinks jest w fazie podglądu przed GA i nie wiąże się z żadnymi opłatami, co oznacza, że w okresie podglądu rozliczenia wynoszą 0 USD.

    • Te pola wywołują kod SKU Text Search 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 wywołują kod SKU Text Search Enterprise + Atmosphere:

      places.allowsDogs
      places.curbsidePickup
      places.delivery
      places.dineIn
      places.editorialSummary
      places.evChargeAmenitySummary
      places.evChargeOptions
      places.fuelOptions
      places.generativeSummary
      places.goodForChildren
      places.goodForGroups
      places.goodForWatchingSports
      places.liveMusic
      places.menuForChildren
      places.neighborhoodSummary
      places.parkingOptions
      places.paymentOptions
      places.outdoorSeating
      places.reservable
      places.restroom
      places.reviews
      places.reviewSummary
      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

  • textQuery

    Ciąg tekstowy, według którego ma być prowadzone wyszukiwanie, np. „restauracja”, „ul. Główna 123” lub „najlepsze miejsce do odwiedzenia w San Francisco”. Interfejs API zwraca pasujące kandydatury na podstawie tego ciągu znaków i porządkuje wyniki według ich trafności.

Parametry opcjonalne

  • includedType

    Wyniki są dostosowywane do miejsc pasujących do określonego typu zdefiniowanego w tabeli A. Możesz określić tylko jeden typ. Na przykład:

    • "includedType":"bar"
    • "includedType":"pharmacy"

    Wyszukiwanie tekstowe (nowe) stosuje filtrowanie według typu w przypadku niektórych zapytań, w zależności od możliwości zastosowania. Na przykład filtrowanie według typu może nie być stosowane w przypadku zapytań dotyczących konkretnych adresów („ulica Główna 123”), ale jest prawie zawsze stosowane w przypadku zapytań kategorycznych („sklepy w pobliżu” lub „centra handlowe”).

    Aby zastosować filtrowanie typu do wszystkich zapytań, ustaw strictTypeFiltering na true.

  • includePureServiceAreaBusinesses

    Jeśli wartość tego parametru to true, odpowiedź zawiera firmy, które odwiedzają klientów lub dostarczają im produkty bezpośrednio, ale nie mają fizycznej lokalizacji. Jeśli wartość tego parametru to false, interfejs API zwraca tylko firmy z fizyczną lokalizacją.

  • 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 wartości languageCode, interfejs API domyślnie użyje wartości en. Jeśli podasz nieprawidłowy kod języka, interfejs 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 mieszkańców. Aby to osiągnąć, zwraca adresy w języku lokalnym, a w razie potrzeby transliteruje je na pismo czytelne dla użytkownika, uwzględniając preferowany język. Wszystkie pozostałe adresy są zwracane w preferowanym języku. Wszystkie komponenty adresu są zwracane w tym samym języku, który jest wybierany na podstawie pierwszego komponentu.
    • Jeśli nazwa nie jest dostępna w preferowanym języku, interfejs API użyje najbliższego dopasowania.
    • Preferowany język ma niewielki wpływ na zestaw wyników, które interfejs API wybiera do zwrócenia, oraz na kolejność, w jakiej są one zwracane. Geokoder interpretuje skróty w różny sposób w zależności od języka, np. skróty typów ulic lub synonimy, które mogą być prawidłowe w jednym języku, ale nie w innym.

  • locationBias

    Określa obszar wyszukiwania. Ta lokalizacja służy jako punkt odniesienia, co oznacza, że mogą być zwracane wyniki z okolic określonej lokalizacji, w tym wyniki spoza określonego obszaru.

    Możesz określić locationRestriction lub locationBias, ale nie oba te warunki jednocześnie. Parametr locationRestriction określa region, w którym muszą się znajdować wyniki, a parametr locationBias określa region, w którym prawdopodobnie będą się znajdować wyniki lub w pobliżu którego będą się znajdować, ale mogą być poza tym obszarem.

    Określ region jako prostokątny widok lub okrąg.

    • Okrąg jest definiowany 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. Na przykład:

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

    • Prostokąt to widoczny obszar określony przez szerokość i długość geograficzną, reprezentowany przez 2 przeciwległe punkty o niskich i wysokich wartościach. Punkt dolny oznacza południowo-zachodni róg prostokąta, a punkt górny – północno-wschodni róg prostokąta.

      Widoczny obszar jest uważany za obszar zamknięty, co oznacza, że obejmuje swoje granice. Zakres szerokości geograficznej musi się mieścić w przedziale od -90 do 90 stopni włącznie, a zakres długości geograficznej musi się mieścić w przedziale od -180 do 180 stopni włącznie:

      • Jeśli low = high, widoczny obszar składa się z tego pojedynczego punktu.
      • Jeśli low.longitude > high.longitude, zakres długości geograficznej jest odwrócony (widoczny obszar przekracza linię długości geograficznej 180°).
      • Jeśli low.longitude = –180 stopni, a high.longitude = 180 stopni, widoczny obszar obejmuje wszystkie długości geograficzne.
      • Jeśli low.longitude = 180 stopni, a high.longitude = -180 stopni, zakres długości geograficznej jest pusty.
      • Jeśli low.latitude > high.latitude, zakres szerokości geograficznej jest pusty.

      Musisz podać dolną i górną wartość, a reprezentowane pole nie może być puste. Pusty widok spowoduje błąd.

      Na przykład ten obszar widoku w całości obejmuje Nowy Jork:

      "locationBias": {
  "rectangle": {
    "low": {
      "latitude": 40.477398,
      "longitude": -74.259087
    },
    "high": {
      "latitude": 40.91618,
      "longitude": -73.70018
    }
  }
}

  • locationRestriction

    Określa obszar wyszukiwania. Wyniki spoza określonego obszaru nie są zwracane.

    Określ region jako prostokątny widoczny obszar. Przykład definiowania widocznego obszaru znajdziesz w opisie elementu locationBias.

    Możesz określić locationRestriction lub locationBias, ale nie oba te warunki jednocześnie. Parametr locationRestriction określa region, w którym muszą się znajdować wyniki, a parametr locationBias określa region, w którym prawdopodobnie będą się znajdować wyniki lub w pobliżu którego będą się znajdować, ale mogą być poza tym obszarem.

  • maxResultCount (wycofane)

    Określa liczbę wyników (od 1 do 20) wyświetlanych na stronie. Jeśli np. ustawisz wartość maxResultCount na 5, na pierwszej stronie pojawi się maksymalnie 5 wyników. Jeśli zapytanie może zwrócić więcej wyników, odpowiedź zawiera token nextPageToken, który możesz przekazać w kolejnym żądaniu, aby uzyskać dostęp do następnej strony.

  • evOptions

    Określa parametry identyfikowania dostępnych złączy do ładowania pojazdów elektrycznych (EV) i szybkości ładowania.

    • connectorTypes

      Filtruje według typu złącza ładowania EV dostępnego w danym miejscu. Miejsce, które nie obsługuje żadnego z typów złączy, zostanie odfiltrowane. Obsługiwane typy złączy ładowania pojazdów elektrycznych to ładowarki łączone (AC i DC), ładowarki Tesla, ładowarki zgodne z GB/T (do szybkiego ładowania pojazdów elektrycznych w Chinach) i ładowarki do gniazdek ściennych. Więcej informacji znajdziesz w dokumentacji.

      • Aby filtrować wyniki pod kątem konkretnego obsługiwanego oprogramowania sprzęgającego, ustaw wartość connectorTypes. Jeśli na przykład chcesz znaleźć złącza typu 1 J1772, ustaw wartość connectorTypes na EV_CONNECTOR_TYPE_J1772.
      • Aby filtrować wyniki dotyczące nieobsługiwanych łączników, ustaw wartość parametru connectorTypes na EV_CONNECTOR_TYPE_OTHER.
      • Aby odfiltrować wyniki dla dowolnego typu złącza, które jest gniazdkiem ściennym, ustaw wartość connectorTypes na EV_CONNECTOR_TYPE_UNSPECIFIED_WALL_OUTLET.
      • Aby filtrować wyniki według dowolnego typu złącza, ustaw wartość connectorTypes na EV_CONNECTOR_TYPE_UNSPECIFIED lub nie ustawiaj wartości connectorTypes.

    • minimumChargingRateKw

      Filtruje miejsca według minimalnej szybkości ładowania EV w kilowatach (kW). Wszystkie miejsca, w których stawka za ładowanie jest niższa niż minimalna stawka za ładowanie, są odfiltrowywane. Jeśli na przykład chcesz znaleźć ładowarki EV o mocy ładowania co najmniej 10 kW, możesz ustawić ten parametr na „10”.

  • minRating

    Ogranicza wyniki tylko do tych, których średnia ocena użytkowników jest większa lub równa temu limitowi. Wartości muszą mieścić się w zakresie od 0,0 do 5,0 (włącznie) i być wielokrotnością 0,5. Na przykład: 0, 0,5, 1,0, ..., 5,0 włącznie. Wartości są zaokrąglane w górę do najbliższej liczby z końcówką 0,5. Na przykład wartość 0,6 eliminuje wszystkie wyniki z oceną mniejszą niż 1,0.

  • openNow

    Jeśli true, zwracaj tylko te miejsca, które są otwarte w momencie wysłania zapytania. Jeśli false, zwróć wszystkie firmy niezależnie od stanu otwarcia. Miejsca, które nie mają określonych godzin otwarcia w bazie danych Miejsc Google, są zwracane, jeśli ustawisz ten parametr na false.

  • pageSize

    Określa liczbę wyników (od 1 do 20) wyświetlanych na stronie. Jeśli np. ustawisz wartość pageSize na 5, na pierwszej stronie pojawi się maksymalnie 5 wyników. Jeśli zapytanie może zwrócić więcej wyników, odpowiedź zawiera token nextPageToken, który możesz przekazać w kolejnym żądaniu, aby uzyskać dostęp do następnej strony.

  • pageToken

    Określa nextPageToken z treści odpowiedzi na poprzedniej stronie.

  • priceLevels

    Ogranicz wyszukiwanie do miejsc o określonym poziomie cen. Domyślnie wybrane są wszystkie poziomy cenowe.

    Poziomy cen mogą być dostępne w przypadku miejsc tych typów:

    Miejsca nieobsługiwanych typów nie zostaną uwzględnione w odpowiedzi, jeśli określono parametr priceLevels.

    Podaj tablicę zawierającą co najmniej 1 wartość zdefiniowaną przez PriceLevel.

    Na przykład:

    "priceLevels":["PRICE_LEVEL_INEXPENSIVE", "PRICE_LEVEL_MODERATE"]

  • rankPreference

    Określa, w jaki sposób wyniki są klasyfikowane w odpowiedzi na podstawie typu zapytania:

    • W przypadku zapytania kategorycznego, np. „Restauracje w Nowym Jorku”, domyślnie używana jest funkcja RELEVANCE (sortowanie wyników według trafności wyszukiwania). Możesz ustawić wartość rankPreference na RELEVANCE lub DISTANCE (sortowanie wyników według odległości).
    • W przypadku zapytania niekategorycznego, np. „Mountain View, CA”, zalecamy pozostawienie parametru rankPreference bez ustawionej wartości.

  • regionCode

    Kod regionu używany do formatowania odpowiedzi, określony jako dwuznakowy kod CLDR. Ten parametr może też wpływać na wyniki wyszukiwania. Nie ma wartości domyślnej.

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

    Większość kodów CLDR jest identyczna z kodami ISO 3166-1, z kilkoma istotnymi wyjątkami. Na przykład krajowa domena najwyższego poziomu Zjednoczonego Królestwa to „uk” (.co.uk), a kod ISO 3166-1 to „gb” (technicznie dla podmiotu „Zjednoczone Królestwo Wielkiej Brytanii i Irlandii Północnej”). W zależności od obowiązujących przepisów parametr może wpływać na wyniki.

  • strictTypeFiltering

    Używany z parametrem includedType. Jeśli ustawisz wartość true, zwracane będą tylko miejsca pasujące do typów określonych przez parametr includeType. Gdy wartość jest fałszywa (domyślnie), odpowiedź może zawierać miejsca, które nie pasują do określonych typów.

Przykłady wyszukiwania tekstowego (nowego)

Znajdź miejsce za pomocą ciągu zapytania

Poniższy przykład pokazuje żądanie wyszukiwania tekstowego (nowego) dotyczące „pikantnego jedzenia wegetariańskiego w Sydney w Australii”:

curl -X POST -d '{
  "textQuery" : "Spicy Vegetarian Food in Sydney, Australia"
}' \
-H 'Content-Type: application/json' -H 'X-Goog-Api-Key: API_KEY' \
-H 'X-Goog-FieldMask: places.displayName,places.formattedAddress' \
'https://places.googleapis.com/v1/places:searchText'

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

{
  "places": [
    {
      "formattedAddress": "367 Pitt St, Sydney NSW 2000, Australia",
      "displayName": {
        "text": "Mother Chu's Vegetarian Kitchen",
        "languageCode": "en"
      }
    },
    {
      "formattedAddress": "175 First Ave, Five Dock NSW 2046, Australia",
      "displayName": {
        "text": "Veggo Sizzle - Vegan & Vegetarian Restaurant, Five Dock, Sydney",
        "languageCode": "en"
      }
    },
    {
      "formattedAddress": "29 King St, Sydney NSW 2000, Australia",
      "displayName": {
        "text": "Peace Harmony",
        "languageCode": "en"
      }
    },
    ...
  ]
}

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

curl -X POST -d '{
  "textQuery" : "Spicy Vegetarian Food in Sydney, Australia"
}' \
-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:searchText'

Odpowiedź ma teraz postać:

{
  "places": [
    {
      "types": [
        "vegetarian_restaurant",
        "vegan_restaurant",
        "chinese_restaurant",
        "restaurant",
        "food",
        "point_of_interest",
        "establishment"
      ],
      "formattedAddress": "367 Pitt St, Sydney NSW 2000, Australia",
      "websiteUri": "http://www.motherchusvegetarian.com.au/",
      "displayName": {
        "text": "Mother Chu's Vegetarian Kitchen",
        "languageCode": "en"
      }
    },
    {
      "types": [
        "vegan_restaurant",
        "thai_restaurant",
        "vegetarian_restaurant",
        "indian_restaurant",
        "italian_restaurant",
        "american_restaurant",
        "restaurant",
        "food",
        "point_of_interest",
        "establishment"
      ],
      "formattedAddress": "175 First Ave, Five Dock NSW 2046, Australia",
      "websiteUri": "http://www.veggosizzle.com.au/",
      "displayName": {
        "text": "Veggo Sizzle - Vegan & Vegetarian Restaurant, Five Dock, Sydney",
        "languageCode": "en"
      }
    },
    ...
  ]
}

Filtrowanie miejsc według poziomu cen

Użyj opcji priceLevel, aby przefiltrować wyniki i wyświetlić restauracje zdefiniowane jako niedrogie lub średnio drogie:

curl -X POST -d '{
  "textQuery" : "Spicy Vegetarian Food in Sydney, Australia",
  "priceLevels":["PRICE_LEVEL_INEXPENSIVE", "PRICE_LEVEL_MODERATE"]
}' \
-H 'Content-Type: application/json' -H 'X-Goog-Api-Key: API_KEY' \
-H 'X-Goog-FieldMask: places.displayName,places.formattedAddress,places.priceLevel' \
'https://places.googleapis.com/v1/places:searchText'

W tym przykładzie użyto też nagłówka X-Goog-FieldMask, aby dodać pole danych places.priceLevel do odpowiedzi,places.priceLevel dzięki czemu ma ona postać:

{
  "places": [
    {
      "formattedAddress": "367 Pitt St, Sydney NSW 2000, Australia",
      "priceLevel": "PRICE_LEVEL_MODERATE",
      "displayName": {
        "text": "Mother Chu's Vegetarian Kitchen",
        "languageCode": "en"
      }
    },
    {
      "formattedAddress": "115 King St, Newtown NSW 2042, Australia",
      "priceLevel": "PRICE_LEVEL_MODERATE",
      "displayName": {
        "text": "Green Mushroom",
        "languageCode": "en"
      }
    },
    ...
  ]
}

Dodaj dodatkowe opcje, aby zawęzić wyszukiwanie, np. includedType, minRating, rankPreference, openNow i inne parametry opisane w sekcji Parametry opcjonalne.

Ograniczanie wyszukiwania do określonego obszaru

Aby ograniczyć wyszukiwanie do określonego obszaru, użyj właściwości locationRestriction lub locationBias, ale nie obu naraz. locationRestriction określa region, w którym muszą się znajdować wyniki, a locationBias określa region, w pobliżu którego muszą się znajdować wyniki, ale mogą być poza tym obszarem.

Ograniczanie obszaru za pomocą parametru locationRestriction

Użyj parametru locationRestriction, aby ograniczyć wyniki zapytania do określonego regionu. W treści żądania podaj wartości szerokości i długości geograficznej low i high, które określają granicę regionu.

Poniższy przykład pokazuje żądanie wyszukiwania tekstowego (nowego) dotyczące „jedzenia wegetariańskiego” w Nowym Jorku. To żądanie zwraca tylko pierwsze 10 wyników dla otwartych miejsc.

curl -X POST -d '{
  "textQuery" : "vegetarian food",
  "pageSize" : "10",
  "locationRestriction": {
    "rectangle": {
      "low": {
        "latitude": 40.477398,
        "longitude": -74.259087
      },
      "high": {
        "latitude": 40.91618,
        "longitude": -73.70018
      }
    }
  }
}' \
  -H 'Content-Type: application/json' \
  -H 'X-Goog-Api-Key: API_KEY' \
  -H 'X-Goog-FieldMask: places.id,places.formattedAddress' \
  'https://places.googleapis.com/v1/places:searchText'

Określanie obszaru za pomocą parametru locationBias

Poniższy przykład pokazuje żądanie wyszukiwania tekstowego (nowego) dla hasła „jedzenie wegetariańskie” z określeniem lokalizacji w promieniu 500 metrów od punktu w centrum San Francisco. To żądanie zwraca tylko pierwsze 10 wyników dla otwartych miejsc.

curl -X POST -d '{
  "textQuery" : "vegetarian food",
  "openNow": true,
  "pageSize": 10,
  "locationBias": {
    "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' \
'https://places.googleapis.com/v1/places:searchText'

Wyszukiwanie ładowarek EV o minimalnej szybkości ładowania

Użyj ikon minimumChargingRateKw i connectorTypes, aby wyszukać miejsca z dostępnymi ładowarkami zgodnymi z Twoim pojazdem elektrycznym.

Poniższy przykład pokazuje żądanie dotyczące złączy do ładowania pojazdów elektrycznych typu Tesla i J1772 1 o minimalnej szybkości ładowania 10 kW w Mountain View w Kalifornii. Zwracane są tylko 4 wyniki.

curl -X POST -d '{
    "textQuery": "EV Charging Station Mountain View",
    "pageSize": 4,
    "evOptions": {
      "minimumChargingRateKw": 10,
      "connectorTypes": ["EV_CONNECTOR_TYPE_J1772","EV_CONNECTOR_TYPE_TESLA"]
    }
  }' \
-H 'Content-Type: application/json' -H 'X-Goog-Api-Key: API_KEY' \
-H "X-Goog-FieldMask: places.displayName,places.evChargeOptions" \
'https://places.googleapis.com/v1/places:searchText'

Żądanie zwraca tę odpowiedź:

{
  "places": [
    {
      "displayName": {
        "text": "EVgo Charging Station",
        "languageCode": "en"
      },
      "evChargeOptions": {
        "connectorCount": 16,
        "connectorAggregation": [
          {
            "type": "EV_CONNECTOR_TYPE_CHADEMO",
            "maxChargeRateKw": 100,
            "count": 8,
            "availableCount": 5,
            "outOfServiceCount": 0,
            "availabilityLastUpdateTime": "2024-01-10T19:10:00Z"
          },
          {
            "type": "EV_CONNECTOR_TYPE_CCS_COMBO_1",
            "maxChargeRateKw": 100,
            "count": 2,
            "availableCount": 2,
            "outOfServiceCount": 0,
            "availabilityLastUpdateTime": "2024-01-10T19:10:00Z"
          },
          {
            "type": "EV_CONNECTOR_TYPE_CCS_COMBO_1",
            "maxChargeRateKw": 350,
            "count": 6,
            "availableCount": 3,
            "outOfServiceCount": 0,
            "availabilityLastUpdateTime": "2024-01-10T19:10:00Z"
          }
        ]
      }
    },
    {
      "displayName": {
        "text": "EVgo Charging Station",
        "languageCode": "en"
      },
      "evChargeOptions": {
        "connectorCount": 6,
        "connectorAggregation": [
          {
            "type": "EV_CONNECTOR_TYPE_CCS_COMBO_1",
            "maxChargeRateKw": 100,
            "count": 4,
            "availableCount": 3,
            "outOfServiceCount": 0,
            "availabilityLastUpdateTime": "2024-01-10T19:10:00Z"
          },
          {
            "type": "EV_CONNECTOR_TYPE_CCS_COMBO_1",
            "maxChargeRateKw": 350,
            "count": 2,
            "availableCount": 0,
            "outOfServiceCount": 2,
            "availabilityLastUpdateTime": "2024-01-10T19:10:00Z"
          }
        ]
      }
    },
    {
      "displayName": {
        "text": "EVgo Charging Station",
        "languageCode": "en"
      },
      "evChargeOptions": {
        "connectorCount": 5,
        "connectorAggregation": [
          {
            "type": "EV_CONNECTOR_TYPE_J1772",
            "maxChargeRateKw": 3.5999999046325684,
            "count": 1,
            "availableCount": 0,
            "outOfServiceCount": 1,
            "availabilityLastUpdateTime": "2024-01-10T19:10:00Z"
          },
          {
            "type": "EV_CONNECTOR_TYPE_CHADEMO",
            "maxChargeRateKw": 50,
            "count": 2,
            "availableCount": 0,
            "outOfServiceCount": 0,
            "availabilityLastUpdateTime": "2024-01-10T19:10:00Z"
          },
          {
            "type": "EV_CONNECTOR_TYPE_CCS_COMBO_1",
            "maxChargeRateKw": 50,
            "count": 2,
            "availableCount": 0,
            "outOfServiceCount": 0,
            "availabilityLastUpdateTime": "2024-01-10T19:10:00Z"
          }
        ]
      }
    },
    {
      "displayName": {
        "text": "Electric Vehicle Charging Station",
        "languageCode": "en"
      },
      "evChargeOptions": {
        "connectorCount": 10,
        "connectorAggregation": [
          {
            "type": "EV_CONNECTOR_TYPE_OTHER",
            "maxChargeRateKw": 210,
            "count": 10
          }
        ]
      }
    }
  ]
}

Wyszukiwanie firm działających na określonym obszarze

Użyj parametru includePureServiceAreaBusinesses, aby wyszukać firmy bez fizycznego adresu świadczenia usługi (np. mobilną firmę sprzątającą lub food trucka).

Poniższy przykład pokazuje żądanie dotyczące hydraulików w San Francisco:

curl -X POST -d '{
  "textQuery" : "plumber San Francisco",
  "includePureServiceAreaBusinesses": true
}' \
-H 'Content-Type: application/json' -H 'X-Goog-Api-Key: API_KEY' \
-H 'X-Goog-FieldMask: places.displayName,places.formattedAddress' \
'https://places.googleapis.com/v1/places:searchText'

W odpowiedzi firmy bez fizycznego adresu usługi nie uwzględniają pola formattedAddress:

{
  "places": [
    {
      "formattedAddress": "3450 Sacramento St #204, San Francisco, CA 94118, USA",
      "displayName": {
        "text": "Advanced Plumbing & Drain",
        "languageCode": "en"
      }
    },
    {
      "formattedAddress": "1455 Bancroft Ave, San Francisco, CA 94124, USA",
      "displayName": {
        "text": "Magic Plumbing Heating & Cooling",
        "languageCode": "en"
      }
    },
    /.../
    {
      "displayName": {
        "text": "Starboy Plumbing Inc.",
        "languageCode": "en"
      }
    },
    {
      "formattedAddress": "78 Dorman Ave, San Francisco, CA 94124, USA",
      "displayName": {
        "text": "Cabrillo Plumbing, Heating & Air",
        "languageCode": "en"
      }
    },
    {
      "formattedAddress": "540 Barneveld Ave # D, San Francisco, CA 94124, USA",
      "displayName": {
        "text": "Mr. Rooter Plumbing of San Francisco",
        "languageCode": "en"
      }
    },
    /.../
    {
      "displayName": {
        "text": "Pipeline Plumbing",
        "languageCode": "en"
      }
    },
    {
      "formattedAddress": "350 Bay St #100-178, San Francisco, CA 94133, USA",
      "displayName": {
        "text": "One Source Plumbing and Rooter",
        "languageCode": "en"
      }
    },
    /.../
  ]
}

Określanie liczby wyników do zwrócenia na stronie

Użyj parametru pageSize, aby określić liczbę wyników zwracanych na stronie. Parametr nextPageToken w treści odpowiedzi zawiera token, którego można użyć w kolejnych wywołaniach, aby uzyskać dostęp do następnej strony wyników.

Poniższy przykład pokazuje żądanie „pizza w Nowym Jorku” ograniczone do 5 wyników na stronę:

 curl -X POST -d '{
  "textQuery": "pizza in New York",
  "pageSize": 5
  }' \
-H 'Content-Type: application/json' -H 'X-Goog-Api-Key: API_KEY' \
-H "X-Goog-FieldMask: places.id,nextPageToken" \
'https://places.googleapis.com/v1/places:searchText'

{
  "places": [
    {
      "id": "ChIJifIePKtZwokRVZ-UdRGkZzs"
    },
    {
      "id": "ChIJPxPd_P1YwokRfzLhSiACEoU"
    },
    {
      "id": "ChIJrXXKn5NZwokR78g0ipCnY60"
    },
    {
      "id": "ChIJ6ySICVZYwokR9rIK8HjXhzE"
    },
    {
      "id": "ChIJ6xvs94VZwokRnT1D2lX2OTw"
    }
  ],
  "nextPageToken": "AeCrKXsZWzNVbPzO-MRWPu52jWO_Xx8aKwOQ69_Je3DxRpfdjClq8Ekwh3UcF2h2Jn75kL6PtWLGV4ecQri-GEUKN_OFpJkdVc-JL4Q"
}

Aby uzyskać dostęp do następnej strony wyników, użyj pageToken, aby przekazać nextPageToken w treści żądania:

 curl -X POST -d '{
  "textQuery": "pizza in New York",
  "pageSize": 5,
  "pageToken": "AeCrKXsZWzNVbPzO-MRWPu52jWO_Xx8aKwOQ69_Je3DxRpfdjClq8Ekwh3UcF2h2Jn75kL6PtWLGV4ecQri-GEUKN_OFpJkdVc-JL4Q"
  }' \
-H 'Content-Type: application/json' -H 'X-Goog-Api-Key: API_KEY' \
-H "X-Goog-FieldMask: places.id,nextPageToken" \
'https://places.googleapis.com/v1/places:searchText'

{
  "places": [
    {
      "id": "ChIJL-LN1N1ZwokR8K2jACu6Ydw"
    },
    {
      "id": "ChIJjaD94kFZwokR-20CXqlpy_4"
    },
    {
      "id": "ChIJ6ffdpJNZwokRmcafdROM5q0"
    },
    {
      "id": "ChIJ8Q2WSpJZwokRQz-bYYgEskM"
    },
    {
      "id": "ChIJ8164qwFZwokRhplkmhvq1uE"
    }
  ],
  "nextPageToken": "AeCrKXvPd6uUy-oj96W2OaqEe2pUD8QTxOM8-sKfUcFsC9t2Wey5qivrKGoGSxcZnyc7RPmaFfAktslrKbUh31ZDTkL0upRmaxA7c_c"
}

Pobieranie deskryptorów adresu

Deskryptory adresów zawierają informacje o lokalizacji miejsca, w tym o pobliskich punktach orientacyjnych i obszarach.

Poniższy przykład pokazuje żądanie wyszukiwania tekstowego (nowego) miejsc w pobliżu centrum handlowego w San Jose. W tym przykładzie w masce pola uwzględniasz addressDescriptors:

curl -X POST -d '{
  "textQuery": "clothes",
  "maxResultCount": 5,
  "locationBias": {
    "circle": {
      "center": {
        "latitude": 37.321328,
        "longitude": -121.946275
      }
    }
  },
  "rankPreference":"RANK_PREFERENCE_UNSPECIFIED"
}' \
-H 'Content-Type: application/json' \
-H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: places.displayName,places.addressDescriptor" \
https://places.googleapis.com/v1/places:searchText

Odpowiedź zawiera miejsce określone w żądaniu, listę pobliskich punktów orientacyjnych i ich odległość od tego miejsca oraz listę obszarów i ich relację do tego miejsca:

  {
  "places": [
    {
      "displayName": {
        "text": "Urban Outfitters",
        "languageCode": "en"
      },
      "addressDescriptor": {
        "landmarks": [
          {
            "name": "places/ChIJVVVVUB7Lj4ARXyb4HFVDV8s",
            "placeId": "ChIJVVVVUB7Lj4ARXyb4HFVDV8s",
            "displayName": {
              "text": "Westfield Valley Fair",
              "languageCode": "en"
            },
            "types": [
              "clothing_store",
              "department_store",
              "establishment",
              "food",
              "movie_theater",
              "point_of_interest",
              "restaurant",
              "shoe_store",
              "shopping_mall",
              "store"
            ],
            "spatialRelationship": "WITHIN",
            "straightLineDistanceMeters": 133.72855
          },
          {
            "name": "places/ChIJ62_oCR7Lj4AR_MGWkSPotD4",
            "placeId": "ChIJ62_oCR7Lj4AR_MGWkSPotD4",
            "displayName": {
              "text": "Nordstrom",
              "languageCode": "en"
            },
            "types": [
              "clothing_store",
              "department_store",
              "establishment",
              "point_of_interest",
              "shoe_store",
              "store"
            ],
            "straightLineDistanceMeters": 250.99161
          },
          {
            "name": "places/ChIJ8WvuSB7Lj4ARFyHppkxDRQ4",
            "placeId": "ChIJ8WvuSB7Lj4ARFyHppkxDRQ4",
            "displayName": {
              "text": "Macy's",
              "languageCode": "en"
            },
            "types": [
              "clothing_store",
              "department_store",
              "establishment",
              "point_of_interest",
              "store"
            ],
            "straightLineDistanceMeters": 116.24196
          },
          {
            "name": "places/ChIJ9d3plB_Lj4ARzyaU5bn80WY",
            "placeId": "ChIJ9d3plB_Lj4ARzyaU5bn80WY",
            "displayName": {
              "text": "Bank of America Financial Center",
              "languageCode": "en"
            },
            "types": [
              "bank",
              "establishment",
              "finance",
              "point_of_interest"
            ],
            "straightLineDistanceMeters": 121.61515
          },
          {
            "name": "places/ChIJaXCjxvXLj4ARCPmQpvJ52Lw",
            "placeId": "ChIJaXCjxvXLj4ARCPmQpvJ52Lw",
            "displayName": {
              "text": "Bloomingdale's",
              "languageCode": "en"
            },
            "types": [
              "clothing_store",
              "department_store",
              "establishment",
              "furniture_store",
              "home_goods_store",
              "point_of_interest",
              "shoe_store",
              "store"
            ],
            "straightLineDistanceMeters": 81.32396
          }
        ],
        "areas": [
          {
            "name": "places/ChIJb3F-EB7Lj4ARnHApQ_Hu1gI",
            "placeId": "ChIJb3F-EB7Lj4ARnHApQ_Hu1gI",
            "displayName": {
              "text": "Westfield Valley Fair",
              "languageCode": "en"
            },
            "containment": "WITHIN"
          },
          {
            "name": "places/ChIJXYuykB_Lj4AR1Ot8nU5q26Q",
            "placeId": "ChIJXYuykB_Lj4AR1Ot8nU5q26Q",
            "displayName": {
              "text": "Valley Fair",
              "languageCode": "en"
            },
            "containment": "WITHIN"
          },
          {
            "name": "places/ChIJtYoUX2DLj4ARKoKOb1G0CpM",
            "placeId": "ChIJtYoUX2DLj4ARKoKOb1G0CpM",
            "displayName": {
              "text": "Central San Jose",
              "languageCode": "en"
            },
            "containment": "WITHIN"
          }
        ]
      }
    },
    /.../
  ]
}

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 edytuj parametry żądania.

  3. Kliknij przycisk Wykonaj. W oknie dialogowym wybierz konto, z którego chcesz wysłać prośbę.

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