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.

Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

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 Places SDK na Androida (nowy), Places SDK 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 tekstu przez użytkownika zwraca ona miejsca takie jak firmy, adresy i ciekawe miejsca.

Żą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, rozwiązują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 wyświetlać 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 zakodowany na potrzeby 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 tym formacie:

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

Ciąg tekstowy, w którym ma zostać przeprowadzone wyszukiwanie. Usługa autouzupełniania miejsc zwróci pasujące kandydatury na podstawie tego ciągu znaków i uporządkuje wyniki według ich postrzeganej 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 otrzymujesz nieoczekiwane wyniki z kodem kraju, sprawdź, czy używasz kodu, który obejmuje kraje, terytoria zależne i obszary specjalne o znaczeniu geograficznym, które Cię interesują. Informacje o kodach znajdziesz na 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ć kompletna.
- 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, w razie potrzeby transliterowane na pismo czytelne dla użytkownika, z uwzględnieniem preferowanego języka. 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. Gdy podajesz lokalizację, 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.
- Odchylenie IP: 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 wykorzysta cały okres. 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 radius 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 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

Ciąg losowych 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 zostanie wysłane wywołanie informacji 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 w przypadku każdej nowej sesji przekazywać unikalny token 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ę ściśle 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)

Żądanie dotyczące placówek zawierających ciąg znaków „Amoeba” na 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 i Haight 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 dotyczące 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 brazylijskiej odmianie języka portugalskiego:

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 z 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 powiodło się. 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 danego 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 się pojawić 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 żądania. Patrz Kody stanu poniżej.
Zero 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.

W przypadku identyfikatorów miejsc w niektórych podpowiedziach autouzupełniania w odpowiedziach interfejsu Informacje o miejscu (starsza wersja) może nie występować street_number. Dzieje się tak zwykle, gdy nie można interpolować adresu dla danego miejsca. W takich przypadkach tablica types w podpowiedzi będzie zawierać wartość „route”. W przypadku podpowiedzi autouzupełniania z liczbą w opisie (dopasowanie do zapytania wejściowego) odpowiedź interfejsu Informacje o miejscu (starsza wersja) dla identyfikatora miejsca zawiera numer ulicy tylko wtedy, gdy tablica types w 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 sytuacji:
- Przekroczono limity zapytań.
- Na Twoim koncie nie włączono płatności.
- Przekroczono miesięczne środki w wysokości 200 USD lub samodzielnie ustalony 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 problemu znajdziesz w najczęstszych pytaniach dotyczących Map.
REQUEST_DENIED informujący o odrzuceniu Twojej prośby, zwykle z tych powodów:
- W żądaniu brakuje klucza interfejsu API.
- Parametr key jest nieprawidłowy.
UNKNOWN_ERROR – 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 0 lub większej liczby elementów <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 mają być odczytywane w takiej formie, w jakiej są wyświetlane. Nie analizuj sformatowanego adresu za pomocą oprogramowania.
`matched_substrings`	wymagane	Tablica<PlaceAutocompleteMatchedSubstring>	Lista podciągów opisujących lokalizację wpisanego terminu w tekście wyniku prognozy, dzięki czemu termin można 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 mają być odczytywane w takiej formie, w jakiej są wyświetlane. Nie analizuj sformatowanego adresu za pomocą oprogramowania. 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 (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 podciągu w tekście wyniku prognozy.
`offset`	wymagane	liczba	Lokalizacja początkowa pasującego podciągu 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 prognozy, dzięki czemu można go podświetlić, jeśli zostanie wybrany. Więcej informacji znajdziesz w sekcji PlaceAutocompleteMatchedSubstring.
`secondary_text`	opcjonalnie	ciąg znaków	Zawiera tekst dodatkowy prognozy, 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 prognozy, dzięki czemu można go podświetlić, 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łniania 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 miejsca (starszego) w Maps JavaScript API, widżetu autouzupełniania miejsca (starszego) w pakiecie SDK Miejsc na Androida lub elementu sterującego interfejsu autouzupełniania miejsca (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 zapewnia 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ż wdrożenie automatyzacji funkcji Autouzupełniania miejsc (starszej wersji), aby uzyskać dostęp do SKU: Autocomplete – cena za żądanie i wysyłać żądania wyników interfejsu Geocoding API dotyczące wybranego miejsca zamiast informacji o miejscu (starszej wersji). Cena za żądanie w połączeniu z interfejsem Geocoding API jest bardziej opłacalna niż cena za sesję (oparta na sesji), 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 Place Details (starszego).
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 uzyskać pomoc w wyborze implementacji Autouzupełniania miejsc (starszej wersji), która odpowiada Twoim potrzebom, wybierz kartę odpowiadającą Twojej odpowiedzi na to pytanie.

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

Tak, potrzebne są bardziej szczegółowe informacje

Używaj autouzupełniania miejsc opartego na sesji (starszego) z informacjami o miejscu (starszymi).
Ponieważ Twoja aplikacja wymaga informacji o miejscu (starszych), takich jak nazwa miejsca, status firmy lub godziny otwarcia, implementacja autouzupełniania miejsc (starszego) powinna używać tokena sesji programowo lub wbudowanego w widżety JavaScript, Android lub iOS na sesję oraz odpowiednich kodów 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 i iOS. Obejmuje to zarówno żądania Autouzupełniania miejsc (starsza wersja), jak i żądania informacji o miejscu (starsza wersja) dotyczące wybranej prognozy. Pamiętaj, aby określić parametr fields, aby mieć pewność, że żądasz tylko pól danych Autouzupełniania miejsc (starsza wersja), których potrzebujesz.

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 (starsza wersja), które są potrzebne.

Nie, potrzebny jest tylko 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 (starszej wersji) 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 wybranej prognozy miejsca.
Geocoding API dostarcza adresy oraz współrzędne szerokości i długości geograficznej. Wysłanie 4 żądań Autouzupełnianie – na żądanie oraz wywołanie interfejsu Geocoding API dotyczące wybranej podpowiedzi miejsca jest tańsze niż koszt sesji Autouzupełnianie miejsc (starsza wersja) na sesję.¹

Rozważ zastosowanie sprawdzonych metod dotyczących 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 prognozę Autouzupełniania miejsc (starszego), przekracza koszt cen za sesję, więc w implementacji Autouzupełniania miejsc (starszego) należy używać tokena sesji zarówno w przypadku żądań Autouzupełniania miejsc (starszego), jak i powiązanego żądania informacji o miejscu (starszego) 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 (starszego), jak i żądania informacji o miejscu (starszego) dotyczące wybranej podpowiedzi. Pamiętaj, aby określić parametr fields, aby mieć pewność, że żądasz tylko potrzebnych pól.

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óźnienie żądań może być postrzegane przez użytkownika jako opóźnienie, ponieważ może on oczekiwać, że po każdym naciśnięciu klawisza zobaczy podpowiedzi.

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 (starszej wersji) ograniczenia związane z krajem, ustawienia lokalizacji i (w przypadku implementacji programowych) preferencje językowe. Preferencje językowe nie są potrzebne w przypadku widżetów, ponieważ pobierają one preferencje językowe 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 ustawień 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 wartość informuje usługę Autouzupełnianie miejsc (starsza wersja), że ma 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 obiekty pojawiały się w wynikach mieszanych (obiekty i kody geograficzne), 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 radius, dodając parametr strictbounds. To polecenie powoduje, że Autouzupełnianie miejsc (starsza wersja) zwraca tylko wyniki z tego regionu.

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

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, potrzebne są bardziej szczegółowe informacje

Nie, potrzebny jest tylko 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`