Autouzupełnianie miejsc (starsza wersja)

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.

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

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:

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 -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:

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 -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:

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

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:

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

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:

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

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

{
  "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 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

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.

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

PlaceAutocompleteMatchedSubstring

PlaceAutocompleteStructuredFormat

PlaceAutocompleteTerm

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ę.

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

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.

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.