Ta usługa lub funkcja ma stan „Stara”. Więcej informacji o stanie „Stary” znajdziesz w artykule Starsze usługi i funkcje. Aby przejść na interfejs Places API (nowy), przeczytaj przewodnik po migracji.

Autouzupełnianie miejsc (starsza wersja)

Deweloperzy z Europejskiego Obszaru Gospodarczego (EOG)

Uwaga: biblioteki po stronie serwera i po stronie klienta

Interfejs Places API jest też dostępny w klientach Java, Python, Go i Node.js dla usług Map Google. Interfejs Places API i biblioteki klienta są przeznaczone do użytku w aplikacjach serwerowych.

Jeśli tworzysz aplikację po stronie klienta, zapoznaj się z (pakietem) SDK Miejsc na Androida (nowy), (pakietem) SDK Miejsc na iOS (nowy) i biblioteką Miejsc w Maps JavaScript API.

Autouzupełnianie miejsc (starsza wersja) to usługa internetowa, która zwraca prognozy miejsc w odpowiedzi na żądanie HTTP. Żądanie zawiera tekstowy ciąg wyszukiwania i opcjonalne granice geograficzne. Usługa może być używana do udostępniania funkcji autouzupełniania w przypadku wyszukiwań geograficznych opartych na tekście. W miarę wpisywania przez użytkownika tekstu zwraca ona miejsca, takie jak firmy, adresy i punkty orientacyjne.

Żądania Autouzupełniania miejsc (starsza wersja)

Autouzupełnianie miejsc (starsza wersja) jest częścią interfejsu Places API i ma wspólny klucz interfejsu API oraz limity z interfejsem Places API.

Autouzupełnianie miejsc (starsza wersja) może dopasowywać całe słowa i podciągi znaków, rozpoznając nazwy miejsc, adresy i kody Plus Code. Dzięki temu aplikacje mogą wysyłać zapytania w trakcie wpisywania przez użytkownika tekstu, aby na bieżąco podawać prognozy dotyczące miejsc.

Kody plus muszą być prawidłowo sformatowane. Oznacza to, że musisz zastosować kodowanie URL znaku plusa, aby uzyskać %2B, a spacji, aby uzyskać %20.

kod globalny to czteroznakowy numer kierunkowy i sześcioznakowy lub dłuższy kod lokalny. Na przykład globalny kod ucieczki URL 849VCWC8+R9 to 849VCWC8%2BR9.
Kod złożony to 6-znakowy (lub dłuższy) kod lokalny z określoną lokalizacją. Na przykład kod złożony z kodowaniem w formacie adresu URL CWC8+R9 Mountain View, CA, USA to CWC8%2BR9%20Mountain%20View%20CA%20USA.

Zwrócone prognozy są przeznaczone do wyświetlania użytkownikowi, aby ułatwić mu wybór miejsca, które go interesuje. Możesz wysłać prośbę o informacje o miejscu (starsza wersja), aby uzyskać więcej informacji o dowolnym zwróconym miejscu.

Żądanie autouzupełniania miejsc (starsza wersja) to adres URL HTTP w tej postaci:

https://maps.googleapis.com/maps/api/place/autocomplete/output?parameters

gdzie output może mieć jedną z tych wartości:

json (zalecane) oznacza dane wyjściowe w formacie JSON (JavaScript Object Notation).
xml oznacza dane wyjściowe w formacie XML

Aby zainicjować żądanie autouzupełniania miejsc (starsza wersja), wymagane są określone parametry. Zgodnie ze standardem adresów URL wszystkie parametry są rozdzielane znakiem ampersand (&). Listę parametrów i ich możliwych wartości znajdziesz poniżej.

Wymagane parametry

wprowadzanie danych

Ciąg tekstowy, w którym ma zostać przeprowadzone wyszukiwanie. Usługa Autouzupełnianie miejsc zwróci pasujące propozycje na podstawie tego ciągu znaków i uporządkuje wyniki według ich trafności.

Parametry opcjonalne

komponentów,

Grupa miejsc, do których chcesz ograniczyć wyniki. Za pomocą komponentów możesz filtrować dane z maksymalnie 5 krajów. Kraje muszą być przekazywane jako dwuznakowy kod kraju zgodny ze standardem ISO 3166-1 Alpha-2. Przykład: components=country:fr ograniczy wyniki do miejsc we Francji. Wiele krajów musi być przekazywanych jako wiele filtrów country:XX, a separatorem musi być znak |. Przykład: components=country:us|country:pr|country:vi|country:gu|country:mp ograniczy wyniki do miejsc w Stanach Zjednoczonych i ich nieinkorporowanych terytoriach zorganizowanych.

Uwaga: jeśli otrzymasz nieoczekiwane wyniki z kodem kraju, sprawdź, czy używasz kodu, który obejmuje kraje, terytoria zależne i obszary specjalne, które Cię interesują. Informacje o kodach znajdziesz na stronie Wikipedia: List of ISO 3166 country codes lub na platformie ISO Online Browsing Platform.
language

Język, w którym mają być zwracane wyniki.
- Zobacz listę obsługiwanych języków. Google często aktualizuje listę obsługiwanych języków, więc może ona nie być wyczerpująca.
- Jeśli parametr language nie zostanie podany, interfejs API spróbuje użyć preferowanego języka określonego w nagłówku Accept-Language.
- Interfejs API stara się podać adres ulicy, który jest czytelny zarówno dla użytkownika, jak i mieszkańców. Aby to osiągnąć, zwraca adresy w języku lokalnym, a w razie potrzeby transliteruje je na pismo czytelne dla użytkownika, uwzględniając preferowany język. Wszystkie pozostałe adresy są zwracane w preferowanym języku. Wszystkie komponenty adresu są zwracane w tym samym języku, który jest wybierany na podstawie pierwszego komponentu.
- Jeśli nazwa nie jest dostępna w preferowanym języku, interfejs API użyje najbliższego dopasowania.
- Preferowany język ma niewielki wpływ na zestaw wyników, które interfejs API wybiera do zwrócenia, oraz na kolejność, w jakiej są one zwracane. Geokoder interpretuje skróty w różny sposób w zależności od języka, np. skróty typów ulic lub synonimy, które mogą być prawidłowe w jednym języku, ale nie w innym. Na przykład utca i tér to synonimy słowa „ulica” w języku węgierskim.
lokalizacja

Punkt, wokół którego mają być pobierane informacje o miejscu. Musi mieć wartość latitude,longitude. Podczas określania lokalizacji musisz też podać parametr radius. Jeśli nie podano wartości radius, parametr location jest ignorowany.

Jeśli używasz interfejsu API Wyszukaj tekst, parametr „location” może zostać zastąpiony, jeśli parametr „query” zawiera wyraźną lokalizację, np. „Market in Barcelona”.
locationbias

Preferuj wyniki w określonym obszarze, podając promień i współrzędne geograficzne lub 2 pary współrzędnych geograficznych reprezentujące punkty prostokąta. Jeśli ten parametr nie zostanie określony, interfejs API domyślnie używa preferowania adresu IP.
- IP bias: instruuje interfejs API, aby używał odchylenia adresu IP. Przekaż ciąg znaków ipbias (ta opcja nie ma dodatkowych parametrów).
- Okrąg: ciąg znaków określający promień w metrach oraz szerokość i długość geograficzną w stopniach dziesiętnych. Użyj tego formatu: circle:radius@lat,lng.
- Prostokąt: ciąg znaków określający 2 pary współrzędnych geograficznych w stopniach dziesiętnych, reprezentujące punkty południowo-zachodni i północno-wschodni prostokąta. Użyj tego formatu:rectangle:south,west|north,east. Pamiętaj, że wartości wschód/zachód są zawijane do zakresu -180, 180, a wartości północ/południe są ograniczane do zakresu -90, 90.
locationrestriction

Ogranicz wyniki do określonego obszaru, podając promień i współrzędne geograficzne lub 2 pary współrzędnych geograficznych reprezentujące punkty prostokąta.
- Okrąg: ciąg znaków określający promień w metrach oraz szerokość i długość geograficzną w stopniach dziesiętnych. Użyj tego formatu: circle:radius@lat,lng.
- Prostokąt: ciąg znaków określający 2 pary współrzędnych geograficznych w stopniach dziesiętnych, reprezentujące punkty południowo-zachodni i północno-wschodni prostokąta. Użyj tego formatu:rectangle:south,west|north,east. Pamiętaj, że wartości wschód/zachód są zawijane do zakresu -180, 180, a wartości północ/południe są ograniczane do zakresu -90, 90.
odliczyć

Pozycja ostatniego znaku w wyrażeniu wejściowym, którego usługa używa do dopasowywania prognoz. Jeśli na przykład dane wejściowe to Google, a przesunięcie wynosi 3, usługa dopasuje Goo. Ciąg znaków określony przez przesunięcie jest dopasowywany tylko do pierwszego słowa w terminie wejściowym. Jeśli na przykład termin wejściowy to Google abc, a przesunięcie wynosi 3, usługa spróbuje dopasować go do Goo abc. Jeśli nie podasz przesunięcia, usługa użyje całego okresu. Przesunięcie powinno być zwykle ustawione na pozycję kursora tekstowego.
pochodzenie

Punkt początkowy, od którego należy obliczyć odległość w linii prostej do miejsca docelowego (zwracany jako distance_meters). Jeśli ta wartość zostanie pominięta, odległość w linii prostej nie zostanie zwrócona. Musi być określony jako latitude,longitude.
promień

Określa odległość (w metrach), w której mają być zwracane wyniki dotyczące miejsc. Możesz zawęzić wyniki do określonego okręgu, przekazując parametr location i radius. W ten sposób instruujesz usługę Miejsca, aby preferowała wyświetlanie wyników w obrębie tego okręgu. Wyniki spoza zdefiniowanego obszaru mogą być nadal 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 m, dostosowywane dynamicznie na podstawie gęstości obszaru, niezależnie od parametru rankby.
    - Gdy używasz rankby=distance, parametr promienia nie jest akceptowany i powoduje wystąpienie błędu INVALID_REQUEST.
- Autouzupełnianie zapytań: 50 000 metrów
- Wyszukiwanie tekstu: 50 000 metrów
region

Kod regionu 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 znaczącymi 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”).
sessiontoken

Losowy ciąg znaków, który identyfikuje sesję autouzupełniania na potrzeby rozliczeń.

Sesja rozpoczyna się, gdy użytkownik zaczyna wpisywać zapytanie, a kończy, gdy wybierze miejsce i wywoła informacje o miejscu. Każda sesja może zawierać wiele zapytań, po których następuje wybór jednego miejsca. Klucze API używane w każdym żądaniu w ramach sesji muszą należeć do tego samego projektu w konsoli Google Cloud. Po zakończeniu sesji token traci ważność. Aplikacja musi generować nowy token dla każdej sesji. Jeśli parametr sessiontoken zostanie pominięty lub jeśli ponownie użyjesz tokena sesji, sesja zostanie obciążona tak, jakby nie podano tokena sesji (każde żądanie jest rozliczane osobno).

Zalecamy stosowanie tych wytycznych:
- Używaj tokenów sesji we wszystkich sesjach autouzupełniania.
- Generuj nowy token dla każdej sesji. Zalecany jest identyfikator UUID w wersji 4.
- Upewnij się, że klucze interfejsu API używane we wszystkich żądaniach Autouzupełniania miejsc i informacji o miejscu w ramach sesji należą do tego samego projektu w konsoli Cloud.
- Pamiętaj, aby przekazywać unikalny token sesji dla każdej nowej sesji. Używanie tego samego tokena w przypadku więcej niż jednej sesji spowoduje naliczenie opłaty za każde żądanie z osobna.
strictbounds

Zwraca tylko te miejsca, które znajdują się w regionie zdefiniowanym przez parametry location i radius. Jest to ograniczenie, a nie odchylenie, co oznacza, że wyniki spoza tego regionu nie będą zwracane, nawet jeśli pasują do danych wejściowych użytkownika.
typy

Możesz ograniczyć wyniki żądania autouzupełniania miejsc do określonego typu, przekazując parametr types. Ten parametr określa typ lub zbiór typów wymienionych w Typach miejsc. Jeśli nic nie zostanie określone, zwracane są wszystkie typy.

Miejsce może mieć tylko jeden typ podstawowy z typów wymienionych w tabeli 1 lub tabeli 2. Na przykład hotel, w którym serwowane są posiłki, może być zwracany tylko z wartością types=lodging, a nie z wartością types=restaurant.

W przypadku wartości parametru types możesz określić:
- Maksymalnie 5 wartości z tabeli 1 lub tabeli 2. Jeśli jest wiele wartości, rozdziel je znakiem | (pionowa kreska). Na przykład:
  
  types=book_store|cafe
- Dowolny pojedynczy obsługiwany filtr w tabeli 3. Nie można łączyć kolekcji typów.
Uwaga: chociaż geocode i establishment są częścią tabeli 2, nie można ich łączyć z żadnym innym typem w tabelach 1, 2 ani 3 w filtrach żądań autouzupełniania miejsc.

Żądanie zostanie odrzucone z błędem INVALID_REQUEST, jeśli:
- Określono więcej niż 5 typów.
- Występują nierozpoznane typy.
- Dowolne typy z tabeli 1 lub tabeli 2 są mieszane z dowolnymi filtrami z tabeli 3.
Uwaga: parametr types działa tylko w przypadku głównego typu miejsca, a nie wszystkich typów z nim powiązanych. Każde miejsce ma typ podstawowy, ale nie wszystkie typy podstawowe są obsługiwane przez interfejs Places API (nowy). Obsługiwane typy obejmują te wymienione w tabeli 1 lub tabeli 2.

Przykłady autouzupełniania miejsc (starsza wersja)

Zapytanie o lokale zawierające ciąg znaków „Amoeba” w obszarze w centrum San Francisco w Kalifornii:

URL

https://maps.googleapis.com/maps/api/place/autocomplete/json
      ?input=amoeba
      &types=establishment
      &location=37.76999%2C-122.44696
      &radius=500
      &key=YOUR_API_KEY

curl

curl -L -X GET 'https://maps.googleapis.com/maps/api/place/autocomplete/json?input=amoeba&types=establishment&location=37.76999%2C-122.44696&radius=500&key=YOUR_API_KEY'

To samo żądanie, ale ograniczone do wyników w promieniu 500 metrów od skrzyżowania ulic Ashbury St i Haight St w San Francisco:

URL

https://maps.googleapis.com/maps/api/place/autocomplete/json
      ?input=amoeba
      &types=establishment
      &location=37.76999%2C-122.44696&radius=500
      &strictbounds=true
      &key=YOUR_API_KEY

curl

curl -L -X GET 'https://maps.googleapis.com/maps/api/place/autocomplete/json?input=amoeba&types=establishment&location=37.76999%2C-122.44696&radius=500&strictbounds=true&key=YOUR_API_KEY'

Żądanie adresów zawierających „Vict” z wynikami w języku francuskim:

URL

https://maps.googleapis.com/maps/api/place/autocomplete/json
      ?input=Vict
      &types=geocode
      &language=fr
      &key=YOUR_API_KEY

curl

curl -L -X GET 'https://maps.googleapis.com/maps/api/place/autocomplete/json?input=Vict&types=geocode&language=fr&key=YOUR_API_KEY'

Żądanie dotyczące miast zawierających „Vict” z wynikami w języku portugalskim (brazylijskim):

URL

https://maps.googleapis.com/maps/api/place/autocomplete/json
      ?input=Vict
      &types=(cities)
      &language=pt_BR&key=YOUR_API_KEY

curl

curl -L -X GET 'https://maps.googleapis.com/maps/api/place/autocomplete/json?input=Vict&types=(cities)&language=pt_BR&key=YOUR_API_KEY'

Pamiętaj, że w tych przykładach musisz zastąpić klucz interfejsu API swoim kluczem.

Odpowiedź Autouzupełniania miejsc (starsza wersja)

Odpowiedzi usługi Autouzupełnianie miejsc (starsza wersja) są zwracane w formacie wskazanym przez flagę output w ścieżce adresu URL żądania. Poniższe wyniki wskazują, co może zostać zwrócone w przypadku zapytania z tymi parametrami:

URL

https://maps.googleapis.com/maps/api/place/autocomplete/json
      ?input=Paris
      &types=geocode
      &key=YOUR_API_KEY

curl

curl -L -X GET 'https://maps.googleapis.com/maps/api/place/autocomplete/json?input=Paris&types=geocode&key=YOUR_API_KEY'

JSON

{
  "predictions":
    [
      {
        "description": "Paris, France",
        "matched_substrings": [{ "length": 5, "offset": 0 }],
        "place_id": "ChIJD7fiBh9u5kcRYJSMaMOCCwQ",
        "reference": "ChIJD7fiBh9u5kcRYJSMaMOCCwQ",
        "structured_formatting":
          {
            "main_text": "Paris",
            "main_text_matched_substrings": [{ "length": 5, "offset": 0 }],
            "secondary_text": "France",
          },
        "terms":
          [
            { "offset": 0, "value": "Paris" },
            { "offset": 7, "value": "France" },
          ],
        "types": ["locality", "political", "geocode"],
      },
      {
        "description": "Paris, TX, USA",
        "matched_substrings": [{ "length": 5, "offset": 0 }],
        "place_id": "ChIJmysnFgZYSoYRSfPTL2YJuck",
        "reference": "ChIJmysnFgZYSoYRSfPTL2YJuck",
        "structured_formatting":
          {
            "main_text": "Paris",
            "main_text_matched_substrings": [{ "length": 5, "offset": 0 }],
            "secondary_text": "TX, USA",
          },
        "terms":
          [
            { "offset": 0, "value": "Paris" },
            { "offset": 7, "value": "TX" },
            { "offset": 11, "value": "USA" },
          ],
        "types": ["locality", "political", "geocode"],
      },
      {
        "description": "Paris, TN, USA",
        "matched_substrings": [{ "length": 5, "offset": 0 }],
        "place_id": "ChIJ4zHP-Sije4gRBDEsVxunOWg",
        "reference": "ChIJ4zHP-Sije4gRBDEsVxunOWg",
        "structured_formatting":
          {
            "main_text": "Paris",
            "main_text_matched_substrings": [{ "length": 5, "offset": 0 }],
            "secondary_text": "TN, USA",
          },
        "terms":
          [
            { "offset": 0, "value": "Paris" },
            { "offset": 7, "value": "TN" },
            { "offset": 11, "value": "USA" },
          ],
        "types": ["locality", "political", "geocode"],
      },
      {
        "description": "Paris, Brant, ON, Canada",
        "matched_substrings": [{ "length": 5, "offset": 0 }],
        "place_id": "ChIJsamfQbVtLIgR-X18G75Hyi0",
        "reference": "ChIJsamfQbVtLIgR-X18G75Hyi0",
        "structured_formatting":
          {
            "main_text": "Paris",
            "main_text_matched_substrings": [{ "length": 5, "offset": 0 }],
            "secondary_text": "Brant, ON, Canada",
          },
        "terms":
          [
            { "offset": 0, "value": "Paris" },
            { "offset": 7, "value": "Brant" },
            { "offset": 14, "value": "ON" },
            { "offset": 18, "value": "Canada" },
          ],
        "types": ["neighborhood", "political", "geocode"],
      },
      {
        "description": "Paris, KY, USA",
        "matched_substrings": [{ "length": 5, "offset": 0 }],
        "place_id": "ChIJsU7_xMfKQ4gReI89RJn0-RQ",
        "reference": "ChIJsU7_xMfKQ4gReI89RJn0-RQ",
        "structured_formatting":
          {
            "main_text": "Paris",
            "main_text_matched_substrings": [{ "length": 5, "offset": 0 }],
            "secondary_text": "KY, USA",
          },
        "terms":
          [
            { "offset": 0, "value": "Paris" },
            { "offset": 7, "value": "KY" },
            { "offset": 11, "value": "USA" },
          ],
        "types": ["locality", "political", "geocode"],
      },
    ],
  "status": "OK",
}

XML

    
<?xml version="1.0" encoding="UTF-8"?>
<AutocompletionResponse>
 <status>OK</status>
 <prediction>
  <description>Paris, France</description>
  <type>locality</type>
  <type>political</type>
  <type>geocode</type>
  <reference>ChIJD7fiBh9u5kcRYJSMaMOCCwQ</reference>
  <term>
   <value>Paris</value>
   <offset>0</offset>
  </term>
  <term>
   <value>France</value>
   <offset>7</offset>
  </term>
  <matched_substring>
   <offset>0</offset>
   <length>5</length>
  </matched_substring>
  <place_id>ChIJD7fiBh9u5kcRYJSMaMOCCwQ</place_id>
  <structured_formatting>
   <description>Paris</description>
   <subdescription>France</subdescription>
   <description_matched_substring>
    <offset>0</offset>
    <length>5</length>
   </description_matched_substring>
  </structured_formatting>
 </prediction>
 <prediction>
  <description>Paris, TX, USA</description>
  <type>locality</type>
  <type>political</type>
  <type>geocode</type>
  <reference>ChIJmysnFgZYSoYRSfPTL2YJuck</reference>
  <term>
   <value>Paris</value>
   <offset>0</offset>
  </term>
  <term>
   <value>TX</value>
   <offset>7</offset>
  </term>
  <term>
   <value>USA</value>
   <offset>11</offset>
  </term>
  <matched_substring>
   <offset>0</offset>
   <length>5</length>
  </matched_substring>
  <place_id>ChIJmysnFgZYSoYRSfPTL2YJuck</place_id>
  <structured_formatting>
   <description>Paris</description>
   <subdescription>TX, USA</subdescription>
   <description_matched_substring>
    <offset>0</offset>
    <length>5</length>
   </description_matched_substring>
  </structured_formatting>
 </prediction>
 <prediction>
  <description>Paris, TN, USA</description>
  <type>locality</type>
  <type>political</type>
  <type>geocode</type>
  <reference>ChIJ4zHP-Sije4gRBDEsVxunOWg</reference>
  <term>
   <value>Paris</value>
   <offset>0</offset>
  </term>
  <term>
   <value>TN</value>
   <offset>7</offset>
  </term>
  <term>
   <value>USA</value>
   <offset>11</offset>
  </term>
  <matched_substring>
   <offset>0</offset>
   <length>5</length>
  </matched_substring>
  <place_id>ChIJ4zHP-Sije4gRBDEsVxunOWg</place_id>
  <structured_formatting>
   <description>Paris</description>
   <subdescription>TN, USA</subdescription>
   <description_matched_substring>
    <offset>0</offset>
    <length>5</length>
   </description_matched_substring>
  </structured_formatting>
 </prediction>
 <prediction>
  <description>Paris, Brant, ON, Canada</description>
  <type>neighborhood</type>
  <type>political</type>
  <type>geocode</type>
  <reference>ChIJsamfQbVtLIgR-X18G75Hyi0</reference>
  <term>
   <value>Paris</value>
   <offset>0</offset>
  </term>
  <term>
   <value>Brant</value>
   <offset>7</offset>
  </term>
  <term>
   <value>ON</value>
   <offset>14</offset>
  </term>
  <term>
   <value>Canada</value>
   <offset>18</offset>
  </term>
  <matched_substring>
   <offset>0</offset>
   <length>5</length>
  </matched_substring>
  <place_id>ChIJsamfQbVtLIgR-X18G75Hyi0</place_id>
  <structured_formatting>
   <description>Paris</description>
   <subdescription>Brant, ON, Canada</subdescription>
   <description_matched_substring>
    <offset>0</offset>
    <length>5</length>
   </description_matched_substring>
  </structured_formatting>
 </prediction>
 <prediction>
  <description>Paris, KY, USA</description>
  <type>locality</type>
  <type>political</type>
  <type>geocode</type>
  <reference>ChIJsU7_xMfKQ4gReI89RJn0-RQ</reference>
  <term>
   <value>Paris</value>
   <offset>0</offset>
  </term>
  <term>
   <value>KY</value>
   <offset>7</offset>
  </term>
  <term>
   <value>USA</value>
   <offset>11</offset>
  </term>
  <matched_substring>
   <offset>0</offset>
   <length>5</length>
  </matched_substring>
  <place_id>ChIJsU7_xMfKQ4gReI89RJn0-RQ</place_id>
  <structured_formatting>
   <description>Paris</description>
   <subdescription>KY, USA</subdescription>
   <description_matched_substring>
    <offset>0</offset>
    <length>5</length>
   </description_matched_substring>
  </structured_formatting>
 </prediction>
</AutocompletionResponse>

PlacesAutocompleteResponse

Pole	Wymagane	Typ	Opis
`predictions`	wymagane	Array<PlaceAutocompletePrediction>	Zawiera tablicę prognoz. Więcej informacji znajdziesz w artykule PlaceAutocompletePrediction.
`status`	wymagane	PlacesAutocompleteStatus	Zawiera stan żądania i może zawierać informacje do debugowania, które pomogą Ci ustalić, dlaczego żądanie nie zostało zrealizowane. Więcej informacji znajdziesz w sekcji PlacesAutocompleteStatus.
`error_message`	opcjonalnie	ciąg znaków	Jeśli usługa zwróci kod stanu inny niż `OK<`, w obiekcie odpowiedzi może się pojawić dodatkowe pole `error_message`. To pole zawiera bardziej szczegółowe informacje o przyczynach podanego kodu stanu. To pole nie zawsze jest zwracane, a jego zawartość może ulec zmianie.
`info_messages`	opcjonalnie	Array<string>	Gdy usługa zwraca dodatkowe informacje o specyfikacji żądania, w obiekcie odpowiedzi może pojawić 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.

Szczególnie interesujące w wynikach są elementy place_id, których można użyć do wysłania osobnego zapytania z prośbą o bardziej szczegółowe informacje o miejscu. Zobacz żądania informacji o miejscu (starsza wersja).

Odpowiedź XML składa się z jednego elementu <AutocompletionResponse> z 2 rodzajami elementów podrzędnych:

Pojedynczy element <status> zawiera metadane dotyczące żądania. Zobacz poniżej kody stanu.
0 lub więcej elementów <prediction>, z których każdy zawiera informacje o jednym miejscu. Więcej informacji o tych wynikach znajdziesz w artykule Wyniki autouzupełniania miejsc (starsza wersja). Interfejs Places API zwraca maksymalnie 5 wyników.

Zalecamy używanie json jako preferowanej flagi wyjściowej, chyba że z jakiegoś powodu aplikacja wymaga xml. Przetwarzanie drzew XML wymaga pewnej ostrożności, aby odwoływać się do odpowiednich węzłów i elementów. Więcej informacji o przetwarzaniu plików XML znajdziesz w artykule Przetwarzanie plików XML za pomocą XPath.

Komponent adresu street_number może nie występować w odpowiedziach Informacji o miejscu (starsza wersja) w przypadku identyfikatorów miejsc w niektórych prognozach autouzupełniania. Zwykle dzieje się tak, gdy nie można interpolować adresu dla miejsca. W takich przypadkach tablica types w prognozie będzie zawierać wartość „route”. W przypadku podpowiedzi autouzupełniania z liczbą w opisie (pasującą do zapytania) odpowiedź interfejsu informacje o miejscu (starsza wersja) dla identyfikatora miejsca zawiera numer ulicy tylko wtedy, gdy tablica types dla podpowiedzi zawiera co najmniej jeden z tych elementów:

street_address
założenie,
instytucja

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łowo sformułowane, zwykle z powodu braku parametru input.
OVER_QUERY_LIMIT – oznacza dowolną z tych czynności:
- Przekroczono limity zapytań na sekundę.
- Na Twoim koncie nie włączono płatności.
- Miesięczny limit środków w wysokości 200 USD lub samodzielnie ustalony limit wykorzystania został przekroczony.
- Podana forma płatności nie jest już ważna (np. karta kredytowa straciła ważność).
Więcej informacji o rozwiązywaniu tego problemu znajdziesz w najczęstszych pytaniach dotyczących Map.
REQUEST_DENIED, z którego wynika, że Twoja prośba została odrzucona, zwykle z tych powodów:
- W żądaniu brakuje klucza interfejsu API.
- Parametr key jest nieprawidłowy.
UNKNOWN_ERROR – wskazuje nieznany błąd.

Gdy usługa Miejsca 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 1 elementu <prediction>.

PlaceAutocompletePrediction

Pole	Wymagane	Typ	Opis
`description`	wymagane	ciąg znaków	Zawiera zrozumiałą dla człowieka nazwę zwróconego wyniku. W przypadku wyników `establishment` jest to zwykle nazwa firmy. Te treści należy odczytywać w takiej formie, w jakiej są wyświetlane. Nie należy programowo analizować sformatowanego adresu.
`matched_substrings`	wymagane	Tablica<PlaceAutocompleteMatchedSubstring>	Lista podłańcuchów opisujących lokalizację wpisanego terminu w tekście wyniku podpowiedzi, dzięki czemu można go wyróżnić, jeśli zostanie wybrany. Więcej informacji znajdziesz w sekcji PlaceAutocompleteMatchedSubstring.
`structured_formatting`	wymagane	PlaceAutocompleteStructuredFormat	Zawiera wstępnie sformatowany tekst, który może być wyświetlany w wynikach autouzupełniania. Te treści należy odczytywać w takiej formie, w jakiej są wyświetlane. Nie należy programowo analizować sformatowanego adresu. Więcej informacji znajdziesz w artykule PlaceAutocompleteStructuredFormat.
`terms`	wymagane	Tablica<PlaceAutocompleteTerm>	Zawiera tablicę terminów identyfikujących poszczególne sekcje zwróconego opisu (sekcja opisu jest zwykle zakończona przecinkiem). Każdy wpis w tablicy ma pole `value` zawierające tekst terminu i pole `offset` określające pozycję początkową tego terminu w opisie, mierzoną w znakach Unicode. Więcej informacji znajdziesz w sekcji PlaceAutocompleteTerm.
`distance_meters`	opcjonalnie	liczba całkowita	Odległość w metrach w linii prostej od punktu początkowego. To pole jest zwracane tylko w przypadku żądań wysłanych za pomocą `origin`.
`place_id`	opcjonalnie	ciąg znaków	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.
`reference`	opcjonalnie	ciąg znaków	`reference` zostało wycofane. Zobacz place_id.
`types`	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
`length`	wymagane	liczba	Długość pasującego podłańcucha w tekście wyniku prognozy.
`offset`	wymagane	liczba	Lokalizacja początkowa pasującego podłańcucha w tekście wyniku prognozy.

PlaceAutocompleteStructuredFormat

Pole	Wymagane	Typ	Opis
`main_text`	wymagane	ciąg znaków	Zawiera główny tekst prognozy, zwykle nazwę miejsca.
`main_text_matched_substrings`	wymagane	Tablica<PlaceAutocompleteMatchedSubstring>	Zawiera tablicę z wartością `offset` i `length`. Opisują one lokalizację wpisanego terminu w tekście wyniku podpowiedzi, dzięki czemu można go wyróżnić, jeśli zostanie wybrany. Więcej informacji znajdziesz w sekcji PlaceAutocompleteMatchedSubstring.
`secondary_text`	opcjonalnie	ciąg znaków	Zawiera tekst dodatkowy podpowiedzi, zwykle lokalizację miejsca.
`secondary_text_matched_substrings`	opcjonalnie	Tablica<PlaceAutocompleteMatchedSubstring>	Zawiera tablicę z wartością `offset` i `length`. Opisują one lokalizację wpisanego terminu w tekście wyniku podpowiedzi, dzięki czemu można go wyróżnić, jeśli zostanie wybrany. Więcej informacji znajdziesz w sekcji PlaceAutocompleteMatchedSubstring.

PlaceAutocompleteTerm

Pole	Wymagane	Typ	Opis
`offset`	wymagane	liczba	Określa pozycję początkową tego terminu w opisie, mierzoną w znakach Unicode.
`value`	wymagane	ciąg znaków	Tekst terminu.

Optymalizacja Autouzupełniania miejsc (starsza wersja)

W tej sekcji opisujemy sprawdzone metody, które pomogą Ci w pełni wykorzystać możliwości usługi Autouzupełnianie miejsc (starsza wersja).

Oto kilka ogólnych wskazówek:

Najszybszym sposobem na stworzenie działającego interfejsu użytkownika jest użycie widżetu autouzupełniania miejsc (starszego) w interfejsie Maps JavaScript API, widżetu autouzupełniania miejsc (starszego) w pakiecie SDK Miejsc na Androida lub elementu sterującego interfejsu autouzupełniania miejsc (starszego) w pakiecie SDK Miejsc na iOS.
Poznaj najważniejsze pola danych Autouzupełniania miejsc (starsza wersja) od samego początku.
Pola dotyczące preferowania lokalizacji i ograniczania lokalizacji są opcjonalne, ale mogą mieć znaczący wpływ na skuteczność autouzupełniania.
Używaj obsługi błędów, aby zapewnić prawidłowe działanie aplikacji, gdy interfejs API zwróci błąd.
Upewnij się, że aplikacja obsługuje sytuacje, w których użytkownik nie dokonał wyboru, i oferuje mu możliwość kontynuowania.

Sprawdzone metody optymalizacji kosztów

Podstawowa optymalizacja kosztów

Aby zoptymalizować koszt korzystania z usługi autouzupełniania miejsc (starszej wersji), używaj masek pól w widżetach informacji o miejscu (starszej wersji) i autouzupełniania miejsc (starszej wersji), aby zwracać tylko potrzebne pola danych autouzupełniania miejsc (starszej wersji).

Zaawansowana optymalizacja kosztów

Rozważ programowe wdrożenie usługi Autouzupełnianie miejsc (starszej wersji), aby uzyskać dostęp do SKU: Autouzupełnianie – cena za żądanie i zamiast informacji o miejscu (starszej wersji) wysyłać żądania wyników interfejsu Geocoding API dotyczących wybranego miejsca. Cena za żądanie w połączeniu z interfejsem Geocoding API jest bardziej opłacalna niż cena za sesję (oparta na sesjach), jeśli spełnione są oba te warunki:

Jeśli potrzebujesz tylko szerokości i długości geograficznej lub adresu wybranego miejsca, interfejs Geocoding API dostarczy te informacje za niższą cenę niż wywołanie interfejsu informacje o miejscu (Legacy).
Jeśli użytkownicy wybiorą podpowiedź autouzupełniania w ramach średnio 4 lub mniej żądań autouzupełniania miejsc (starsza wersja), cena za żądanie może być bardziej opłacalna niż cena za sesję.

Aby wybrać implementację Autouzupełniania miejsc (starszej wersji), która odpowiada Twoim potrzebom, kliknij kartę z odpowiedzią na to pytanie.

Czy Twoja aplikacja wymaga innych informacji niż adres i szerokość/długość geograficzna wybranej prognozy?

Tak, wymaga więcej szczegółów

Używaj Autouzupełniania miejsc opartego na sesji (starsza wersja) z Informacjami o miejscu (starsza wersja).
Ponieważ Twoja aplikacja wymaga szczegółów miejsca (starsza wersja), takich jak nazwa miejsca, status firmy lub godziny otwarcia, implementacja autouzupełniania miejsc (starsza wersja) powinna używać tokena sesji (programowo lub wbudowanego w widżety JavaScript, Android lub iOS) na sesję oraz odpowiednich SKU danych o miejscach w zależności od tego, o które pola danych o miejscach prosisz.¹

Implementacja widżetu
Zarządzanie sesją jest automatycznie wbudowane w widżety JavaScript, Android lub iOS. Obejmuje to zarówno żądania Autouzupełniania miejsc (starsza wersja), jak i żądania informacji o miejscu (starsza wersja) dotyczące wybranej podpowiedzi. Pamiętaj, aby określić parametr fields, aby mieć pewność, że żądasz tylko potrzebnych pól danych autouzupełniania miejsc (starsza wersja).

Implementacja programowa
Używaj tokena sesji w żądaniach autouzupełniania miejsc (starsza wersja). Podczas wysyłania żądania informacji o miejscu (starszych) dotyczących wybranej podpowiedzi uwzględnij te parametry:

Identyfikator miejsca z odpowiedzi Autouzupełniania miejsc (starszej wersji)
Token sesji użyty w żądaniu Autouzupełniania miejsc (starsza wersja).
Parametr fields określający pola danych autouzupełniania miejsc (starszego)

Nie, wystarczy adres i lokalizacja

W zależności od wydajności korzystania z autouzupełniania miejsc (starsza wersja) interfejs Geocoding API może być bardziej opłacalną opcją niż informacje o miejscu (starsza wersja). Skuteczność każdej aplikacji korzystającej z interfejsu Autouzupełnianie miejsc (Legacy) zależy od tego, co wpisują użytkownicy, gdzie jest używana aplikacja i czy zostały wdrożone sprawdzone metody optymalizacji wydajności.

Aby odpowiedzieć na to pytanie, przeanalizuj, ile znaków użytkownik wpisuje średnio, zanim wybierze prognozę autouzupełniania miejsc (starsza wersja) w Twojej aplikacji.

Czy użytkownicy wybierają prognozę autouzupełniania miejsc (starszego) średnio w 4 lub mniejszej liczbie żądań?

Tak

Zaimplementuj programowo funkcję autouzupełniania miejsc (starszą wersję) bez tokenów sesji i wywołaj interfejs Geocoding API w przypadku wybranego przewidywania miejsca.
Geocoding API dostarcza adresy oraz współrzędne szerokości i długości geograficznej. Wykonanie 4 żądań Autouzupełnianie – na żądanie oraz wywołanie interfejsu Geocoding API dotyczące wybranej podpowiedzi miejsca jest tańsze niż koszt sesji Autouzupełniania miejsc (starsza wersja) na sesję.¹

Rozważ zastosowanie sprawdzonych metod zwiększania wydajności, aby użytkownicy mogli uzyskać prognozę, której szukają, przy użyciu jeszcze mniejszej liczby znaków.

Nie

Używaj Autouzupełniania miejsc opartego na sesji (starsza wersja) z Informacjami o miejscu (starsza wersja).
Średnia liczba żądań, które prawdopodobnie wyślesz, zanim użytkownik wybierze podpowiedź autouzupełniania miejsc (starsza wersja), przekracza koszt cen za sesję, więc w implementacji autouzupełniania miejsc (starsza wersja) należy używać tokena sesji zarówno w przypadku żądań autouzupełniania miejsc (starsza wersja), jak i powiązanych żądań informacji o miejscu (starsza wersja) za sesję. ¹

Implementacja widżetu
Zarządzanie sesją jest automatycznie wbudowane w widżety JavaScript, Android i iOS. Obejmuje to zarówno żądania Autouzupełniania miejsc (starsza wersja), jak i żądania informacji o miejscu (starsza wersja) dotyczące wybranej podpowiedzi. Pamiętaj, aby określić parametr fields, aby mieć pewność, że żądasz tylko potrzebnych pól.

Implementacja programowa
Używaj tokena sesji w żądaniach autouzupełniania miejsc (starsza wersja). Gdy wysyłasz żądanie informacji o miejscu (starsza wersja) dotyczących wybranej podpowiedzi, uwzględnij te parametry:

Identyfikator miejsca z odpowiedzi Autouzupełniania miejsc (starszej wersji)
Token sesji użyty w żądaniu autouzupełniania miejsc (starsza wersja).
Parametr fields określający pola danych podstawowych, takie jak adres i geometria.

Rozważ opóźnienie żądań autouzupełniania miejsc (starsza wersja)
Możesz zastosować strategie, takie jak opóźnienie żądania autouzupełniania miejsc (starsza wersja), dopóki użytkownik nie wpisze pierwszych 3–4 znaków, aby aplikacja wysyłała mniej żądań. Jeśli na przykład wysyłasz żądania do interfejsu API autouzupełniania miejsc (starszej wersji) dla każdego znaku po wpisaniu przez użytkownika trzeciego znaku, a użytkownik wpisze 7 znaków, a potem wybierze podpowiedź, dla której wysyłasz 1 żądanie do interfejsu Geocoding API, łączny koszt wyniesie 4 żądania do interfejsu API autouzupełniania miejsc (starszej wersji) + geokodowanie.¹

Jeśli opóźnienie żądań może spowodować, że średnia liczba żądań zautomatyzowanych będzie mniejsza niż 4, możesz postępować zgodnie z instrukcjami dotyczącymi implementacji wydajnego interfejsu Autouzupełnianie miejsc (starszego) z interfejsem Geocoding API. Pamiętaj, że opóźnianie żądań może być postrzegane przez użytkownika jako opóźnienie, ponieważ może on oczekiwać, że podpowiedzi będą wyświetlane po każdym naciśnięciu klawisza.

Aby użytkownicy mogli uzyskać prognozę, której szukają, przy użyciu mniejszej liczby znaków, rozważ zastosowanie sprawdzonych metod dotyczących wydajności.

Ceny znajdziesz w cennikach Google Maps Platform.

Sprawdzone metody dotyczące wydajności

Poniższe wytyczne opisują sposoby optymalizacji skuteczności autouzupełniania miejsc (starsza wersja):

Dodaj do implementacji funkcji Autouzupełnianie miejsc (starsza wersja) ograniczenia związane z krajem, ustawianie preferencji lokalizacji i (w przypadku implementacji programowych) preferencje językowe. W przypadku widżetów nie trzeba określać preferencji językowych, ponieważ są one pobierane z przeglądarki lub urządzenia mobilnego użytkownika.
Jeśli usługa autouzupełniania miejsc (starsza wersja) jest używana z mapą, możesz określić lokalizację na podstawie widocznego obszaru mapy.
W sytuacjach, gdy użytkownik nie wybierze żadnej z podpowiedzi Autouzupełniania miejsc (starsza wersja), zwykle dlatego, że żadna z nich nie jest adresem, którego szuka, możesz ponownie użyć pierwotnych danych wejściowych użytkownika, aby uzyskać trafniejsze wyniki:
- Jeśli oczekujesz, że użytkownik poda tylko informacje o adresie, użyj ponownie pierwotnych danych wejściowych użytkownika w wywołaniu interfejsu Geocoding API.
- Jeśli oczekujesz, że użytkownik będzie wpisywać zapytania dotyczące konkretnego miejsca według nazwy lub adresu, użyj żądania informacje o miejscu (starsza wersja). Jeśli wyniki mają być wyświetlane tylko w określonym regionie, użyj promowania lokalizacji.
Inne scenariusze, w których warto wrócić do Geocoding API:
- użytkownicy wpisujący adresy podrzędne, np. adresy konkretnych lokali lub mieszkań w budynku; Na przykład czeski adres „Stroupežnického 3191/17, Praha” daje częściową podpowiedź w usłudze Autouzupełnianie miejsc (starsza wersja).
- Użytkownicy wpisujący adresy z prefiksami odcinków dróg, np. „23–30 29th St, Queens” w Nowym Jorku lub „47–380 Kamehameha Hwy, Kaneohe” na wyspie Kauai na Hawajach.

Preferowanie lokalizacji

Aby zawęzić wyniki do określonego obszaru, przekaż parametr location i parametr radius. Ta opcja nakazuje usłudze Autouzupełnianie miejsc (starsza wersja) preferować wyświetlanie wyników w określonym obszarze. Wyniki spoza zdefiniowanego obszaru mogą być nadal wyświetlane. Możesz użyć parametru includedRegionCodes, aby filtrować wyniki i wyświetlać tylko miejsca w określonym kraju.

Ostrzeżenie: jeśli nie podasz wartości radius, parametr location zostanie zignorowany.

Wyniki dotyczące placówek zwykle nie mają wystarczająco wysokiej pozycji, aby wyświetlać się w wynikach, gdy obszar wyszukiwania jest duży. Jeśli chcesz, aby w wynikach mieszanych (zawierających zarówno miejsca, jak i kody geograficzne) pojawiały się firmy, możesz określić mniejszy promień. Możesz też użyć types=establishment, aby ograniczyć wyniki tylko do placówek.

Ograniczanie lokalizacji

Ogranicz wyniki do określonego obszaru, przekazując parametr locationRestriction.

Możesz też ograniczyć wyniki do regionu zdefiniowanego przez parametr location i parametr radius, dodając parametr strictbounds. Instruuje to interfejs Autouzupełnianie miejsc (starszy), aby zwracał tylko wyniki w tym regionie.

Autouzupełnianie miejsc (starsza wersja) Zadbaj o dobrą organizację dzięki kolekcji Zapisuj i kategoryzuj treści zgodnie ze swoimi preferencjami.

Żądania Autouzupełniania miejsc (starsza wersja)

Wymagane parametry

wprowadzanie danych

Parametry opcjonalne

komponentów,

language

lokalizacja

locationbias

locationrestriction

odliczyć

pochodzenie

promień

region

sessiontoken

strictbounds

typy

Przykłady autouzupełniania miejsc (starsza wersja)

URL

curl

URL

curl

URL

curl

URL

curl

Odpowiedź Autouzupełniania miejsc (starsza wersja)

URL

curl

JSON

XML

PlacesAutocompleteResponse

predictions

status

error_message

info_messages

PlacesAutocompleteStatus

PlaceAutocompletePrediction

description

matched_substrings

structured_formatting

terms

distance_meters

place_id

reference

types

PlaceAutocompleteMatchedSubstring

length

offset

PlaceAutocompleteStructuredFormat

main_text

main_text_matched_substrings

secondary_text

secondary_text_matched_substrings

PlaceAutocompleteTerm

offset

value

Optymalizacja Autouzupełniania miejsc (starsza wersja)

Sprawdzone metody optymalizacji kosztów

Podstawowa optymalizacja kosztów

Zaawansowana optymalizacja kosztów

Tak, wymaga więcej szczegółów

Nie, wystarczy adres i lokalizacja

Tak

Nie

Sprawdzone metody dotyczące wydajności

Preferowanie lokalizacji

Ograniczanie lokalizacji

Autouzupełnianie miejsc (starsza wersja)

`predictions`

`status`

`error_message`

`info_messages`

`description`

`matched_substrings`

`structured_formatting`

`terms`

`distance_meters`

`place_id`

`reference`

`types`

`length`

`offset`

`main_text`

`main_text_matched_substrings`

`secondary_text`

`secondary_text_matched_substrings`

`offset`

`value`