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

Autouzupełnianie (nowość)

Wybierz platformę: Android iOS JavaScript Usługa internetowa

Usługa autouzupełniania (nowa) to usługa internetowa, która w odpowiedzi na żądanie HTTP zwraca prognozy miejsc i zapytań. W żądaniu określ wyszukiwany tekst i granice geograficzne, które sterują obszarem wyszukiwania.

Usługa autouzupełniania (nowa) może uwzględniać pełne słowa i podłańcuchy danych wejściowych oraz rozpoznawać nazwy miejsc, adresy i kody plus. Aplikacje mogą więc wysyłać zapytania w trakcie wpisywania zapytań przez użytkownika, aby na bieżąco zapewniać prognozy dotyczące miejsc i zapytań.

Odpowiedź z nowego interfejsu API autouzupełniania może zawierać 2 typy podpowiedzi:

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

Na przykład wywołasz interfejs API, używając jako danych wejściowych ciągu zawierającego częściowe dane wejściowe użytkownika: „Sycylijski piz” z obszarem wyszukiwania ograniczonym do San Francisco w stanie Kalifornia. Odpowiedź zawiera wtedy listę przewidywanych miejsc, które pasują do ciągu wyszukiwania i obszaru wyszukiwania, np. restauracji o nazwie „Sycylijska pizza gastronomiczna”, a także szczegółowe informacje o danym miejscu.

Zwracane prognozy dotyczące miejsc mają zostać przedstawione użytkownikowi, aby pomóc mu w wyborze odpowiedniego miejsca. Możesz wysłać żądanie Szczegóły miejsca (nowe), aby uzyskać więcej informacji o dowolnych zwróconych prognozach dotyczących miejsc.

Odpowiedź może też zawierać listę podpowiedzi zapytania, które pasują do ciągu wyszukiwania i obszaru wyszukiwania, na przykład „Sycylijska pizza i makarony”. Każda prognoza zapytania w odpowiedzi zawiera pole text z zalecanym ciągiem wyszukiwania. Wpisz ten ciąg znaków jako dane wejściowe funkcji Wyszukiwanie tekstowe (nowe), aby przeprowadzić bardziej szczegółowe wyszukiwanie.

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

Wypróbuj

Żądania autouzupełniania (nowe)

Nowe (nowe) żądanie autouzupełniania to żądanie HTTP POST wysyłane do adresu URL w postaci:

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

Przekazuj 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

Informacje o odpowiedzi

Autouzupełnianie (nowe) zwraca w odpowiedzi obiekt JSON. W odpowiedzi:

Tablica suggestions zawiera wszystkie prognozowane miejsca i zapytania uporządkowane według ich postrzeganej trafności. Każde miejsce jest reprezentowane przez pole placePrediction, a każde zapytanie jest reprezentowane przez pole queryPrediction.
Pole placePrediction zawiera szczegółowe informacje o prognozie dotyczącej pojedynczego miejsca, w tym identyfikator miejsca i opis tekstowy.
Pole queryPrediction zawiera szczegółowe informacje o prognozie pojedynczego zapytania.

Uwaga: autouzupełnianie (nowe) zwraca 5 podpowiedzi: placePredictions, queryPredictions lub ich kombinację, w zależności od żądania. Jeśli na przykład żądanie nie ma ustawionego atrybutu includeQueryPredictions, treść odpowiedzi zawiera do 5 elementów placePredictions. Jeśli żądanie ustawia includeQueryPredictions, treść odpowiedzi zawiera maksymalnie 5 prognoz w kombinacji placePredictions i queryPredictions.

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

{
  "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, który ma być przeszukiwany. Określ pełne słowa i podłańcuchy, nazwy miejsc, adresy i kody plus. Usługa autouzupełniania (nowa) zwraca dopasowania kandydatów na podstawie tego ciągu znaków i porządkuje wyniki na podstawie ich postrzeganej trafności.

Parametry opcjonalne

includedPrimaryTypes

Miejsce może mieć tylko jeden typ podstawowy spośród typów wymienionych w tabeli A lub tabeli B. Typem głównym może być np. "mexican_restaurant" lub "steak_house".

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

Za pomocą tego parametru możesz określić maksymalnie 5 wartości typów z tabeli A lub tabeli B. Miejsce musi pasować do jednej z określonych wartości typu podstawowego, aby zostało uwzględnione w odpowiedzi.

Ten parametr może też zawierać wartość (regions) lub (cities). Kolekcja typu (regions) filtruje obszary lub okręgi, np. dzielnice i kody pocztowe. Zbiór typu (cities) filtruje miejsca, które Google identyfikuje jako miasto.

Żądanie zostanie odrzucone z powodu błędu INVALID_REQUEST, jeśli:
- Określono więcej niż 5 typów.
- Oprócz (cities) i (regions) jest określony każdy 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 danym miejscem. Chociaż każde miejsce ma typ główny, nie każdy typ podstawowy jest obsługiwany przez Places API (nowy). Obsługiwane typy obejmują te wymienione w tabeli A lub tabeli B.
includeQueryPredictions

Jeśli parametr ma wartość true, odpowiedź zawiera zarówno prognozy dotyczące miejsc, jak i zapytań. 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 określonej w postaci tablicy zawierającej maksymalnie 15 dwuznakowych wartości ccTLD („domena najwyższego poziomu”). Jeśli go pominiesz, do odpowiedzi nie będą stosowane żadne ograniczenia. Aby na przykład ograniczyć regiony do Niemiec i Francji:
```
    "includedRegionCodes": ["de", "fr"]
```
Jeśli podasz zarówno locationRestriction, jak i includedRegionCodes, wyniki będą znajdować się w obszarze przecięcia tych ustawień.
inputOffset

Przesunięcie znaków Unicode liczone od zera, które wskazuje pozycję kursora w polu input. Pozycja kursora może wpływać na wyświetlane podpowiedzi. Jeśli pole jest puste, domyślna długość to input.

Uwaga: w pierwszej wersji prywatnej usługi testowej ta właściwość nazywała się 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żywany w polu input różni się od wartości określonej w polu languageCode lub jeśli zwrócone miejsce nie ma tłumaczenia z języka lokalnego na languageCode.
- Aby określić preferowany język, musisz użyć kodów języka IETF BCP-47.
- Jeśli nie podano languageCode, interfejs API używa wartości podanej w nagłówku Accept-Language. Jeśli nie podasz żadnej z tych wartości, wartość domyślna to en. Jeśli podasz nieprawidłowy kod języka, interfejs API zwróci błąd INVALID_ARGUMENT.
- Preferowany język ma niewielki wpływ na zestaw wyników zwracanych przez interfejs API oraz na kolejność, w jakiej są one zwracane. Dotyczy to również możliwości poprawiania błędów pisowni przez interfejs API.
- Interfejs API stara się dostarczyć adres, który jest czytelny dla użytkownika i populacji lokalnej, i 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.
  - Jako pierwsze są wybierane pasujące hasła w parametrze input – nazwy zgodne z ustawieniami języka wskazanym w parametrze languageCode (jeśli są dostępne). W przeciwnym razie używane są nazwy, które najlepiej pasują do danych wejściowych użytkownika.
  - Adresy są sformatowane w języku lokalnym za pomocą skryptu, który w miarę możliwości jest czytelny dla użytkownika, dopiero po wybraniu pasujących haseł, które pasują do haseł w parametrze input.
  - Pozostałe adresy są zwracane w preferowanym języku po wybraniu pasujących haseł zgodnie z hasłami w parametrze input. Jeśli nazwa nie jest dostępna w preferowanym języku, interfejs API używa najbliższego dopasowania.
Promowanie lokalizacji lub ograniczenie związane z lokalizacją

Aby zdefiniować obszar wyszukiwania, możesz podać locationBias lub locationRestriction, ale nie obie te wartości. Pole locationRestriction określa region, w którym muszą się znajdować wyniki, a locationBias określa region, w którym wyniki muszą znajdować się w pobliżu, ale mogą znajdować się poza tym obszarem.

Uwaga: jeśli pominiesz zarówno locationBias, jak i locationRestriction, interfejs API domyślnie będzie stosować promowanie adresów IP. W przypadku promowania wyników ze względu na adres IP interfejs API używa adresu IP urządzenia.
- locationBias
  
  Określa obszar wyszukiwania. Ta lokalizacja działa jako odchylenie, co oznacza, że mogą być zwracane wyniki dotyczące określonej lokalizacji, w tym wyniki spoza określonego obszaru.
- locationRestriction
  
  Określa obszar wyszukiwania. Wyniki spoza określonego obszaru nie będą zwracane.
Określ obszar locationBias lub locationRestriction w formie prostokątnego widocznego obszaru lub okręgu.
- Okrąg jest wyznaczany 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 ustaw 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 o długości i szerokości geograficznej przedstawiony jako dwa przeciwległe punkty low i dwóch punktów po przekątnej. Widoczny obszar jest uważany za obszar zamknięty, co oznacza, że obejmuje swoją granicę. Granice szerokości geograficznej muszą mieścić się w przedziale od -90 do 90 stopni włącznie, a granice długości geograficznej 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 przecina 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.
  Zarówno pole low, jak i high muszą być wypełnione, a reprezentowane pole nie może być puste. Gdy to zrobisz, pojawi się błąd.
  
  Na przykład ten widoczny obszar 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, z którego oblicza się odległość prostą do miejsca docelowego (zwracany jako distanceMeters). Jeśli ta wartość zostanie pominięta, odległość prosta nie zostanie zwrócona. Wartość należy podać jako szerokość i długość geograficzną:
```
"origin": {
    "latitude": 40.477398,
    "longitude": -74.259087
}
```
regionCode

Kod regionu używany do formatowania odpowiedzi, określony jako dwuznakowa wartość ccTLD („domeny najwyższego poziomu”). Większość kodów ccTLD jest identyczna z kodami ISO 3166-1 z kilkoma wyjątkami. Na przykład domena ccTLD Wielkiej Brytanii to „uk” (.co.uk), a kod ISO 3166-1 to „gb” (technicznie dla podmiotu „Wielka Brytania i Irlandia Północna”).

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

Tokeny sesji to ciągi wygenerowane przez użytkownika, które śledzą nowe (nowe) wywołania autouzupełniania jako „sesje”. Autouzupełnianie (nowość) korzysta z tokenów sesji, aby grupować etapy zapytania i wyboru autouzupełniania wyszukiwania użytkownika w oddzielną sesję na potrzeby rozliczeń. Więcej informacji znajdziesz w artykule o tokenach sesji.

Przykłady autouzupełniania (nowe)

Używanie ograniczeń lokalizacji i uprzedzeń według lokalizacji

Do kontroli obszaru wyszukiwania interfejs API wykorzystuje domyślnie promowanie adresów IP. W przypadku promowania ze względu na adres IP interfejs API używa adresu IP urządzenia, aby wpływać na wyniki. Opcjonalnie do określenia obszaru wyszukiwania możesz użyć właściwości locationRestriction lub locationBias, ale nie obu naraz.

locationRestriction określa obszar do przeszukania. Wyniki spoza określonego obszaru nie są zwracane. W poniższym przykładzie za pomocą polecenia locationRestriction ograniczysz żądanie do okręgu o promieniu 5000 metrów wyśrodkowanym na San Francisco:

curl -X POST -d '{
  "input": "Amoeba",
  "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 są 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": [
          "home_goods_store",
          "establishment",
          "store",
          "point_of_interest",
          "electronics_store"
        ]
      }
    }
  ]
}

W polu locationBias lokalizacja działa jako odchylenie, co oznacza, że mogą być zwracane wyniki dotyczące wskazanej lokalizacji, w tym wyniki spoza określonego obszaru. W następnym przykładzie zmienisz żądanie tak, aby używało locationBias:

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 elementów, 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"
        ]
      }
    },
    ...
  ]
}

Użyj uwzględnionych podstawowych typów

Użyj parametru includedPrimaryTypes, aby określić maksymalnie 5 wartości typów z tabeli A, tabeli B, tylko (regions) lub tylko (cities). Miejsce musi pasować do jednej z określonych wartości typu podstawowego, aby można było uwzględnić je w odpowiedzi.

W poniższym przykładzie określasz ciąg input „Piłka nożna” i użyjesz parametru includedPrimaryTypes, aby ograniczyć wyniki do firm 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ć informacje o niepożądanym typie, np. "athletic_field".

Żądanie prognoz zapytań

Prognozy zapytań nie są domyślnie zwracane. Użyj parametru żądania includeQueryPredictions, aby dodać prognozy zapytania do odpowiedzi. 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 dotyczące miejsc, jak i prognozy zapytań, jak pokazano powyżej w sekcji Informacje o odpowiedzi. Każda prognoza zapytania zawiera pole text zawierające zalecany ciąg znaków wyszukiwania. Możesz wysłać żądanie Wyszukiwanie tekstowe (nowe), aby uzyskać więcej informacji o dowolnym ze zwróconych prognoz zapytań.

Uwaga: prognozy zapytań nie są zwracane po ustawieniu parametru includedRegionCodes.

Użyj punktu początkowego

W tym przykładzie uwzględnij w żądaniu parametr origin jako szerokość i długość geograficzną. Jeśli dodasz parametr origin, interfejs API uwzględni w odpowiedzi pole distanceMeters, które zawiera prostą odległość od miejsca docelowego (origin) do miejsca docelowego. W tym przykładzie punkt początkowy jest ustawiony na centrum 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
      }
    }
  ]
}

Wypróbuj

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

Wybierz ikonę interfejsu API () po prawej stronie.
Opcjonalnie rozwiń sekcję Pokaż parametry standardowe i ustaw parametr fields na maskę pola.
Opcjonalnie edytuj Treść żądania.
Kliknij przycisk Wykonaj. W wyskakującym okienku wybierz konto, z którego chcesz przesłać prośbę.
W panelu API Explorer kliknij ikonę rozwijania , aby rozwinąć okno API Explorer.

Autouzupełnianie (nowość)

Żądania autouzupełniania (nowe)

Informacje o odpowiedzi

Wymagane parametry

dane wejściowe

Parametry opcjonalne

includedPrimaryTypes

includeQueryPredictions

includedRegionCodes

inputOffset

languageCode

Promowanie lokalizacji lub ograniczenie związane z lokalizacją

locationBias

locationRestriction

pochodzenie

regionCode

sessionToken

Przykłady autouzupełniania (nowe)

Używanie ograniczeń lokalizacji i uprzedzeń według lokalizacji

Użyj uwzględnionych podstawowych typów

Żądanie prognoz zapytań

Użyj punktu początkowego

Wypróbuj