Autouzupełnianie (nowość)

Wprowadzenie

Autouzupełnianie (nowe) to usługa internetowa, która w odpowiedzi na żądanie HTTP zwraca prognozy miejsc i prognozy zapytań. W żądaniu podaj ciąg tekstowy wyszukiwania i granice geograficzne, które określają obszar wyszukiwania.

Autouzupełnianie (nowe) może dopasowywać całe słowa i podciągi wejściowe, rozwiązując nazwy miejsc, adresy i kody plus. Dzięki temu aplikacje mogą wysyłać zapytania w trakcie wpisywania przez użytkownika tekstu, aby na bieżąco podawać prognozy dotyczące miejsc i zapytań.

Odpowiedź z interfejsu Autocomplete (New) może zawierać 2 rodzaje prognoz:

• Prognozy dotyczące miejsc: miejsca, takie jak firmy, adresy i ciekawe miejsca, na podstawie określonego ciągu tekstowego i obszaru wyszukiwania. Prognozy miejsc są domyślnie zwracane.
• Prognozy zapytań: ciągi zapytań pasujące do ciągu tekstu wejściowego i obszaru wyszukiwania. Domyślnie nie są zwracane prognozy zapytań. Użyj parametru żądania includeQueryPredictions, aby dodać do odpowiedzi prognozy zapytań.

Na przykład wywołujesz autouzupełnianie (nowe), używając jako danych wejściowych ciągu znaków zawierającego częściowe dane wejściowe użytkownika „Sicilian piz” z obszarem wyszukiwania ograniczonym do San Francisco w Kalifornii. Odpowiedź zawiera listę prognoz dotyczących miejsc, które pasują do ciągu wyszukiwania i obszaru wyszukiwania, np. restauracji o nazwie „Sicilian Pizza Kitchen”, wraz ze szczegółowymi informacjami o tym miejscu.

Zwrócone prognozy miejsc są przeznaczone do wyświetlania użytkownikowi, aby ułatwić mu wybór zamierzonego miejsca. Możesz wysłać żądanie Szczegóły miejsca (nowe), aby uzyskać więcej informacji o dowolnej z zwróconych prognoz miejsc.

Odpowiedź może też zawierać listę podpowiedzi do zapytania, które pasują do ciągu wyszukiwania i obszaru wyszukiwania, np. „Sicilian Pizza & Pasta”. Każda prognoza zapytania w odpowiedzi zawiera pole text z rekomendowanym ciągiem tekstowym wyszukiwania. Użyj tego ciągu znaków jako danych wejściowych w wyszukiwaniu tekstowym (nowym), aby przeprowadzić bardziej szczegółowe wyszukiwanie.

Narzędzie APIs Explorer umożliwia wysyłanie żądań w czasie rzeczywistym, dzięki czemu możesz zapoznać się z interfejsem API i jego opcjami:

Żądania autouzupełniania (nowe)

Żądanie Autocomplete (New) to żądanie HTTP POST wysyłane na adres URL w formacie:

https://places.googleapis.com/v1/places:autocomplete

Przekaż wszystkie parametry w treści żądania JSON lub w nagłówkach w ramach żądania POST. Na przykład:

curl -X POST -d '{
  "input": "pizza",
  "locationBias": {
    "circle": {
      "center": {
        "latitude": 37.7937,
        "longitude": -122.3965
      },
      "radius": 500.0
    }
  }
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
https://places.googleapis.com/v1/places:autocomplete

Obsługiwane parametry

Informacje o odpowiedzi

Autouzupełnianie (nowe) zwraca obiekt JSON jako odpowiedź. W odpowiedzi:

• Tablica suggestions zawiera wszystkie przewidywane miejsca i zapytania w kolejności określonej na podstawie ich trafności. Każde miejsce jest reprezentowane przez pole placePrediction, a każde zapytanie – przez pole queryPrediction.
• Pole placePrediction zawiera szczegółowe informacje o jednej prognozie miejsca, w tym identyfikator miejsca i opis tekstowy.
• Pole queryPrediction zawiera szczegółowe informacje o pojedynczej prognozie zapytania.

Pełny obiekt JSON ma postać:

{
  "suggestions": [
    {
      "placePrediction": {
        "place": "places/ChIJ5YQQf1GHhYARPKG7WLIaOko",
        "placeId": "ChIJ5YQQf1GHhYARPKG7WLIaOko",
        "text": {
          "text": "Amoeba Music, Haight Street, San Francisco, CA, USA",
          "matches": [
            {
              "endOffset": 6
            }]
        },
      ...
    },
    {
      "queryPrediction": {
        "text": {
          "text": "Amoeba Music",
          "matches": [
            {
              "endOffset": 6
            }]
        },
        ...
    }
  ...]
}

Wymagane parametry

• wprowadzanie danych

  Ciąg tekstowy, w którym ma zostać przeprowadzone wyszukiwanie. Określ pełne słowa i podciągi znaków, nazwy miejsc, adresy i kody plus. Usługa Autocomplete (New) zwraca pasujące propozycje na podstawie tego ciągu znaków i porządkuje wyniki według ich trafności.

Parametry opcjonalne

• FieldMask

  Określ listę pól, które mają zostać zwrócone w odpowiedzi, tworząc maskę pola odpowiedzi. Przekaż maskę pola odpowiedzi do metody, używając nagłówka HTTP X-Goog-FieldMask.

  Podaj rozdzieloną przecinkami listę pól sugestii do zwrócenia. Na przykład, aby pobrać suggestions.placePrediction.text.text i suggestions.queryPrediction.text.text sugestii.

    X-Goog-FieldMask: suggestions.placePrediction.text.text,suggestions.queryPrediction.text.text

  Użyj *, aby pobrać wszystkie pola.

    X-Goog-FieldMask: *

• includedPrimaryTypes

  Miejsce może mieć tylko jeden typ podstawowy z typów wymienionych w tabeli A lub tabeli B. Na przykład typ podstawowy może mieć wartość "mexican_restaurant" lub "steak_house".

  Domyślnie interfejs API zwraca wszystkie miejsca na podstawie parametru input, niezależnie od wartości typu podstawowego powiązanego z miejscem. Ogranicz wyniki do określonego typu podstawowego lub typów podstawowych, przekazując parametr includedPrimaryTypes.

  Użyj tego parametru, aby określić maksymalnie 5 wartości typu z tabeli A lub tabeli B. Aby miejsce zostało uwzględnione w odpowiedzi, musi odpowiadać jednej z określonych wartości typu podstawowego.

  Ten parametr może też zawierać zamiast tego jeden z tych symboli: (regions) lub (cities). Kolekcja typów (regions) filtruje obszary lub podziały, takie jak dzielnice i kody pocztowe. Kolekcja typu (cities) filtruje miejsca, które Google identyfikuje jako miasto.

  Żądanie zostanie odrzucone z błędem INVALID_REQUEST, jeśli:

  • Określono więcej niż 5 typów.
  • Oprócz (cities) lub (regions) określono dowolny typ.
  • Wszystkie nierozpoznane typy są określone.

• includePureServiceAreaBusinesses

  Jeśli wartość tego parametru to true, odpowiedź zawiera firmy, które odwiedzają klientów lub dostarczają im produkty bezpośrednio, ale nie mają fizycznej lokalizacji. Jeśli wartość tego parametru to false, interfejs API zwraca tylko firmy z fizyczną lokalizacją.

• includeQueryPredictions

  Jeśli true, odpowiedź zawiera zarówno prognozy dotyczące miejsca, jak i zapytania. Wartość domyślna to false, co oznacza, że odpowiedź zawiera tylko prognozy dotyczące miejsc.

• includedRegionCodes

  Uwzględniaj tylko wyniki z listy określonych regionów, podanych jako tablica zawierająca maksymalnie 15 dwuznakowych wartości ccTLD („domena najwyższego poziomu”). Jeśli ten parametr zostanie pominięty, do odpowiedzi nie zostaną zastosowane żadne ograniczenia. Aby na przykład ograniczyć regiony do Niemiec i Francji:

      "includedRegionCodes": ["de", "fr"]

  Jeśli określisz zarówno locationRestriction, jak i includedRegionCodes, wyniki będą znajdować się w obszarze przecięcia tych 2 ustawień.

• inputOffset

  Odsunięcie znaku Unicode od zera wskazujące pozycję kursora w input. Pozycja kursora może wpływać na zwracane prognozy. Jeśli to pole jest puste, domyślnie przyjmuje długość input.

• languageCode

  Preferowany język, w którym mają być zwracane wyniki. Wyniki mogą być w różnych językach, jeśli język użyty w input różni się od wartości określonej przez languageCode lub jeśli zwrócone miejsce nie ma tłumaczenia z języka lokalnego na język languageCode.

  • Aby określić preferowany język, musisz użyć kodów języków IETF BCP-47.
  • Jeśli parametr languageCode nie zostanie podany, interfejs API użyje wartości określonej w nagłówku Accept-Language. Jeśli nie określisz żadnej z tych wartości, zostanie użyta wartość domyślna en. Jeśli podasz nieprawidłowy kod języka, API zwróci błąd INVALID_ARGUMENT.
  • 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. Ma to też wpływ na możliwość poprawiania błędów ortograficznych przez interfejs API.
  • Interfejs API próbuje podać adres ulicy, który jest czytelny zarówno dla użytkownika, jak i dla lokalnej społeczności, a jednocześnie odzwierciedla dane wejściowe użytkownika. Prognozy miejsc są formatowane w różny sposób w zależności od danych wejściowych użytkownika w każdym żądaniu.
    • Najpierw wybierane są pasujące terminy w parametrze input, przy czym używane są nazwy zgodne z preferencjami językowymi wskazanymi przez parametr languageCode, jeśli są dostępne, a w przeciwnym razie nazwy najlepiej pasujące do danych wprowadzonych przez użytkownika.
    • Adresy są formatowane w języku lokalnym, w piśmie czytelnym dla użytkownika, w miarę możliwości dopiero po wybraniu pasujących terminów, które odpowiadają terminom w parametrze input.
    • Wszystkie pozostałe adresy są zwracane w preferowanym języku po wybraniu pasujących terminów, które odpowiadają terminom w parametrze input. Jeśli nazwa nie jest dostępna w preferowanym języku, interfejs API użyje najbliższego dopasowania.

• locationBias lub locationRestriction

  Aby określić obszar wyszukiwania, możesz podać locationBias lub locationRestriction, ale nie oba jednocześnie. locationRestriction określa region, w którym muszą się znajdować wyniki, a locationBias określa region, w pobliżu którego muszą się znajdować wyniki, ale mogą być poza tym obszarem.

  • locationBias

    Określa obszar wyszukiwania. Ta lokalizacja służy jako punkt odniesienia, co oznacza, że mogą być zwracane wyniki z okolic określonej lokalizacji, w tym wyniki spoza określonego obszaru.

  • locationRestriction

    Określa obszar wyszukiwania. Wyniki spoza określonego obszaru nie są zwracane.

  Określ region locationBias lub locationRestriction jako prostokątny widok lub okrąg.

  • Okrąg jest definiowany przez punkt środkowy i promień w metrach. Promień musi mieścić się w zakresie od 0,0 do 50 000,0 włącznie. Wartością domyślną jest 0,0. W przypadku locationRestriction musisz ustawić promień na wartość większą niż 0,0. W przeciwnym razie żądanie nie zwraca wyników.

    Na przykład:

    "locationBias": {
      "circle": {
        "center": {
          "latitude": 37.7937,
          "longitude": -122.3965
        },
        "radius": 500.0
      }
    }

  • Prostokąt to widoczny obszar określony przez szerokość i długość geograficzną, reprezentowany przez 2 przeciwległe punkty low i wysokie. Widoczny obszar jest uważany za zamknięty region, co oznacza, że obejmuje swoje granice. Zakres szerokości geograficznej musi się mieścić w przedziale od -90 do 90 stopni włącznie, a zakres długości geograficznej musi się mieścić w przedziale od -180 do 180 stopni włącznie:

    • Jeśli low = high, widoczny obszar składa się z tego jednego punktu.
    • Jeśli low.longitude > high.longitude, zakres długości geograficznej jest odwrócony (widoczny obszar przekracza linię długości geograficznej 180 stopni).
    • Jeśli low.longitude = –180 stopni, a high.longitude = 180 stopni, widoczny obszar obejmuje wszystkie długości geograficzne.
    • Jeśli low.longitude = 180 stopni, a high.longitude = -180 stopni, zakres długości geograficznej jest pusty.

    Pola low i high muszą być wypełnione, a reprezentowane pole nie może być puste. Pusty widoczny obszar powoduje błąd.

    Na przykład ten widoczny obszar w całości obejmuje Nowy Jork:

    "locationBias": {
      "rectangle": {
        "low": {
          "latitude": 40.477398,
          "longitude": -74.259087
        },
        "high": {
          "latitude": 40.91618,
          "longitude": -73.70018
        }
      }
    }

• pochodzenie

  Punkt początkowy, od którego należy obliczyć odległość w linii prostej do miejsca docelowego (zwracany jako distanceMeters). Jeśli ta wartość zostanie pominięta, odległość w linii prostej nie zostanie zwrócona. Musi być określony jako współrzędne szerokości i długości geograficznej:

  "origin": {
      "latitude": 40.477398,
      "longitude": -74.259087
  }

• regionCode

  Kod regionu używany do formatowania odpowiedzi, określony jako dwuznakowa wartość ccTLD („domena najwyższego poziomu”). Większość kodów ccTLD jest identyczna z kodami ISO 3166-1, z kilkoma istotnymi 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”).

  Sugestie są też obciążone kodami regionów. Google zaleca ustawienie parametru regionCode zgodnie z preferencjami regionalnymi użytkownika.

  Jeśli podasz nieprawidłowy kod regionu, interfejs API zwróci błąd INVALID_ARGUMENT. W zależności od obowiązujących przepisów parametr może wpływać na wyniki.

• sessionToken

  Tokeny sesji to wygenerowane przez użytkownika ciągi znaków, które śledzą wywołania Autouzupełniania (nowego) jako „sesje”. Autouzupełnianie (nowa wersja) używa tokenów sesji do grupowania faz zapytania i wyboru w wyszukiwaniu autouzupełniania użytkownika w osobną sesję na potrzeby rozliczeń. Więcej informacji znajdziesz w sekcji Tokeny sesji.

Wybieranie parametrów, które mają wpływać na wyniki

Przykłady autouzupełniania (nowość)

Ograniczanie wyszukiwania do obszaru za pomocą parametru locationRestriction

locationRestriction określa obszar wyszukiwania. Wyniki spoza określonego obszaru nie są zwracane. W poniższym przykładzie używasz parametru locationRestriction, aby ograniczyć żądanie do okręgu o promieniu 5000 metrów, którego środek znajduje się w San Francisco:

curl -X POST -d '{
  "input": "Art museum",
  "locationRestriction": {
    "circle": {
      "center": {
        "latitude": 37.7749,
        "longitude": -122.4194
      },
      "radius": 5000.0
    }
  }
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
https://places.googleapis.com/v1/places:autocomplete

Wszystkie wyniki z określonych obszarów znajdują się w tablicy suggestions:

  {
    "suggestions": [
      {
        "placePrediction": {
          "place": "places/ChIJkQQVTZqAhYARHxPt2iJkm1Q",
          "placeId": "ChIJkQQVTZqAhYARHxPt2iJkm1Q",
          "text": {
            "text": "Asian Art Museum, Larkin Street, San Francisco, CA, USA",
            "matches": [
              {
                "startOffset": 6,
                "endOffset": 16
              }
            ]
          },
          "structuredFormat": {
            "mainText": {
              "text": "Asian Art Museum",
              "matches": [
                {
                  "startOffset": 6,
                  "endOffset": 16
                }
              ]
            },
            "secondaryText": {
              "text": "Larkin Street, San Francisco, CA, USA"
            }
          },
          "types": [
            "establishment",
            "museum",
            "point_of_interest"
          ]
        }
      },
      {
        "placePrediction": {
          "place": "places/ChIJI7NivpmAhYARSuRPlbbn_2w",
          "placeId": "ChIJI7NivpmAhYARSuRPlbbn_2w",
          "text": {
            "text": "de Young Museum, Hagiwara Tea Garden Drive, San Francisco, CA, USA",
            "matches": [
              {
                "endOffset": 15
              }
            ]
          },
          "structuredFormat": {
            "mainText": {
              "text": "de Young Museum",
              "matches": [
                {
                  "endOffset": 15
                }
              ]
            },
            "secondaryText": {
              "text": "Hagiwara Tea Garden Drive, San Francisco, CA, USA"
            }
          },
          "types": [
            "establishment",
            "point_of_interest",
            "tourist_attraction",
            "museum"
          ]
        }
      },
      /.../
    ]
  }

Możesz też użyć znaku locationRestriction, aby ograniczyć wyszukiwanie do prostokątnego widocznego obszaru. Poniższy przykład ogranicza żądanie do centrum San Francisco:

  curl -X POST -d '{
    "input": "Art museum",
    "locationRestriction": {
      "rectangle": {
        "low": {
          "latitude": 37.7751,
          "longitude": -122.4219
        },
        "high": {
          "latitude": 37.7955,
          "longitude": -122.3937
        }
      }
    }
  }' \
  -H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
  https://places.googleapis.com/v1/places:autocomplete

Wyniki są zawarte w tablicy suggestions:

  {
    "suggestions": [
      {
        "placePrediction": {
          "place": "places/ChIJkQQVTZqAhYARHxPt2iJkm1Q",
          "placeId": "ChIJkQQVTZqAhYARHxPt2iJkm1Q",
          "text": {
            "text": "Asian Art Museum, Larkin Street, San Francisco, CA, USA",
            "matches": [
              {
                "startOffset": 6,
                "endOffset": 16
              }
            ]
          },
          "structuredFormat": {
            "mainText": {
              "text": "Asian Art Museum",
              "matches": [
                {
                  "startOffset": 6,
                  "endOffset": 16
                }
              ]
            },
            "secondaryText": {
              "text": "Larkin Street, San Francisco, CA, USA"
            }
          },
          "types": [
            "point_of_interest",
            "museum",
            "establishment"
          ]
        }
      },
      {
        "placePrediction": {
          "place": "places/ChIJyQNK-4SAhYARO2DZaJleWRc",
          "placeId": "ChIJyQNK-4SAhYARO2DZaJleWRc",
          "text": {
            "text": "International Art Museum of America, Market Street, San Francisco, CA, USA",
            "matches": [
              {
                "startOffset": 14,
                "endOffset": 24
              }
            ]
          },
          "structuredFormat": {
            "mainText": {
              "text": "International Art Museum of America",
              "matches": [
                {
                  "startOffset": 14,
                  "endOffset": 24
                }
              ]
            },
            "secondaryText": {
              "text": "Market Street, San Francisco, CA, USA"
            }
          },
          "types": [
            "museum",
            "point_of_interest",
            "tourist_attraction",
            "art_gallery",
            "establishment"
          ]
        }
      }
    ]
  }

Zawężanie wyszukiwania do obszaru za pomocą parametru locationBias

W przypadku parametru locationBias lokalizacja służy jako punkt odniesienia, co oznacza, że mogą być zwracane wyniki z okolic określonej lokalizacji, w tym wyniki spoza określonego obszaru. W poniższym przykładzie kierujesz żądanie na śródmieście San Francisco:

curl -X POST -d '{
  "input": "Amoeba",
  "locationBias": {
    "circle": {
      "center": {
        "latitude": 37.7749,
        "longitude": -122.4194
      },
      "radius": 5000.0
    }
  }
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
https://places.googleapis.com/v1/places:autocomplete

Wyniki zawierają teraz znacznie więcej pozycji, w tym wyniki spoza promienia 5000 metrów:

{
  "suggestions": [
    {
      "placePrediction": {
        "place": "places/ChIJ5YQQf1GHhYARPKG7WLIaOko",
        "placeId": "ChIJ5YQQf1GHhYARPKG7WLIaOko",
        "text": {
          "text": "Amoeba Music, Haight Street, San Francisco, CA, USA",
          "matches": [
            {
              "endOffset": 6
            }
          ]
        },
        "structuredFormat": {
          "mainText": {
            "text": "Amoeba Music",
            "matches": [
              {
                "endOffset": 6
              }
            ]
          },
          "secondaryText": {
            "text": "Haight Street, San Francisco, CA, USA"
          }
        },
        "types": [
          "electronics_store",
          "point_of_interest",
          "store",
          "establishment",
          "home_goods_store"
        ]
      }
    },
    {
      "placePrediction": {
        "place": "places/ChIJr7uwwy58hYARBY-e7-QVwqw",
        "placeId": "ChIJr7uwwy58hYARBY-e7-QVwqw",
        "text": {
          "text": "Amoeba Music, Telegraph Avenue, Berkeley, CA, USA",
          "matches": [
            {
              "endOffset": 6
            }
          ]
        },
        "structuredFormat": {
          "mainText": {
            "text": "Amoeba Music",
            "matches": [
              {
                "endOffset": 6
              }
            ]
          },
          "secondaryText": {
            "text": "Telegraph Avenue, Berkeley, CA, USA"
          }
        },
        "types": [
          "electronics_store",
          "point_of_interest",
          "establishment",
          "home_goods_store",
          "store"
        ]
      }
    },
    ...
  ]
}

Możesz też użyć symbolu locationBias, aby zawęzić wyszukiwanie do prostokątnego obszaru widoku. Poniższy przykład ogranicza żądanie do centrum San Francisco:

  curl -X POST -d '{
    "input": "Amoeba",
    "locationBias": {
      "rectangle": {
        "low": {
          "latitude": 37.7751,
          "longitude": -122.4219
        },
        "high": {
          "latitude": 37.7955,
          "longitude": -122.3937
        }
      }
    }
  }' \
  -H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
  https://places.googleapis.com/v1/places:autocomplete

Chociaż w odpowiedzi pojawiają się wyniki wyszukiwania w prostokątnym obszarze widoku, niektóre z nich znajdują się poza zdefiniowanymi granicami ze względu na odchylenie. Wyniki są też zawarte w tablicy suggestions:

  {
    "suggestions": [
      {
        "placePrediction": {
          "place": "places/ChIJ5YQQf1GHhYARPKG7WLIaOko",
          "placeId": "ChIJ5YQQf1GHhYARPKG7WLIaOko",
          "text": {
            "text": "Amoeba Music, Haight Street, San Francisco, CA, USA",
            "matches": [
              {
                "endOffset": 6
              }
            ]
          },
          "structuredFormat": {
            "mainText": {
              "text": "Amoeba Music",
              "matches": [
                {
                  "endOffset": 6
                }
              ]
            },
            "secondaryText": {
              "text": "Haight Street, San Francisco, CA, USA"
            }
          },
          "types": [
            "point_of_interest",
            "store",
            "establishment"
          ]
        }
      },
      {
        "placePrediction": {
          "place": "places/ChIJr7uwwy58hYARBY-e7-QVwqw",
          "placeId": "ChIJr7uwwy58hYARBY-e7-QVwqw",
          "text": {
            "text": "Amoeba Music, Telegraph Avenue, Berkeley, CA, USA",
            "matches": [
              {
                "endOffset": 6
              }
            ]
          },
          "structuredFormat": {
            "mainText": {
              "text": "Amoeba Music",
              "matches": [
                {
                  "endOffset": 6
                }
              ]
            },
            "secondaryText": {
              "text": "Telegraph Avenue, Berkeley, CA, USA"
            }
          },
          "types": [
            "point_of_interest",
            "store",
            "establishment"
          ]
        }
      },
      {
        "placePrediction": {
          "place": "places/ChIJRdmfADq_woARYaVhnfQSUTI",
          "placeId": "ChIJRdmfADq_woARYaVhnfQSUTI",
          "text": {
            "text": "Amoeba Music, Hollywood Boulevard, Los Angeles, CA, USA",
            "matches": [
              {
                "endOffset": 6
              }
            ]
          },
          "structuredFormat": {
            "mainText": {
              "text": "Amoeba Music",
              "matches": [
                {
                  "endOffset": 6
                }
              ]
            },
            "secondaryText": {
              "text": "Hollywood Boulevard, Los Angeles, CA, USA"
            }
          },
          "types": [
            "point_of_interest",
            "store",
            "establishment"
          ]
        }
      },
    /.../
    ]
  }

Używanie parametru includedPrimaryTypes

Użyj parametru includedPrimaryTypes, aby określić maksymalnie 5 wartości typu z tabeli A, tabeli B lub tylko (regions) albo tylko (cities). Aby miejsce zostało uwzględnione w odpowiedzi, musi pasować do jednej z określonych wartości typu podstawowego.

W tym przykładzie określasz ciąg znaków input „Piłka nożna” i używasz parametru includedPrimaryTypes, aby ograniczyć wyniki do placówek typu "sporting_goods_store":

curl -X POST -d '{
  "input": "Soccer",
  "includedPrimaryTypes": ["sporting_goods_store"],
  "locationBias": {
    "circle": {
      "center": {
        "latitude": 37.7749,
        "longitude": -122.4194
      },
      "radius": 500.0
    }
  }
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
https://places.googleapis.com/v1/places:autocomplete

Jeśli pominiesz parametr includedPrimaryTypes, wyniki mogą zawierać obiekty, których nie chcesz, np. "athletic_field".

Żądanie prognoz zapytań

Domyślnie nie są zwracane prognozy zapytań. Użyj parametru żądania includeQueryPredictions, aby dodać do odpowiedzi prognozy zapytań. Na przykład:

curl -X POST -d '{
  "input": "Amoeba",
  "includeQueryPredictions": true,
  "locationBias": {
    "circle": {
      "center": {
        "latitude": 37.7749,
        "longitude": -122.4194
      },
      "radius": 5000.0
    }
  }
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
https://places.googleapis.com/v1/places:autocomplete

Tablica suggestions zawiera teraz zarówno prognozy dotyczące miejsc, jak i prognozy dotyczące zapytań, jak pokazano powyżej w sekcji Informacje o odpowiedzi. Każda prognoza zapytania zawiera pole text z rekomendowanym ciągiem tekstowym wyszukiwania. Możesz wysłać żądanie Wyszukiwanie tekstowe (nowe), aby uzyskać więcej informacji o dowolnej z zwróconych prognoz zapytań.

Użyj punktu początkowego

W tym przykładzie w żądaniu podaj origin jako współrzędne szerokości i długości geograficznej. Jeśli uwzględnisz origin, Autocomplete (New) w odpowiedzi uwzględni pole distanceMeters, które zawiera odległość w linii prostej od origin do miejsca docelowego. W tym przykładzie punkt początkowy jest ustawiony na środek San Francisco:

curl -X POST -d '{
  "input": "Amoeba",
  "origin": {
    "latitude": 37.7749,
    "longitude": -122.4194
  },
  "locationRestriction": {
    "circle": {
      "center": {
        "latitude": 37.7749,
        "longitude": -122.4194
      },
      "radius": 5000.0
    }
  }
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
https://places.googleapis.com/v1/places:autocomplete

Odpowiedź zawiera teraz distanceMeters:

{
  "suggestions": [
    {
      "placePrediction": {
        "place": "places/ChIJ5YQQf1GHhYARPKG7WLIaOko",
        "placeId": "ChIJ5YQQf1GHhYARPKG7WLIaOko",
        "text": {
          "text": "Amoeba Music, Haight Street, San Francisco, CA, USA",
          "matches": [
            {
              "endOffset": 6
            }
          ]
        },
        "structuredFormat": {
          "mainText": {
            "text": "Amoeba Music",
            "matches": [
              {
                "endOffset": 6
              }
            ]
          },
          "secondaryText": {
            "text": "Haight Street, San Francisco, CA, USA"
          }
        },
        "types": [
          "home_goods_store",
          "establishment",
          "point_of_interest",
          "store",
          "electronics_store"
        ],
        "distanceMeters": 3012
      }
    }
  ]
}

W odpowiedzi brakuje odległości

W niektórych przypadkach w treści odpowiedzi brakuje parametru distanceMeters, nawet jeśli w żądaniu jest parametr origin. Może się tak zdarzyć w tych sytuacjach:

• distanceMeters nie jest uwzględniana w prognozach route.
• distanceMeters nie jest uwzględniany, gdy jego wartość jest mniejsza niż 0, co ma miejsce w przypadku prognoz, które znajdują się w odległości mniejszej niż 1 metr od podanej origin lokalizacji.

Biblioteki klienta, które próbują odczytać pole distanceMeters z przeanalizowanego obiektu, zwrócą pole o wartości 0. Aby nie wprowadzać użytkowników w błąd, nie wyświetlaj im odległości równej zero.

Optymalizacja autouzupełniania (nowość)

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

Oto kilka ogólnych wskazówek:

• Najszybszym sposobem na stworzenie działającego interfejsu użytkownika jest użycie widżetu autouzupełniania (nowego) w interfejsie Maps JavaScript API, widżetu autouzupełniania (nowego) w pakiecie SDK Miejsc na Androida lub widżetu autouzupełniania (nowego) w pakiecie SDK Miejsc na iOS.
• Poznaj najważniejsze pola danych autouzupełniania (nowość) 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.
• Sprawdź, czy aplikacja obsługuje sytuacje, w których użytkownik nie dokonał wyboru, i czy oferuje mu możliwość kontynuowania.

Sprawdzone metody optymalizacji kosztów

Podstawowa optymalizacja kosztów

Aby zoptymalizować koszt korzystania z usługi Autouzupełnianie (nowa), użyj masek pól w widżetach Szczegóły miejsca (nowe) i Autouzupełnianie (nowe), aby zwracać tylko potrzebne pola danych Autouzupełniania (nowego).

Zaawansowana optymalizacja kosztów

Rozważ programowe wdrożenie Autocomplete (New), aby uzyskać dostęp do SKU: Autocomplete Request pricing i wysyłać zapytania o wyniki interfejsu Geocoding API dotyczące wybranego miejsca zamiast szczegółów miejsca (nowych). Ceny za żądanie w połączeniu z interfejsem Geocoding API są bardziej opłacalne niż ceny za sesję (oparte na sesjach), jeśli spełnione są oba te warunki:

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

• Dodaj do implementacji Autocomplete (New) ograniczenia dotyczące kraju, ustawienia lokalizacji i (w przypadku implementacji programowych) preferencje językowe. W przypadku widżetów nie trzeba określać preferencji językowych, ponieważ są one pobierane z przeglądarki lub urządzenia mobilnego użytkownika.
• Jeśli usłudze Autouzupełnianie (nowa) towarzyszy mapa, możesz określić lokalizację na podstawie widocznego obszaru mapy.
• Jeśli użytkownik nie wybierze żadnej z podpowiedzi Autocomplete (New), zwykle dlatego, że żadna z nich nie jest szukanym adresem, możesz ponownie użyć pierwotnego tekstu wpisanego przez użytkownika, aby uzyskać bardziej trafne wyniki:
  • Jeśli oczekujesz, że użytkownik wpisze 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 Szczegóły miejsca (nowe). 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” generuje częściową podpowiedź w usłudze Autouzupełnianie (nowa 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. To polecenie informuje usługę Autocomplete (New), ż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 components, 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 locationRestriction. To polecenie informuje interfejs Autocomplete (New), że ma zwracać tylko wyniki z tego regionu.

Wypróbuj

Narzędzie APIs Explorer umożliwia wysyłanie przykładowych żądań, dzięki czemu możesz zapoznać się z interfejsem API i jego opcjami.

1. Po prawej stronie strony kliknij ikonę interfejsu API api.

2. Opcjonalnie możesz edytować parametry żądania.

3. Kliknij przycisk Wykonaj. W oknie dialogowym wybierz konto, z którego chcesz wysłać prośbę.

4. W panelu APIs Explorer kliknij ikonę pełnego ekranu fullscreen, aby rozwinąć okno narzędzia.