Ta strona została przetłumaczona przez Cloud Translation API.

Autouzupełnianie (nowość)

Wybierz platformę: Android iOS JavaScript Usługa internetowa

Deweloperzy z Europejskiego Obszaru Gospodarczego (EOG)

Wprowadzenie

Autouzupełnianie (nowa wersja) to usługa internetowa, która w odpowiedzi na żądanie HTTP zwraca prognozy miejsc i prognozy zapytań. W żądaniu podaj ciąg tekstowy wyszukiwania i granice geograficzne, które określają obszar wyszukiwania.

Autouzupełnianie (nowa wersja) może dopasowywać całe słowa i podciągi wejściowe, rozwiązując nazwy miejsc, adresy i kody plus. Dzięki temu aplikacje mogą wysyłać zapytania w trakcie wpisywania przez użytkownika tekstu, aby na bieżąco podawać prognozy dotyczące miejsc i zapytań.

Odpowiedź z interfejsu Autocomplete (New) może zawierać 2 rodzaje prognoz:

Prognozy dotyczące miejsc: miejsca, takie jak firmy, adresy i ciekawe miejsca, na podstawie określonego ciągu tekstowego i obszaru wyszukiwania. Prognozy miejsc są domyślnie zwracane.
Prognozy zapytań: ciągi zapytań pasujące do ciągu tekstu wejściowego i obszaru wyszukiwania. Domyślnie nie są zwracane prognozy zapytań. Użyj parametru żądania includeQueryPredictions, aby dodać do odpowiedzi prognozy zapytań.

Na przykład wywołujesz autouzupełnianie (nowe), używając jako danych wejściowych ciągu znaków zawierającego częściowe dane wejściowe użytkownika „Sicilian piz” z obszarem wyszukiwania ograniczonym do San Francisco w Kalifornii. Odpowiedź zawiera listę prognoz dotyczących miejsc, które pasują do ciągu wyszukiwania i obszaru wyszukiwania, np. restauracji o nazwie „Sicilian Pizza Kitchen”, wraz ze szczegółami dotyczącymi tego miejsca.

Zwrócone prognozy miejsc są przeznaczone do wyświetlania użytkownikowi, aby ułatwić mu wybór zamierzonego miejsca. Możesz wysłać żądanie Szczegóły miejsca (nowe), aby uzyskać więcej informacji o dowolnej z zwróconych prognoz miejsc.

Odpowiedź może też zawierać listę podpowiedzi do zapytania, które pasują do ciągu wyszukiwania i obszaru wyszukiwania, np. „Sicilian Pizza & Pasta”. Każda prognoza zapytania w odpowiedzi zawiera pole text z rekomendowanym ciągiem znaków do wyszukiwania tekstowego. Użyj tego ciągu znaków jako danych wejściowych w wyszukiwaniu tekstowym (nowym), aby przeprowadzić bardziej szczegółowe wyszukiwanie.

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

Żądania autouzupełniania (nowe)

Żądanie Autocomplete (New) to żądanie HTTP POST wysyłane na adres URL w formacie:

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

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

curl -X POST -d '{
  "input": "pizza",
  "locationBias": {
    "circle": {
      "center": {
        "latitude": 37.7937,
        "longitude": -122.3965
      },
      "radius": 500.0
    }
  }
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
https://places.googleapis.com/v1/places:autocomplete

Obsługiwane parametry

Parametr	Opis
`input`*	Ciąg tekstowy do wyszukania (całe słowa, podciągi, nazwy miejsc, adresy, kody plus).
`FieldMask` (nagłówek HTTP)	Lista rozdzielona przecinkami określająca pola, które mają być zwracane w odpowiedzi.
`includedPrimaryTypes`	Ogranicza wyniki do miejsc pasujących do jednego z maksymalnie 5 określonych typów podstawowych.
`includePureServiceAreaBusinesses`	Jeśli ma wartość „true”, obejmuje firmy bez fizycznej lokalizacji (firmy działające na określonym obszarze). Wartość domyślna to fałsz.
`includeQueryPredictions`	Jeśli wartość to „true”, w odpowiedzi uwzględniane są zarówno prognozy dotyczące miejsca, jak i zapytania. Wartość domyślna to fałsz.
`includedRegionCodes`	Tablica zawierająca maksymalnie 15 dwuznakowych kodów krajów, do których chcesz ograniczyć wyniki.
`inputOffset`	Indeks znaku Unicode (liczony od zera) w ciągu wejściowym, który określa pozycję kursora i ma wpływ na prognozy. Domyślnie jest to długość danych wejściowych.
`languageCode`	Preferowany język wyników (kod IETF BCP-47). Domyślnie jest to nagłówek Accept-Language lub „en”.
`locationBias`	Określa obszar (okrąg lub prostokąt), w którym mają być preferowane wyniki wyszukiwania, ale dopuszcza też wyniki spoza tego obszaru. Nie można używać z parametrem locationRestriction.
`locationRestriction`	Określa obszar (okrąg lub prostokąt), w którym mają się mieścić wyniki wyszukiwania. Wyniki spoza tego obszaru są wykluczane. Nie można używać z parametrem locationBias.
`origin`	Punkt początkowy (szerokość i długość geograficzna) używany do obliczania odległości w linii prostej (distanceMeters) do przewidywanych miejsc docelowych.
`regionCode`	Kod regionu używany do formatowania odpowiedzi i sugerowania odpowiedzi (np. 'uk', 'fr').
`sessionToken`	Ciąg znaków wygenerowany przez użytkownika, który służy do grupowania wywołań autouzupełniania w sesję na potrzeby rozliczeń.

* oznacza pole wymagane.

Informacje o odpowiedzi

Autouzupełnianie (nowe) zwraca obiekt JSON jako odpowiedź. W odpowiedzi:

Tablica suggestions zawiera wszystkie przewidywane miejsca i zapytania w kolejności określonej na podstawie ich trafności. Każde miejsce jest reprezentowane przez pole placePrediction, a każde zapytanie – przez pole queryPrediction.
Pole placePrediction zawiera szczegółowe informacje o jednej prognozie miejsca, w tym identyfikator miejsca i opis tekstowy.
Pole queryPrediction zawiera szczegółowe informacje o pojedynczej prognozie zapytania.

Uwaga: autouzupełnianie (nowe) zwraca łącznie 5 podpowiedzi w postaci placePredictions, queryPredictions lub kombinacji tych typów w zależności od żądania. Jeśli w żądaniu nie ustawiono parametru includeQueryPredictions, odpowiedź zawiera maksymalnie 5 placePredictions. Jeśli żądanie zawiera parametr includeQueryPredictions, odpowiedź zawiera maksymalnie 5 podpowiedzi w połączeniu placePredictions i queryPredictions.

Pełny obiekt JSON ma postać:

{
  "suggestions": [
    {
      "placePrediction": {
        "place": "places/ChIJ5YQQf1GHhYARPKG7WLIaOko",
        "placeId": "ChIJ5YQQf1GHhYARPKG7WLIaOko",
        "text": {
          "text": "Amoeba Music, Haight Street, San Francisco, CA, USA",
          "matches": [
            {
              "endOffset": 6
            }]
        },
      ...
    },
    {
      "queryPrediction": {
        "text": {
          "text": "Amoeba Music",
          "matches": [
            {
              "endOffset": 6
            }]
        },
        ...
    }
  ...]
}

Wymagane parametry

dane wejściowe

Ciąg tekstowy, w którym ma zostać przeprowadzone wyszukiwanie. Określ pełne słowa i podciągi znaków, nazwy miejsc, adresy i kody plus. Usługa Autocomplete (New) zwraca proponowane dopasowania na podstawie tego ciągu znaków i porządkuje wyniki według ich trafności.

Parametry opcjonalne

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ą nagłówka HTTP X-Goog-FieldMask.

Podaj rozdzieloną przecinkami listę pól sugestii do zwrócenia. Na przykład, aby pobrać suggestions.placePrediction.text.text i suggestions.queryPrediction.text.text sugestii.
```
  X-Goog-FieldMask: suggestions.placePrediction.text.text,suggestions.queryPrediction.text.text
```
Uwaga: w liście pól nie można używać spacji.

Użyj *, aby pobrać wszystkie pola.
```
  X-Goog-FieldMask: *
```
includedPrimaryTypes

Miejsce może mieć tylko jeden typ podstawowy z typów wymienionych w tabeli A lub tabeli B. Na przykład typ podstawowy może być "mexican_restaurant" lub "steak_house".

Domyślnie interfejs API zwraca wszystkie miejsca na podstawie parametru input, niezależnie od wartości typu podstawowego powiązanej z miejscem. Ogranicz wyniki do określonego typu podstawowego lub typów podstawowych, przekazując parametr includedPrimaryTypes.

Użyj tego parametru, aby określić maksymalnie 5 wartości typu z tabeli A lub tabeli B. Aby miejsce zostało uwzględnione w odpowiedzi, musi odpowiadać jednej z określonych wartości typu podstawowego.

Ten parametr może też zawierać zamiast tego jeden z tych symboli: (regions) lub (cities). Kolekcja typów (regions) filtruje obszary lub podziały, takie jak dzielnice i kody pocztowe. Kolekcja typu (cities) filtruje miejsca, które Google identyfikuje jako miasto.

Żądanie zostanie odrzucone z błędem INVALID_REQUEST, jeśli:
- Określono więcej niż 5 typów.
- Oprócz wartości (cities) lub (regions) określono dowolny typ.
- Wszystkie nierozpoznane typy są określone.
Uwaga: parametr includedPrimaryTypes działa tylko w przypadku głównego typu miejsca, a nie wszystkich typów powiązanych z tym miejscem. Każde miejsce ma typ podstawowy, ale nie wszystkie typy podstawowe są obsługiwane przez interfejs Places API (nowy). Obsługiwane typy to te wymienione w tabeli A lub tabeli B.
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ą.
includeQueryPredictions

Jeśli true, odpowiedź zawiera zarówno prognozy dotyczące miejsca, jak i zapytania. Wartość domyślna to false, co oznacza, że odpowiedź zawiera tylko prognozy dotyczące miejsc.
includedRegionCodes

Uwzględniaj tylko wyniki z listy określonych regionów, podanych jako tablica zawierająca maksymalnie 15 dwuznakowych wartości ccTLD („domena najwyższego poziomu”). Jeśli ten parametr zostanie pominięty, do odpowiedzi nie zostaną zastosowane żadne ograniczenia. Aby na przykład ograniczyć regiony do Niemiec i Francji:
```
    "includedRegionCodes": ["de", "fr"]
```
Jeśli określisz zarówno locationRestriction, jak i includedRegionCodes, wyniki będą znajdować się w obszarze przecięcia tych 2 ustawień.

Uwaga: jeśli otrzymasz nieoczekiwane wyniki z kodem kraju, sprawdź, czy używasz kodu, który obejmuje kraje, terytoria zależne i obszary specjalne o znaczeniu geograficznym, które Cię interesują. Informacje o kodach znajdziesz na Wikipedii: Lista kodów krajów ISO 3166 lub na platformie ISO Online Browsing Platform.
inputOffset

Indeks znaku Unicode liczony od zera, który wskazuje pozycję kursora w polu input. Pozycja kursora może wpływać na zwracane prognozy. Jeśli to pole jest puste, domyślnie przyjmuje długość input.

Uwaga: w początkowej wersji w ramach ograniczonego podglądu ta właściwość nosiła nazwę predictionTermOffset.
languageCode

Preferowany język, w którym mają być zwracane wyniki. Wyniki mogą być w różnych językach, jeśli język użyty w input różni się od wartości określonej przez languageCode lub jeśli zwrócone miejsce nie ma tłumaczenia z języka lokalnego na język languageCode.
- Aby określić preferowany język, musisz użyć kodów języków IETF BCP-47.
- Jeśli parametr languageCode nie zostanie podany, interfejs API użyje wartości określonej w nagłówku Accept-Language. Jeśli nie określisz żadnej z tych wartości, zostanie użyta wartość domyślna en. Jeśli podasz nieprawidłowy kod języka, API zwróci błąd INVALID_ARGUMENT.
- 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. Ma to też wpływ na możliwość poprawiania błędów ortograficznych przez interfejs API.
- Interfejs API próbuje podać adres ulicy, który jest czytelny zarówno dla użytkownika, jak i dla lokalnej społeczności, a jednocześnie odzwierciedla dane wejściowe użytkownika. Prognozy miejsc są formatowane w różny sposób w zależności od danych wejściowych użytkownika w każdym żądaniu.
  - Najpierw wybierane są pasujące terminy w parametrze input, przy czym w miarę możliwości używane są nazwy zgodne z ustawieniem języka wskazanym przez parametr languageCode, a w pozostałych przypadkach nazwy najlepiej pasujące do danych wejściowych użytkownika.
  - Adresy są formatowane w języku lokalnym, w piśmie czytelnym dla użytkownika, w miarę możliwości dopiero po wybraniu pasujących terminów, które odpowiadają terminom w parametrze input.
  - Wszystkie pozostałe adresy są zwracane w preferowanym języku po wybraniu pasujących terminów, które odpowiadają terminom w parametrze input. Jeśli nazwa nie jest dostępna w preferowanym języku, interfejs API użyje najbliższego dopasowania.
locationBias lub locationRestriction

Aby określić obszar wyszukiwania, możesz podać locationBias lub locationRestriction, ale nie oba jednocześnie. locationRestriction oznacza region, w którym muszą się znajdować wyniki, a locationBias oznacza region, w pobliżu którego muszą się znajdować wyniki, ale mogą być poza tym obszarem.

Uwaga: jeśli pominiesz zarówno parametr locationBias, jak i locationRestriction, Autocomplete (New) domyślnie użyje określania preferencji na podstawie adresu IP. W przypadku określania preferencji na podstawie adresu IP funkcja Autocomplete (New) używa adresu IP urządzenia do określania preferencji wyników.
- 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.
- locationRestriction
  
  Określa obszar wyszukiwania. Wyniki spoza określonego obszaru nie są zwracane.
Określ region locationBias lub locationRestriction 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. Wartością domyślną jest 0,0. W przypadku locationRestriction musisz ustawić promień na wartość większą niż 0,0. W przeciwnym razie żądanie nie zwraca żadnych wyników.
  
  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 low. Widoczny obszar jest uważany za zamknięty region, 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 jednego punktu.
  - Jeśli low.longitude > high.longitude, zakres długości geograficznej jest odwrócony (widoczny obszar przekracza linię długości geograficznej 180 stopni).
  - 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.
  Pola low i high muszą być wypełnione, 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
    }
  }
}
```
pochodzenie

Punkt początkowy, od którego należy obliczyć odległość w linii prostej do miejsca docelowego (zwracany jako distanceMeters). Jeśli ta wartość zostanie pominięta, odległość w linii prostej nie zostanie zwrócona. Musi być określony jako współrzędne szerokości i długości geograficznej:
```
"origin": {
    "latitude": 40.477398,
    "longitude": -74.259087
}
```
regionCode

Kod regionu używany do formatowania odpowiedzi, określony jako 2-znakowa wartość ccTLD („domena najwyższego poziomu”). Większość kodów ccTLD jest identyczna z kodami ISO 3166-1, z kilkoma 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”).

Sugestie są też obciążone kodami regionów. Google zaleca ustawienie parametru regionCode zgodnie z preferencjami regionalnymi użytkownika.

Jeśli podasz nieprawidłowy kod regionu, interfejs API zwróci błąd INVALID_ARGUMENT. W zależności od obowiązujących przepisów parametr może wpływać na wyniki.
sessionToken

Tokeny sesji to wygenerowane przez użytkownika ciągi znaków, które śledzą wywołania Autouzupełniania (nowego) jako „sesje”. Autouzupełnianie (nowa wersja) używa tokenów sesji do grupowania faz zapytania i wyboru w wyszukiwaniu autouzupełniania użytkownika w osobną sesję na potrzeby rozliczeń. Więcej informacji znajdziesz w artykule Tokeny sesji.

Wybieranie parametrów, które mają wpływać na wyniki

Parametry autouzupełniania (nowe) mogą wpływać na wyniki wyszukiwania w inny sposób. W tabeli poniżej znajdziesz zalecenia dotyczące używania parametrów w zależności od zamierzonego wyniku.

Parametr	Zalecenia dotyczące użytkowania
`regionCode`	Ustaw zgodnie z preferencjami regionalnymi użytkownika.
`includedRegionCodes`	Ustaw, aby ograniczyć wyniki do listy określonych regionów.
`locationBias`	Używaj, gdy preferowane są wyniki w regionie lub w jego pobliżu. W odpowiednich przypadkach zdefiniuj region jako widoczny obszar mapy, na który patrzy użytkownik.
`locationRestriction`	Używaj wartości only, gdy wyniki spoza regionu nie powinny być zwracane.
`origin`	Użyj, gdy zamierzasz obliczyć odległość w linii prostej do każdej prognozy. Uwaga: odległość nie będzie dostępna w przypadku wszystkich prognoz. Zobacz Brak odległości w odpowiedzi.

Przykłady autouzupełniania (nowa wersja)

Ograniczanie wyszukiwania do obszaru za pomocą parametru locationRestriction

Uwaga: Autocomplete (New) domyślnie używa funkcji IP biasing do kontrolowania obszaru wyszukiwania. W przypadku stosowania funkcji IP biasing Autocomplete (New) używa adresu IP urządzenia do określania wyników. Opcjonalnie możesz użyć właściwości locationRestriction lub locationBias, ale nie obu jednocześnie, aby określić obszar wyszukiwania.

locationRestriction określa obszar wyszukiwania. Wyniki spoza określonego obszaru nie są zwracane. W poniższym przykładzie używasz parametru locationRestriction, aby ograniczyć żądanie do okręgu o promieniu 5000 metrów wyśrodkowanego na San Francisco:

curl -X POST -d '{
  "input": "Art museum",
  "locationRestriction": {
    "circle": {
      "center": {
        "latitude": 37.7749,
        "longitude": -122.4194
      },
      "radius": 5000.0
    }
  }
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
https://places.googleapis.com/v1/places:autocomplete

Wszystkie wyniki z określonych obszarów znajdują się w tablicy suggestions:

  {
    "suggestions": [
      {
        "placePrediction": {
          "place": "places/ChIJkQQVTZqAhYARHxPt2iJkm1Q",
          "placeId": "ChIJkQQVTZqAhYARHxPt2iJkm1Q",
          "text": {
            "text": "Asian Art Museum, Larkin Street, San Francisco, CA, USA",
            "matches": [
              {
                "startOffset": 6,
                "endOffset": 16
              }
            ]
          },
          "structuredFormat": {
            "mainText": {
              "text": "Asian Art Museum",
              "matches": [
                {
                  "startOffset": 6,
                  "endOffset": 16
                }
              ]
            },
            "secondaryText": {
              "text": "Larkin Street, San Francisco, CA, USA"
            }
          },
          "types": [
            "establishment",
            "museum",
            "point_of_interest"
          ]
        }
      },
      {
        "placePrediction": {
          "place": "places/ChIJI7NivpmAhYARSuRPlbbn_2w",
          "placeId": "ChIJI7NivpmAhYARSuRPlbbn_2w",
          "text": {
            "text": "de Young Museum, Hagiwara Tea Garden Drive, San Francisco, CA, USA",
            "matches": [
              {
                "endOffset": 15
              }
            ]
          },
          "structuredFormat": {
            "mainText": {
              "text": "de Young Museum",
              "matches": [
                {
                  "endOffset": 15
                }
              ]
            },
            "secondaryText": {
              "text": "Hagiwara Tea Garden Drive, San Francisco, CA, USA"
            }
          },
          "types": [
            "establishment",
            "point_of_interest",
            "tourist_attraction",
            "museum"
          ]
        }
      },
      /.../
    ]
  }

Możesz też użyć znaku locationRestriction, aby ograniczyć wyszukiwanie do prostokątnego widocznego obszaru. Poniższy przykład ogranicza żądanie do centrum San Francisco:

  curl -X POST -d '{
    "input": "Art museum",
    "locationRestriction": {
      "rectangle": {
        "low": {
          "latitude": 37.7751,
          "longitude": -122.4219
        },
        "high": {
          "latitude": 37.7955,
          "longitude": -122.3937
        }
      }
    }
  }' \
  -H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
  https://places.googleapis.com/v1/places:autocomplete

Wyniki są zawarte w tablicy suggestions:

  {
    "suggestions": [
      {
        "placePrediction": {
          "place": "places/ChIJkQQVTZqAhYARHxPt2iJkm1Q",
          "placeId": "ChIJkQQVTZqAhYARHxPt2iJkm1Q",
          "text": {
            "text": "Asian Art Museum, Larkin Street, San Francisco, CA, USA",
            "matches": [
              {
                "startOffset": 6,
                "endOffset": 16
              }
            ]
          },
          "structuredFormat": {
            "mainText": {
              "text": "Asian Art Museum",
              "matches": [
                {
                  "startOffset": 6,
                  "endOffset": 16
                }
              ]
            },
            "secondaryText": {
              "text": "Larkin Street, San Francisco, CA, USA"
            }
          },
          "types": [
            "point_of_interest",
            "museum",
            "establishment"
          ]
        }
      },
      {
        "placePrediction": {
          "place": "places/ChIJyQNK-4SAhYARO2DZaJleWRc",
          "placeId": "ChIJyQNK-4SAhYARO2DZaJleWRc",
          "text": {
            "text": "International Art Museum of America, Market Street, San Francisco, CA, USA",
            "matches": [
              {
                "startOffset": 14,
                "endOffset": 24
              }
            ]
          },
          "structuredFormat": {
            "mainText": {
              "text": "International Art Museum of America",
              "matches": [
                {
                  "startOffset": 14,
                  "endOffset": 24
                }
              ]
            },
            "secondaryText": {
              "text": "Market Street, San Francisco, CA, USA"
            }
          },
          "types": [
            "museum",
            "point_of_interest",
            "tourist_attraction",
            "art_gallery",
            "establishment"
          ]
        }
      }
    ]
  }

Zawężanie wyszukiwania do obszaru za pomocą parametru locationBias

W przypadku parametru locationBias lokalizacja służy jako odchylenie, co oznacza, że mogą być zwracane wyniki z okolic określonej lokalizacji, w tym wyniki spoza określonego obszaru. W poniższym przykładzie kierujesz żądanie na śródmieście San Francisco:

curl -X POST -d '{
  "input": "Amoeba",
  "locationBias": {
    "circle": {
      "center": {
        "latitude": 37.7749,
        "longitude": -122.4194
      },
      "radius": 5000.0
    }
  }
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
https://places.googleapis.com/v1/places:autocomplete

Wyniki zawierają teraz znacznie więcej pozycji, w tym wyniki spoza promienia 5000 metrów:

{
  "suggestions": [
    {
      "placePrediction": {
        "place": "places/ChIJ5YQQf1GHhYARPKG7WLIaOko",
        "placeId": "ChIJ5YQQf1GHhYARPKG7WLIaOko",
        "text": {
          "text": "Amoeba Music, Haight Street, San Francisco, CA, USA",
          "matches": [
            {
              "endOffset": 6
            }
          ]
        },
        "structuredFormat": {
          "mainText": {
            "text": "Amoeba Music",
            "matches": [
              {
                "endOffset": 6
              }
            ]
          },
          "secondaryText": {
            "text": "Haight Street, San Francisco, CA, USA"
          }
        },
        "types": [
          "electronics_store",
          "point_of_interest",
          "store",
          "establishment",
          "home_goods_store"
        ]
      }
    },
    {
      "placePrediction": {
        "place": "places/ChIJr7uwwy58hYARBY-e7-QVwqw",
        "placeId": "ChIJr7uwwy58hYARBY-e7-QVwqw",
        "text": {
          "text": "Amoeba Music, Telegraph Avenue, Berkeley, CA, USA",
          "matches": [
            {
              "endOffset": 6
            }
          ]
        },
        "structuredFormat": {
          "mainText": {
            "text": "Amoeba Music",
            "matches": [
              {
                "endOffset": 6
              }
            ]
          },
          "secondaryText": {
            "text": "Telegraph Avenue, Berkeley, CA, USA"
          }
        },
        "types": [
          "electronics_store",
          "point_of_interest",
          "establishment",
          "home_goods_store",
          "store"
        ]
      }
    },
    ...
  ]
}

Możesz też użyć znaku locationBias, aby ograniczyć wyszukiwanie do prostokątnego widocznego obszaru. Poniższy przykład ogranicza żądanie do centrum San Francisco:

  curl -X POST -d '{
    "input": "Amoeba",
    "locationBias": {
      "rectangle": {
        "low": {
          "latitude": 37.7751,
          "longitude": -122.4219
        },
        "high": {
          "latitude": 37.7955,
          "longitude": -122.3937
        }
      }
    }
  }' \
  -H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
  https://places.googleapis.com/v1/places:autocomplete

Chociaż w odpowiedzi pojawiają się wyniki wyszukiwania w prostokątnym obszarze widoku, niektóre z nich znajdują się poza zdefiniowanymi granicami ze względu na odchylenie. Wyniki są też zawarte w tablicy suggestions:

  {
    "suggestions": [
      {
        "placePrediction": {
          "place": "places/ChIJ5YQQf1GHhYARPKG7WLIaOko",
          "placeId": "ChIJ5YQQf1GHhYARPKG7WLIaOko",
          "text": {
            "text": "Amoeba Music, Haight Street, San Francisco, CA, USA",
            "matches": [
              {
                "endOffset": 6
              }
            ]
          },
          "structuredFormat": {
            "mainText": {
              "text": "Amoeba Music",
              "matches": [
                {
                  "endOffset": 6
                }
              ]
            },
            "secondaryText": {
              "text": "Haight Street, San Francisco, CA, USA"
            }
          },
          "types": [
            "point_of_interest",
            "store",
            "establishment"
          ]
        }
      },
      {
        "placePrediction": {
          "place": "places/ChIJr7uwwy58hYARBY-e7-QVwqw",
          "placeId": "ChIJr7uwwy58hYARBY-e7-QVwqw",
          "text": {
            "text": "Amoeba Music, Telegraph Avenue, Berkeley, CA, USA",
            "matches": [
              {
                "endOffset": 6
              }
            ]
          },
          "structuredFormat": {
            "mainText": {
              "text": "Amoeba Music",
              "matches": [
                {
                  "endOffset": 6
                }
              ]
            },
            "secondaryText": {
              "text": "Telegraph Avenue, Berkeley, CA, USA"
            }
          },
          "types": [
            "point_of_interest",
            "store",
            "establishment"
          ]
        }
      },
      {
        "placePrediction": {
          "place": "places/ChIJRdmfADq_woARYaVhnfQSUTI",
          "placeId": "ChIJRdmfADq_woARYaVhnfQSUTI",
          "text": {
            "text": "Amoeba Music, Hollywood Boulevard, Los Angeles, CA, USA",
            "matches": [
              {
                "endOffset": 6
              }
            ]
          },
          "structuredFormat": {
            "mainText": {
              "text": "Amoeba Music",
              "matches": [
                {
                  "endOffset": 6
                }
              ]
            },
            "secondaryText": {
              "text": "Hollywood Boulevard, Los Angeles, CA, USA"
            }
          },
          "types": [
            "point_of_interest",
            "store",
            "establishment"
          ]
        }
      },
    /.../
    ]
  }

Używanie parametru includedPrimaryTypes

Użyj parametru includedPrimaryTypes, aby określić maksymalnie 5 wartości typu z tabeli A, tabeli B lub tylko (regions) albo tylko (cities). Aby miejsce zostało uwzględnione w odpowiedzi, musi pasować do jednej z określonych wartości typu podstawowego.

W tym przykładzie określasz ciąg znaków input „Piłka nożna” i używasz parametru includedPrimaryTypes, aby ograniczyć wyniki do placówek typu "sporting_goods_store":

curl -X POST -d '{
  "input": "Soccer",
  "includedPrimaryTypes": ["sporting_goods_store"],
  "locationBias": {
    "circle": {
      "center": {
        "latitude": 37.7749,
        "longitude": -122.4194
      },
      "radius": 500.0
    }
  }
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
https://places.googleapis.com/v1/places:autocomplete

Jeśli pominiesz parametr includedPrimaryTypes, wyniki mogą zawierać obiekty, których nie chcesz, np. "athletic_field".

Żądanie prognoz zapytań

Domyślnie nie są zwracane prognozy zapytań. Użyj parametru żądania includeQueryPredictions, aby dodać do odpowiedzi prognozy zapytań. Na przykład:

curl -X POST -d '{
  "input": "Amoeba",
  "includeQueryPredictions": true,
  "locationBias": {
    "circle": {
      "center": {
        "latitude": 37.7749,
        "longitude": -122.4194
      },
      "radius": 5000.0
    }
  }
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
https://places.googleapis.com/v1/places:autocomplete

Tablica suggestions zawiera teraz zarówno prognozy miejsc, jak i prognozy zapytań, jak pokazano powyżej w sekcji Informacje o odpowiedzi. Każda prognoza zapytania zawiera pole text z rekomendowanym ciągiem tekstowym wyszukiwania. Możesz wysłać żądanie Wyszukiwanie tekstowe (nowe), aby uzyskać więcej informacji o dowolnej z zwróconych prognoz zapytań.

Uwaga: podpowiedzi zapytań nie są zwracane, gdy ustawiony jest parametr includedRegionCodes.

Użyj punktu początkowego

W tym przykładzie w żądaniu uwzględnij origin jako współrzędne szerokości i długości geograficznej. Jeśli uwzględnisz origin, funkcja Autocomplete (New) umieści w odpowiedzi pole distanceMeters, które zawiera odległość w linii prostej od origin do miejsca docelowego. W tym przykładzie punkt początkowy jest ustawiony na środek San Francisco:

curl -X POST -d '{
  "input": "Amoeba",
  "origin": {
    "latitude": 37.7749,
    "longitude": -122.4194
  },
  "locationRestriction": {
    "circle": {
      "center": {
        "latitude": 37.7749,
        "longitude": -122.4194
      },
      "radius": 5000.0
    }
  }
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
https://places.googleapis.com/v1/places:autocomplete

Odpowiedź zawiera teraz distanceMeters:

{
  "suggestions": [
    {
      "placePrediction": {
        "place": "places/ChIJ5YQQf1GHhYARPKG7WLIaOko",
        "placeId": "ChIJ5YQQf1GHhYARPKG7WLIaOko",
        "text": {
          "text": "Amoeba Music, Haight Street, San Francisco, CA, USA",
          "matches": [
            {
              "endOffset": 6
            }
          ]
        },
        "structuredFormat": {
          "mainText": {
            "text": "Amoeba Music",
            "matches": [
              {
                "endOffset": 6
              }
            ]
          },
          "secondaryText": {
            "text": "Haight Street, San Francisco, CA, USA"
          }
        },
        "types": [
          "home_goods_store",
          "establishment",
          "point_of_interest",
          "store",
          "electronics_store"
        ],
        "distanceMeters": 3012
      }
    }
  ]
}

W odpowiedzi brakuje odległości

W niektórych przypadkach w treści odpowiedzi brakuje parametru distanceMeters, nawet jeśli w żądaniu znajduje się parametr origin. Może się tak zdarzyć w tych sytuacjach:

distanceMeters nie jest uwzględniana w prognozach route.
distanceMeters nie jest uwzględniana, gdy jej wartość wynosi 0, co ma miejsce w przypadku prognoz, które znajdują się w odległości mniejszej niż 1 metr od podanej origin lokalizacji.

Biblioteki klienta, które próbują odczytać pole distanceMeters z przeanalizowanego obiektu, zwrócą pole o wartości 0. Aby nie wprowadzać użytkowników w błąd, nie wyświetlaj im odległości równej zero.

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.

Po prawej stronie strony kliknij ikonę interfejsu API api.
Opcjonalnie edytuj parametry żądania.
Kliknij przycisk Wykonaj. W oknie dialogowym wybierz konto, z którego chcesz wysłać prośbę.
W panelu APIs Explorer kliknij ikonę pełnego ekranu fullscreen, aby rozwinąć okno narzędzia.

Autouzupełnianie (nowość)

Wprowadzenie

Żądania autouzupełniania (nowe)

Obsługiwane parametry

Informacje o odpowiedzi

Wymagane parametry

dane wejściowe

Parametry opcjonalne

FieldMask

includedPrimaryTypes

includePureServiceAreaBusinesses

includeQueryPredictions

includedRegionCodes

inputOffset

languageCode

locationBias lub locationRestriction

locationBias

locationRestriction

pochodzenie

regionCode

sessionToken

Wybieranie parametrów, które mają wpływać na wyniki

Przykłady autouzupełniania (nowa wersja)

Ograniczanie wyszukiwania do obszaru za pomocą parametru locationRestriction

Zawężanie wyszukiwania do obszaru za pomocą parametru locationBias

Używanie parametru includedPrimaryTypes

Żądanie prognoz zapytań

Użyj punktu początkowego

W odpowiedzi brakuje odległości

Wypróbuj