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 określa tekstowy ciąg wyszukiwania i opcjonalne granice geograficzne. Usługa może służyć do udostępniania funkcji autouzupełniania w przypadku tekstowych wyszukiwań geograficznych, zwracając miejsca takie jak firmy, adresy i ciekawe miejsca podczas wpisywania znaków przez użytkownika.

Żądania autouzupełniania miejsc (starsza wersja)

Autouzupełnianie miejsc (starsza wersja) jest częścią interfejsu Places API i udostępnia klucz interfejsu API oraz limity interfejsowi Places API.

Autouzupełnianie miejsc (starsza wersja) może dopasowywać pełne słowa i podłańcuchy, rozpoznając nazwy miejsc, adresy i plus codes. Dzięki temu aplikacje mogą wysyłać zapytania, gdy użytkownik wpisuje tekst, 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 4-znakowy numer kierunkowy i 6-znakowy lub dłuższy kod lokalny. Na przykład globalny kod URL-escape 849VCWC8+R9 to 849VCWC8%2BR9.
• kod złożony to 6-znakowy (lub dłuższy) kod lokalny z wyraźnie określoną lokalizacją. Na przykład zakodowany adres URL kodu złożonego CWC8+R9 Mountain View, CA, USA to CWC8%2BR9%20Mountain%20View%20CA%20USA.

Zwrócone prognozy są przeznaczone do wyświetlania użytkownikowi, aby pomóc mu w wybraniu miejsca, które go interesuje. Możesz wysłać żądanie informacji o miejscu (starsza wersja), aby uzyskać więcej informacji o zwróconych miejscach.

Żądanie autouzupełniania miejsca (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) wskazuje dane wyjściowe w formacie JavaScript Object Notation (JSON).
• xml oznacza dane wyjściowe w formacie XML

Do zainicjowania żądania autouzupełniania miejsc (starsza wersja) wymagane są określone parametry. Zgodnie ze standardem adresów URL wszystkie parametry są rozdzielone znakiem ampersand (&). Lista parametrów i ich możliwych wartości znajduje się poniżej.

Wymagane parametry

• wprowadzanie

  Ciąg tekstowy, który ma zostać wyszukany. Usługa autouzupełniania miejsc zwróci pasujące propozycje na podstawie tego ciągu znaków i uporządkuje wyniki według ich trafności.

Parametry opcjonalne

• komponenty,

  Grupa miejsc, do których chcesz ograniczyć wyniki. Za pomocą komponentów możesz filtrować dane według 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 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ć wyczerpująca.
  • Jeśli nie podasz parametru language, interfejs API spróbuje użyć preferowanego języka określonego w nagłówku Accept-Language.
  • Interfejs API stara się podać adres ulicy, który jest czytelny zarówno dla użytkownika, jak i miejscowych. 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 zwraca, oraz na kolejność, w jakiej są zwracane. Geokoder interpretuje skróty w różny sposób w zależności od języka, np. skróty typów ulic lub synonimy, które mogą być prawidłowe w jednym języku, ale nie w innym. Na przykład utca i tér to synonimy słowa „ulica” w języku węgierskim.

• lokalizacja

  Punkt, wokół którego mają być pobierane informacje o miejscu. Musi być określony jako latitude,longitude. Jeśli 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żyje preferowania adresu IP.

  • IP bias: instruuje interfejs API, aby używał kierowania na adres IP. Przekaż ciąg tekstowy 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ących punkty południowo-zachodni i północno-wschodni prostokąta. Użyj formatu przedstawionego poniżej: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 szerokość/długość geograficzną lub 2 pary szerokości/długości geograficznej 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ątny: ciąg znaków określający 2 pary współrzędnych geograficznych w stopniach dziesiętnych, reprezentujące południowo-zachodni i północno-wschodni punkt prostokąta. Użyj formatu przedstawionego poniżej:rectangle:south,west|north,east. Pamiętaj, że wartości wschód/zachód są zawijane do zakresu od -180 do 180, a wartości północ/południe są ograniczane do zakresu od -90 do 90.

• przesunięcie,

  Pozycja ostatniego znaku w wyszukiwanym haśle, którego usługa używa do dopasowywania podpowiedzi. Jeśli na przykład dane wejściowe to Google, a przesunięcie wynosi 3, usługa dopasuje Goo. Ciąg znaków określony przez przesunięcie jest dopasowywany tylko do pierwszego słowa w wyszukiwanym haśle. Jeśli np. termin wejściowy to Google abc, a przesunięcie wynosi 3, usługa spróbuje dopasować termin 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 parametry location i radius. W ten sposób instruujesz usługę Miejsca, aby preferowała wyświetlanie wyników w tym 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 metrów, 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 tekstowe: 50 000 m

• region

  Kod regionu podany jako ccTLD („domena najwyższego poziomu”), czyli wartość dwuznakowa. Większość kodów ccTLD jest identyczna z kodami ISO 3166-1, z kilkoma wyjątkami. Na przykład domena ccTLD Wielkiej Brytanii to „uk” (.co.uk), a jej 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 wybiera miejsce i wywoływana jest usługa informacji o miejscu. Każda sesja może zawierać wiele zapytań, po których następuje wybór jednego miejsca. Klucze interfejsu 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 użyjesz ponownie tokena sesji, sesja zostanie obciążona tak, jakby nie podano tokena sesji (każde żądanie jest rozliczane osobno).

  Zalecamy stosowanie tych wskazówek:

  • 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 szczegółów miejsca w ramach sesji należą do tego samego projektu w Konsoli Cloud.
  • Pamiętaj, aby przekazywać unikalny token sesji dla każdej nowej sesji. Użycie tego samego tokena w więcej niż 1 sesji spowoduje, że każde żądanie będzie rozliczane osobno.

• strictbounds

  Zwraca tylko te miejsca, które znajdują się ściśle w regionie określonym przez location i radius. Jest to ograniczenie, a nie preferencja, 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 kolekcję typów wymienionych w typach miejsc. Jeśli nic nie zostanie określone, zwracane są wszystkie typy.

  Miejsce może mieć tylko 1 główny typ spośród typów wymienionych w tabeli 1 lub tabeli 2. Na przykład hotel, w którym serwowane są posiłki, może być zwrócony 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. W przypadku wielu wartości rozdziel każdą z nich 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:

  • Podano 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” w 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 Ashbury St i Haight St 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 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'

Prośba o podanie 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 własnym 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 uzyskania bardziej szczegółowych informacji o miejscu za pomocą osobnego zapytania. Więcej informacji znajdziesz w sekcji Żą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.
• 0 lub więcej elementów <prediction>, z których każdy zawiera informacje o jednym miejscu. Informacje 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 aplikacja z jakiegoś powodu wymaga xml. Przetwarzanie drzew XML wymaga pewnej ostrożności, aby odwoływać się do właściwych 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 przetworzone.
• ZERO_RESULTS, co oznacza, że wyszukiwanie zakończyło się powodzeniem, ale nie zwróciło żadnych wyników. Może się tak zdarzyć, jeśli wyszukiwanie zostało przekazane do granic w odległej lokalizacji.
• INVALID_REQUEST, co oznacza, że żądanie do interfejsu API było nieprawidłowe, zwykle z powodu braku parametru input.
• OVER_QUERY_LIMIT, który zawiera dowolną z tych informacji:
  • Przekroczono limity zapytań na sekundę.
  • Na Twoim koncie nie włączono płatności.
  • 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 utraciła ważność).
  Więcej informacji o tym, jak rozwiązać ten problem, znajdziesz w najczęstszych pytaniach dotyczących Map.
• REQUEST_DENIED z informacją, że Twoja prośba została odrzucona, zwykle z powodu:
  • 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 co najmniej 1 elementu <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 (starszej wersji).

Oto ogólne wskazówki:

• Najszybszym sposobem na stworzenie działającego interfejsu użytkownika jest użycie widżetu autouzupełniania miejsc (starszego) w 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 Autouzupełniania miejsc (starsza wersja), aby uzyskać dostęp do SKU: Autouzupełnianie – cena za żądanie i poprosić o wyniki interfejsu Geocoding API dotyczące wybranego miejsca zamiast informacji o miejscu (starsza wersja). Ceny za żądanie w połączeniu z Geocoding API są bardziej opłacalne niż ceny za sesję, jeśli spełnione są oba te warunki:

• Jeśli potrzebujesz tylko szerokości i długości geograficznej lub adresu wybranego miejsca użytkownika, Geocoding API dostarczy te informacje za niższą cenę niż wywołanie Place Details (Legacy).
• Jeśli użytkownicy wybiorą podpowiedź autouzupełniania w ramach średnio 4 lub mniej żądań podpowiedzi 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

W poniższych wytycznych opisano sposoby optymalizacji skuteczności usługi Autouzupełnianie miejsc (starsza wersja):

• Dodaj do implementacji funkcji Autouzupełnianie miejsc (starsza wersja) ograniczenia związane z krajem, sugerowanie lokalizacji i (w przypadku implementacji zautomatyzowanych) ustawienia języka. 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 autouzupełnianiu miejsc (starsza wersja) towarzyszy mapa, możesz ustawić preferencje lokalizacji według 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 wpisze tylko informacje o adresie, ponownie użyj 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 ustawienia lokalizacji.
  Inne sytuacje, 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” zwraca częściową podpowiedź w Autouzupełnianiu miejsc (starsza wersja).
  • Użytkownicy wpisujący adresy z prefixami odcinków dróg, np. „23–30 29th St, Queens” w Nowym Jorku lub „47–380 Kamehameha Hwy, Kaneohe” na wyspie Kauai na Hawajach.

Uwzględnianie lokalizacji

Aby zawęzić wyniki do określonego obszaru, przekaż parametr location i parametr radius. Ta instrukcja 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. Za pomocą parametru includedRegionCodes możesz filtrować wyniki, aby 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 określonego przez parametry location i radius, dodając parametr strictbounds. Dzięki temu interfejs Autouzupełnianie miejsc (starsza wersja) będzie zwracać tylko wyniki z tego regionu.