Funkcja autouzupełniania zapytania (starsza wersja) może służyć do podpowiadania zapytań w przypadku wyszukiwania geograficznego na podstawie tekstu, zwracając sugerowane zapytania podczas wpisywania.
Żądania autouzupełniania zapytania (starsza wersja)
Autouzupełnianie zapytania (starsza wersja) jest częścią interfejsu Places API (starsza wersja) i udostępnia mu klucz interfejsu API oraz limit.
Funkcja autouzupełniania zapytania (starsza wersja) umożliwia dodawanie do aplikacji podpowiedzi zapytań geograficznych na bieżąco. Zamiast wyszukiwać konkretną lokalizację, użytkownik może wpisać wyszukiwanie kategorialne, np. „pizza w pobliżu Nowego Jorku”, a usługa odpowie listą sugerowanych zapytań pasujących do ciągu znaków. Autouzupełnianie zapytania (starsza wersja) może dopasowywać zarówno całe słowa, jak i podłańcuchy, dlatego aplikacje mogą wysyłać zapytania podczas wpisywania przez użytkownika, aby wyświetlać podpowiedzi na bieżąco.
Żądanie autouzupełniania zapytania (starsza wersja) to adres URL HTTP w tym formacie:
https://maps.googleapis.com/maps/api/place/queryautocomplete/output?parameters
gdzie output może być json lub xml.
Do zainicjowania żądania autouzupełniania zapytania (starsza wersja) wymagane są określone parametry.
Zgodnie ze standardem adresów URL wszystkie parametry są rozdzielone znakiem ampersand (&). Poniżej znajdziesz listę parametrów i ich możliwych wartości.
Wymagane parametry
wprowadzanie danych
Ciąg tekstowy, który ma zostać wyszukany. Usługa autouzupełniania miejsc zwróci dopasowania na podstawie tego ciągu znaków i uporządkuje wyniki według ich trafności.
Parametry opcjonalne
language
Język, w którym mają być zwracane wyniki.
- Zobacz listę obsługiwanych języków. Google często aktualizuje obsługiwane języki, więc ta lista może nie być wyczerpująca.
-
Jeśli nie podasz parametru
language, interfejs API spróbuje użyć preferowanego języka określonego w nagłówkuAccept-Language. - Interfejs API stara się podać adres, który jest czytelny zarówno dla użytkownika, jak i dla mieszkańców. Aby osiągnąć ten cel, zwraca adresy pocztowe w języku lokalnym, w razie potrzeby transliterowane na pismo czytelne dla użytkownika, z uwzględnieniem preferowanego języka. Wszystkie inne 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żywa najbliższego dopasowania.
- Preferowany język ma niewielki wpływ na zestaw wyników, które interfejs API zwraca, oraz na kolejność, w jakiej są 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. Na przykład utca i tér to synonimy słowa „ulica” w języku węgierskim.
lokalizacja
Definiuje punkt jako współrzędne latitude,longitude, wokół którego ma zostać przeprowadzone wyszukiwanie.
Usługa Places używa lokalizacji, aby faworyzować wyniki wyszukiwania w obszarze określonym przez parametry location i radius. Wyniki spoza tego obszaru mogą być nadal wyświetlane.
location może zostać zastąpiony, jeśli query zawiera konkretną lokalizację, np. Market in Barcelona. Użycie cudzysłowów w zapytaniu może też wpłynąć na wagę przypisaną do parametrów location i radius.
offset
Pozycja ostatniego znaku w wyszukiwanym haśle, którego usługa używa do dopasowywania podpowiedzi. Jeśli na przykład dane wejściowe to Google, a przesunięcie wynosi 3, usługa dopasuje Goo. Ciąg określony przez przesunięcie jest dopasowywany tylko do pierwszego słowa w wyszukiwanym haśle. Jeśli na przykład wyszukiwane hasło to Google abc, a przesunięcie wynosi 3, usługa spróbuje dopasować hasło Goo abc. Jeśli nie podasz przesunięcia, usługa użyje całego terminu. Przesunięcie powinno być zwykle ustawione na pozycję kursora tekstowego.
promień
Określa odległość (w metrach), w której mają być zwracane wyniki dotyczące miejsc. Możesz faworyzować wyniki w określonym okręgu, przekazując parametry location i radius.
W ten sposób usługa Miejsca będzie preferować wyświetlanie wyników w obrębie tego okręgu, ale wyniki spoza zdefiniowanego obszaru mogą nadal być wyświetlane.
Promień zostanie automatycznie ograniczony do maksymalnej wartości w zależności od typu wyszukiwania i innych parametrów.
- Autouzupełnianie: 50 000 metrów
-
Wyszukiwanie w pobliżu:
- z
keywordlubname: 50 000 metrów -
bez
keywordlubname-
Do 50 000 metrów, dostosowywane dynamicznie na podstawie gęstości obszaru, niezależnie od parametru
rankby. -
Jeśli używasz parametru
rankby=distance, parametr radius nie będzie akceptowany i spowoduje błądINVALID_REQUEST.
-
Do 50 000 metrów, dostosowywane dynamicznie na podstawie gęstości obszaru, niezależnie od parametru
- z
- Query Autocomplete: 50 000 metrów
- Wyszukiwanie tekstu: 50 000 metrów
Przykłady autouzupełniania zapytań (starsza wersja)
URL
https://maps.googleapis.com/maps/api/place/queryautocomplete/json ?input=pizza%20near%20par &key=YOUR_API_KEY
curl
curl -L -X GET 'https://maps.googleapis.com/maps/api/place/queryautocomplete/json?input=pizza%20near%20par&key=YOUR_API_KEY'Zapytanie „Pizza near Par” z wynikami w języku francuskim:
URL
https://maps.googleapis.com/maps/api/place/queryautocomplete/json ?input=pizza%20near%20par &language=fr &key=YOUR_API_KEY
curl
curl -L -X GET 'https://maps.googleapis.com/maps/api/place/queryautocomplete/json?input=pizza%20near%20par&language=fr&key=YOUR_API_KEY'Pamiętaj, że w tych przykładach musisz zastąpić klucz interfejsu API własnym kluczem.
Odpowiedź z Query Autocomplete (starsza wersja)
Odpowiedzi z funkcji autouzupełniania zapytania (starsza wersja) są zwracane w formacie wskazanym przez parametr output w ścieżce żądania adresu URL. Wyniki poniżej są zwracane w przypadku zapytania z tymi parametrami:
URL
https://maps.googleapis.com/maps/api/place/queryautocomplete/json ?input=pizza%20near%20par &key=YOUR_API_KEY
curl
curl -L -X GET 'https://maps.googleapis.com/maps/api/place/queryautocomplete/json?input=pizza%20near%20par&key=YOUR_API_KEY'JSON
{ "predictions": [ { "description": "pizza near Paris, France", "matched_substrings": [{ "length": 5, "offset": 0 }, { "length": 3, "offset": 11 }], "structured_formatting": { "main_text": "pizza", "main_text_matched_substrings": [{ "length": 5, "offset": 0 }], "secondary_text": "near Paris, France", "secondary_text_matched_substrings": [{ "length": 3, "offset": 5 }], }, "terms": [ { "offset": 0, "value": "pizza" }, { "offset": 6, "value": "near" }, { "offset": 11, "value": "Paris" }, { "offset": 18, "value": "France" }, ], }, { "description": "pizza near Pari Chowk, NRI City, Omega II, Noida, Uttar Pradesh, India", "matched_substrings": [{ "length": 5, "offset": 0 }, { "length": 3, "offset": 11 }], "structured_formatting": { "main_text": "pizza", "main_text_matched_substrings": [{ "length": 5, "offset": 0 }], "secondary_text": "near Pari Chowk, NRI City, Omega II, Noida, Uttar Pradesh, India", "secondary_text_matched_substrings": [{ "length": 3, "offset": 5 }], }, "terms": [ { "offset": 0, "value": "pizza" }, { "offset": 6, "value": "near" }, { "offset": 11, "value": "Pari Chowk" }, { "offset": 23, "value": "NRI City" }, { "offset": 33, "value": "Omega II" }, { "offset": 43, "value": "Noida" }, { "offset": 50, "value": "Uttar Pradesh" }, { "offset": 65, "value": "India" }, ], }, { "description": "pizza near Disneyland Park, Disneyland Drive, Anaheim, CA, USA", "matched_substrings": [{ "length": 5, "offset": 0 }, { "length": 3, "offset": 22 }], "structured_formatting": { "main_text": "pizza", "main_text_matched_substrings": [{ "length": 5, "offset": 0 }], "secondary_text": "near Disneyland Park, Disneyland Drive, Anaheim, CA, USA", "secondary_text_matched_substrings": [{ "length": 3, "offset": 16 }], }, "terms": [ { "offset": 0, "value": "pizza" }, { "offset": 6, "value": "near" }, { "offset": 11, "value": "Disneyland Park" }, { "offset": 28, "value": "Disneyland Drive" }, { "offset": 46, "value": "Anaheim" }, { "offset": 55, "value": "CA" }, { "offset": 59, "value": "USA" }, ], }, { "description": "pizza near Cathédrale Notre-Dame de Paris, Parvis Notre-Dame - place Jean-Paul-II, Paris, France", "matched_substrings": [{ "length": 5, "offset": 0 }, { "length": 3, "offset": 36 }], "structured_formatting": { "main_text": "pizza", "main_text_matched_substrings": [{ "length": 5, "offset": 0 }], "secondary_text": "near Cathédrale Notre-Dame de Paris, Parvis Notre-Dame - place Jean-Paul-II, Paris, France", "secondary_text_matched_substrings": [{ "length": 3, "offset": 30 }], }, "terms": [ { "offset": 0, "value": "pizza" }, { "offset": 6, "value": "near" }, { "offset": 11, "value": "Cathédrale Notre-Dame de Paris" }, { "offset": 43, "value": "Parvis Notre-Dame - place Jean-Paul-II" }, { "offset": 83, "value": "Paris" }, { "offset": 90, "value": "France" }, ], }, { "description": "pizza near Paris Beauvais Airport, Route de l'Aéroport, Tillé, France", "matched_substrings": [{ "length": 5, "offset": 0 }, { "length": 3, "offset": 11 }], "structured_formatting": { "main_text": "pizza", "main_text_matched_substrings": [{ "length": 5, "offset": 0 }], "secondary_text": "near Paris Beauvais Airport, Route de l'Aéroport, Tillé, France", "secondary_text_matched_substrings": [{ "length": 3, "offset": 5 }], }, "terms": [ { "offset": 0, "value": "pizza" }, { "offset": 6, "value": "near" }, { "offset": 11, "value": "Paris Beauvais Airport" }, { "offset": 35, "value": "Route de l'Aéroport" }, { "offset": 56, "value": "Tillé" }, { "offset": 63, "value": "France" }, ], }, ], "status": "OK", }
XML
<AutocompletionResponse> <status>OK</status> <prediction> <description>pizza near Paris, France</description> <term> <value>pizza</value> <offset>0</offset> </term> <term> <value>near</value> <offset>6</offset> </term> <term> <value>Paris</value> <offset>11</offset> </term> <term> <value>France</value> <offset>18</offset> </term> <matched_substring> <offset>0</offset> <length>5</length> </matched_substring> <matched_substring> <offset>11</offset> <length>3</length> </matched_substring> <structured_formatting> <description>pizza</description> <subdescription>near Paris, France</subdescription> <description_matched_substring> <offset>0</offset> <length>5</length> </description_matched_substring> <subdescription_matched_substring> <offset>5</offset> <length>3</length> </subdescription_matched_substring> </structured_formatting> </prediction> <prediction> <description>pizza near Pari Chowk, NRI City, Omega II, Noida, Uttar Pradesh, India</description> <term> <value>pizza</value> <offset>0</offset> </term> <term> <value>near</value> <offset>6</offset> </term> <term> <value>Pari Chowk</value> <offset>11</offset> </term> <term> <value>NRI City</value> <offset>23</offset> </term> <term> <value>Omega II</value> <offset>33</offset> </term> <term> <value>Noida</value> <offset>43</offset> </term> <term> <value>Uttar Pradesh</value> <offset>50</offset> </term> <term> <value>India</value> <offset>65</offset> </term> <matched_substring> <offset>0</offset> <length>5</length> </matched_substring> <matched_substring> <offset>11</offset> <length>3</length> </matched_substring> <structured_formatting> <description>pizza</description> <subdescription>near Pari Chowk, NRI City, Omega II, Noida, Uttar Pradesh, India</subdescription> <description_matched_substring> <offset>0</offset> <length>5</length> </description_matched_substring> <subdescription_matched_substring> <offset>5</offset> <length>3</length> </subdescription_matched_substring> </structured_formatting> </prediction> <prediction> <description>pizza near Disneyland Park, Disneyland Drive, Anaheim, CA, USA</description> <term> <value>pizza</value> <offset>0</offset> </term> <term> <value>near</value> <offset>6</offset> </term> <term> <value>Disneyland Park</value> <offset>11</offset> </term> <term> <value>Disneyland Drive</value> <offset>28</offset> </term> <term> <value>Anaheim</value> <offset>46</offset> </term> <term> <value>CA</value> <offset>55</offset> </term> <term> <value>USA</value> <offset>59</offset> </term> <matched_substring> <offset>0</offset> <length>5</length> </matched_substring> <matched_substring> <offset>22</offset> <length>3</length> </matched_substring> <structured_formatting> <description>pizza</description> <subdescription>near Disneyland Park, Disneyland Drive, Anaheim, CA, USA</subdescription> <description_matched_substring> <offset>0</offset> <length>5</length> </description_matched_substring> <subdescription_matched_substring> <offset>16</offset> <length>3</length> </subdescription_matched_substring> </structured_formatting> </prediction> <prediction> <description>pizza near Cathédrale Notre-Dame de Paris, Parvis Notre-Dame - place Jean-Paul-II, Paris, France</description> <term> <value>pizza</value> <offset>0</offset> </term> <term> <value>near</value> <offset>6</offset> </term> <term> <value>Cathédrale Notre-Dame de Paris</value> <offset>11</offset> </term> <term> <value>Parvis Notre-Dame - place Jean-Paul-II</value> <offset>43</offset> </term> <term> <value>Paris</value> <offset>83</offset> </term> <term> <value>France</value> <offset>90</offset> </term> <matched_substring> <offset>0</offset> <length>5</length> </matched_substring> <matched_substring> <offset>36</offset> <length>3</length> </matched_substring> <structured_formatting> <description>pizza</description> <subdescription>near Cathédrale Notre-Dame de Paris, Parvis Notre-Dame - place Jean-Paul-II, Paris, France</subdescription> <description_matched_substring> <offset>0</offset> <length>5</length> </description_matched_substring> <subdescription_matched_substring> <offset>30</offset> <length>3</length> </subdescription_matched_substring> </structured_formatting> </prediction> <prediction> <description>pizza near Paris Beauvais Airport, Route de l'Aéroport, Tillé, France</description> <term> <value>pizza</value> <offset>0</offset> </term> <term> <value>near</value> <offset>6</offset> </term> <term> <value>Paris Beauvais Airport</value> <offset>11</offset> </term> <term> <value>Route de l'Aéroport</value> <offset>35</offset> </term> <term> <value>Tillé</value> <offset>56</offset> </term> <term> <value>France</value> <offset>63</offset> </term> <matched_substring> <offset>0</offset> <length>5</length> </matched_substring> <matched_substring> <offset>11</offset> <length>3</length> </matched_substring> <structured_formatting> <description>pizza</description> <subdescription>near Paris Beauvais Airport, Route de l'Aéroport, Tillé, France</subdescription> <description_matched_substring> <offset>0</offset> <length>5</length> </description_matched_substring> <subdescription_matched_substring> <offset>5</offset> <length>3</length> </subdescription_matched_substring> </structured_formatting> </prediction> </AutocompletionResponse>
Gdy usługa Places zwraca wyniki wyszukiwania w formacie JSON, umieszcza je w tablicy predictions. Nawet jeśli usługa nie zwróci żadnych wyników (np. gdy location jest zdalny), nadal zwraca pustą tablicę predictions. Odpowiedzi XML składają się z co najmniej 0 elementów <prediction>.
PlacesQueryAutocompleteResponse
| Pole | Wymagane | Typ | Opis |
|---|---|---|---|
|
wymagane | Array<PlaceAutocompletePrediction> |
Zawiera tablicę podpowiedzi. Więcej informacji znajdziesz w artykule na temat PlaceAutocompletePrediction. |
|
wymagane | PlacesAutocompleteStatus |
Zawiera stan żądania i może zawierać informacje na potrzeby debugowania, które pomogą Ci ustalić, dlaczego żądanie się nie powiodło. Więcej informacji znajdziesz w artykule PlacesAutocompleteStatus. |
|
opcjonalnie | tekst |
Gdy usługa zwraca kod stanu inny niż |
|
opcjonalnie | Array<string> |
Gdy usługa zwraca dodatkowe informacje o specyfikacji żądania, w obiekcie odpowiedzi może znajdować się dodatkowe pole |
PlacesAutocompleteStatus
Kody stanu zwracane przez usługę.
OK, co oznacza, że żądanie do interfejsu API zostało zrealizowane.-
ZERO_RESULTS, co oznacza, że wyszukiwanie zakończyło się powodzeniem, ale nie zwróciło żadnych wyników. Może się tak zdarzyć, jeśli wyszukiwanie zostało przekazane do granic w odległej lokalizacji. -
INVALID_REQUEST, co oznacza, że żądanie do interfejsu API było nieprawidłowe, zwykle z powodu braku parametruinput. -
OVER_QUERY_LIMIT, który zawiera dowolną z tych informacji:- Przekroczono limity zapytań na sekundę.
- Na Twoim koncie nie włączono płatności.
- Przekroczono miesięczny limit środków w wysokości 200 USD lub samodzielnie nałożony limit wykorzystania.
- Podana forma płatności nie jest już ważna (np. karta kredytowa straciła ważność).
-
REQUEST_DENIEDz informacją, że Twoja prośba została odrzucona. Zwykle dzieje się tak, ponieważ:- W żądaniu brakuje klucza interfejsu API.
- Parametr
keyjest nieprawidłowy.
UNKNOWN_ERRORwskazujący nieznany błąd.
Gdy usługa Places zwraca wyniki wyszukiwania w formacie JSON, umieszcza je w tablicy predictions. Nawet jeśli usługa nie zwraca żadnych wyników (np. gdy location jest zdalny), nadal zwraca pustą tablicę predictions. Odpowiedzi XML składają się z co najmniej 0 elementów <prediction>.
PlaceAutocompletePrediction
| Pole | Wymagane | Typ | Opis |
|---|---|---|---|
|
wymagane | tekst |
Zawiera zrozumiałą dla człowieka nazwę zwróconego wyniku. W przypadku wyników |
|
wymagane | Array<PlaceAutocompleteMatchedSubstring> |
Lista podłańcuchów, które opisują lokalizację wpisanego hasła w tekście wyniku podpowiedzi, dzięki czemu można je wyróżnić, jeśli jest to konieczne. Więcej informacji znajdziesz w artykule PlaceAutocompleteMatchedSubstring. |
|
wymagane | PlaceAutocompleteStructuredFormat |
Udostępnia wstępnie sformatowany tekst, który może być wyświetlany w wynikach autouzupełniania. Te treści powinny być odczytywane w takiej postaci, w jakiej są. Nie analizuj sformatowanego adresu automatycznie. Więcej informacji znajdziesz w artykule PlaceAutocompleteStructuredFormat. |
|
wymagane | Array<PlaceAutocompleteTerm> |
Zawiera tablicę haseł identyfikujących każdą sekcję zwróconego opisu (sekcja opisu jest zwykle zakończona przecinkiem). Każdy wpis w tablicy ma pole Więcej informacji znajdziesz w artykule PlaceAutocompleteTerm. |
|
opcjonalnie | liczba całkowita |
Odległość w linii prostej w metrach od punktu początkowego. To pole jest zwracane tylko w przypadku żądań wysłanych za pomocą |
|
opcjonalnie | tekst |
Identyfikator tekstowy, który jednoznacznie identyfikuje miejsce. Aby pobrać informacje o miejscu, przekaż ten identyfikator w polu placeId żądania do interfejsu Places API. Więcej informacji o identyfikatorach miejsc znajdziesz w omówieniu identyfikatorów miejsc. |
|
opcjonalnie | tekst |
Zobacz place_id. |
|
opcjonalnie | Array<string> |
Zawiera tablicę typów, które mają zastosowanie do tego miejsca. Na przykład: |
PlaceAutocompleteMatchedSubstring
| Pole | Wymagane | Typ | Opis |
|---|---|---|---|
|
wymagane | liczba |
Długość dopasowanego podłańcucha w tekście wyniku prognozy. |
|
wymagane | liczba |
Lokalizacja początkowa dopasowanego podłańcucha w tekście wyniku prognozy. |
PlaceAutocompleteStructuredFormat
| Pole | Wymagane | Typ | Opis |
|---|---|---|---|
|
wymagane | tekst |
Zawiera główny tekst podpowiedzi, zwykle nazwę miejsca. |
|
wymagane | Array<PlaceAutocompleteMatchedSubstring> |
Zawiera tablicę z wartością Więcej informacji znajdziesz w artykule PlaceAutocompleteMatchedSubstring. |
|
opcjonalnie | tekst |
Zawiera tekst dodatkowy podpowiedzi, zwykle lokalizację miejsca. |
|
opcjonalnie | Array<PlaceAutocompleteMatchedSubstring> |
Zawiera tablicę z wartością Więcej informacji znajdziesz w artykule PlaceAutocompleteMatchedSubstring. |
PlaceAutocompleteTerm
| Pole | Wymagane | Typ | Opis |
|---|---|---|---|
|
wymagane | liczba |
Definiuje pozycję początkową tego terminu w opisie, mierzoną w znakach Unicode. |
|
wymagane | tekst |
Tekst hasła. |