Zapytanie autouzupełniania (starsza wersja)

Deweloperzy z Europejskiego Obszaru Gospodarczego (EOG)

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łówku Accept-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.

Parametr 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 keyword lub name: 50 000 metrów
    • bez keyword lub name
      • 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łąd INVALID_REQUEST.
  • 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ż OK, w obiekcie odpowiedzi może znajdować się dodatkowe pole error_message. To pole zawiera bardziej szczegółowe informacje o przyczynach danego kodu stanu. To pole nie zawsze jest zwracane, a jego zawartość może ulec zmianie.

opcjonalnie Array<string>

Gdy usługa zwraca dodatkowe informacje o specyfikacji żądania, w obiekcie odpowiedzi może znajdować się dodatkowe pole info_messages. To pole jest zwracane tylko w przypadku żądań zakończonych powodzeniem. Może nie zawsze być zwracany, a jego zawartość może ulec zmianie.

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 parametru input.
  • 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ść).
    Więcej informacji o rozwiązywaniu tego błędu znajdziesz w najczęstszych pytaniach dotyczących Map.
  • REQUEST_DENIED z informacją, że Twoja prośba została odrzucona. Zwykle dzieje się tak, ponieważ:
    • W żądaniu brakuje klucza interfejsu API.
    • Parametr key jest nieprawidłowy.
  • UNKNOWN_ERROR wskazują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 establishment jest to zwykle nazwa firmy. Te treści powinny być odczytywane w takiej postaci, w jakiej są. Nie analizuj sformatowanego adresu automatycznie.

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 value zawierające tekst hasła oraz pole offset określające pozycję początkową tego hasła w opisie, mierzoną w znakach Unicode.

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ą origin.

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: [ "political", "locality" ] lub [ "establishment", "geocode", "beauty_salon" ]. Tablica może zawierać wiele wartości. Dowiedz się więcej o typach miejsc.

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ą offset i length. Opisują one 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.

opcjonalnie tekst

Zawiera tekst dodatkowy podpowiedzi, zwykle lokalizację miejsca.

opcjonalnie Array<PlaceAutocompleteMatchedSubstring>

Zawiera tablicę z wartością offset i length. Opisują one 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.

PlaceAutocompleteTerm

Pole Wymagane Typ Opis
wymagane liczba

Definiuje pozycję początkową tego terminu w opisie, mierzoną w znakach Unicode.

wymagane tekst

Tekst hasła.