Autouzupełnianie (nowość)

Wprowadzenie

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

Autouzupełnianie (nowe) może dopasowywać pełne słowa i podłańcuchy danych wejściowych, rozpoznając nazwy miejsc, adresy i plus kody. Dzięki temu aplikacje mogą wysyłać zapytania podczas wpisywania tekstu przez użytkownika, aby na bieżąco wyświetlać podpowiedzi dotyczące miejsc i zapytań.

Odpowiedź z autouzupełniania (nowego) może zawierać 2 rodzaje podpowiedzi:

• Podpowiedzi miejsc: miejsca, takie jak firmy, adresy i ciekawe miejsca, na podstawie podanego ciągu tekstowego i obszaru wyszukiwania. Domyślnie zwracane są podpowiedzi dotyczące miejsc.
• Podpowiedzi zapytań: ciągi zapytań pasujące do wejściowego ciągu tekstowego i obszaru wyszukiwania. Podpowiedzi zapytań nie są domyślnie zwracane. Aby dodać do odpowiedzi podpowiedzi zapytania, użyj parametru żądania includeQueryPredictions.

Załóżmy na przykład, że wywołujesz Autouzupełnianie (nowe), używając jako danych wejściowych ciągu znaków, który zawiera częściowe dane wejściowe użytkownika „Sicilian piz”, a obszar wyszukiwania jest ograniczony do San Francisco w Kalifornii. Odpowiedź zawiera listę podpowiedzi miejsc, które pasują do wyszukiwanego ciągu znaków i obszaru wyszukiwania, np. restaurację o nazwie „Sicilian Pizza Kitchen”, wraz ze szczegółowymi informacjami o miejscu.

Zwrócone podpowiedzi miejsc są przeznaczone do wyświetlania użytkownikowi, aby pomóc mu w wyborze odpowiedniego miejsca. Możesz wysłać żądanie informacji o miejscu (nowe), aby uzyskać więcej informacji o zwróconych podpowiedziach miejsc.

Odpowiedź może też zawierać listę podpowiedzi zapytań, które pasują do wyszukiwanego ciągu znaków i obszaru wyszukiwania, np. „Sicilian Pizza & Pasta”. Każda podpowiedź zapytania w odpowiedzi zawiera pole text z zalecanym ciągiem wyszukiwania tekstowego. Użyj tego ciągu znaków jako danych wejściowych w wyszukiwarce tekstowej (nowej), 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 Autouzupełniania (nowe) 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 opartej na ich postrzeganej 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 podpowiedzi miejsca, w tym identyfikator miejsca i opis tekstowy.
  • Aby lepiej dopasować dane wejściowe użytkownika podane w parametrze input, opis tekstowy podpowiedzi miejsca może zawierać alternatywne nazwy miejsc, ulic i innych elementów adresu. Te alternatywne nazwy mogą się różnić od nazw zwracanych w polach displayName i adresu w wynikach informacji o miejscu dla tego samego identyfikatora miejsca.
  • W tym kontekście alternatywne nazwy niektórych miejsc mogą być w innym języku niż oczekiwany na podstawie parametru languageCode, w zależności od tego, które nazwy są bardziej zbliżone do danych wprowadzonych przez użytkownika.
• Pole queryPrediction zawiera szczegółowe informacje o pojedynczej podpowiedzi dotyczącej zapytania.

Kompletny 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, który ma zostać wyszukany. Podaj pełne słowa i podłańcuchy, nazwy miejsc, adresy i plus codes. Usługa Autouzupełnianie (nowa) zwraca potencjalne dopasowania 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, które mają zostać zwrócone. 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

Aby pobrać wszystkie pola, użyj *.

  X-Goog-FieldMask: *

includeFutureOpeningBusinesses

Jeśli ma wartość true, zwraca firmy, które mają zostać otwarte w przyszłości. Domyślna wartość to false.

includedPrimaryTypes

Miejsce może mieć tylko 1 główny typ spośród typów wymienionych w tabeli A lub tabeli B. Na przykład typem głównym może być "mexican_restaurant" lub "steak_house".

Domyślnie interfejs API zwraca wszystkie miejsca na podstawie parametru input, niezależnie od wartości typu głównego powiązanej z miejscem. Ogranicz wyniki do określonego typu głównego lub określonych typów głównych, 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ć (regions) lub (cities). Kolekcja typu (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:

• Podano więcej niż 5 typów.
• Oprócz (cities) lub (regions) określono dowolny typ.
• określono nierozpoznane typy;

includePureServiceAreaBusinesses

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

includeQueryPredictions

Jeśli true, odpowiedź zawiera zarówno podpowiedzi dotyczące miejsc, jak i zapytań. Wartością domyślną jest false, co oznacza, że odpowiedź zawiera tylko podpowiedzi 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 pominiesz ten parametr, 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

Przesunięcie znaku Unicode liczone od 0, które wskazuje pozycję kursora w polu input. Pozycja kursora może wpływać na zwracane podpowiedzi. Jeśli pozostawisz to pole puste, domyślnie zostanie użyta 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żywany w parametrze input różni się od wartości określonej przez parametr languageCode lub jeśli zwrócone miejsce nie ma tłumaczenia z języka lokalnego na język określony przez parametr languageCode.

• Aby określić preferowany język, musisz użyć kodów języków IETF BCP-47.
• Jeśli nie podasz parametru languageCode, interfejs API użyje wartości określonej w nagłówku Accept-Language. Jeśli nie określono żadnej z tych wartości, domyślną wartością jest en. Jeśli podasz nieprawidłowy kod języka, interfejs API zwróci błąd INVALID_ARGUMENT.
• Preferowany język ma niewielki wpływ na zestaw wyników, które interfejs API zwraca, oraz na kolejność, w jakiej są zwracane. Wpływa to też na możliwość poprawiania błędów pisowni przez interfejs API.
• Podpowiedzi miejsc są formatowane inaczej w zależności od danych wejściowych użytkownika w każdym żądaniu.
  • Najpierw wybierane są pasujące hasła w parametrze input, przy czym używane są nazwy zgodne z ustawieniem języka wskazanym przez parametr languageCode, jeśli jest dostępny. W przeciwnym razie używane są nazwy, które najlepiej pasują do danych wejściowych użytkownika.
  • Nazwy miejsc mogą być sformatowane przy użyciu nazw alternatywnych, aby pasowały do haseł w parametrze input, w tym nazw w językach innych niż język wskazany przez parametr languageCode.
  • Adresy są formatowane w języku lokalnym, w miarę możliwości w skrypcie czytelnym dla użytkownika, dopiero po wybraniu haseł pasujących do haseł w parametrze input.
  • Wszystkie pozostałe adresy są zwracane w preferowanym języku po wybraniu haseł pasujących do haseł w parametrze input. Jeśli nazwa nie jest dostępna w preferowanym języku, interfejs API używa najbliższego dopasowania.

locationBias lub locationRestriction

Aby określić obszar wyszukiwania, możesz podać locationBias lub locationRestriction, ale nie obie te wartości. Parametr locationRestriction określa region, w którym muszą znajdować się wyniki, a parametr locationBias określa region, w pobliżu którego muszą znajdować się 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 dotyczące 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 widoczny obszar lub jako 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ść domyślna to 0,0. W przypadku locationRestriction musisz ustawić promień na wartość większą niż 0,0. W przeciwnym razie żądanie nie zwraca żadnych wyników.

  Na przykład:

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

• Prostokąt to widoczny obszar szerokości i długości geograficznej, reprezentowany jako 2 przeciwległe po przekątnej punkty low i wysokie. Okno jest uważane za zamknięty region, co oznacza, że obejmuje swoje granice. Szerokość geograficzna musi mieścić się w zakresie od -90 do 90 stopni, a długość geograficzna – od -180 do 180 stopni:

  • Jeśli low = high, widoczny obszar składa się z tego pojedynczego 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 obejmuje cały 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 ma być obliczana odległość w linii prostej do miejsca docelowego (zwracana jako distanceMeters). Jeśli ta wartość zostanie pominięta, odległość w linii prostej nie zostanie zwrócona. Muszą być określone 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 2-znakowa wartość ccTLD („domena najwyższego poziomu”). Większość kodów ccTLD jest identyczna z kodami ISO 3166-1, ale są pewne wyjątki. 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”).

Sugestie są też dostosowywane na podstawie kodów 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. Parametr może wpływać na wyniki na podstawie obowiązujących przepisów.

Gdy ustawisz regionCode, podpowiedzi w tym regionie mogą pomijać nazwę kraju w tekście sugestii, co oznacza, że structuredFormat.secondaryText może nie być obecny. Dlatego upewnij się, że aplikacja obsługuje przypadki, w których parametr secondaryText jest niezdefiniowany lub go brakuje.

sessionToken

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

Wybieranie parametrów do dostosowywania wyników

Przykłady autouzupełniania (nowa wersja)

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 ze środkiem 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 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": [
            "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ć parametru locationRestriction, aby ograniczyć wyszukiwanie do prostokątnego obszaru widoku. Ten 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"
          ]
        }
      }
    ]
  }

Ukierunkowywanie wyszukiwania na dany obszar za pomocą parametru locationBias

W przypadku parametru locationBias lokalizacja służy jako preferencja, co oznacza, że mogą być zwracane wyniki z określonej lokalizacji, w tym wyniki spoza określonego obszaru. W tym przykładzie żądanie jest kierowane na centrum 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 elementów, 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ć parametru locationBias, aby wyszukiwanie było ukierunkowane na prostokątny widoczny obszar. Ten 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ż wyniki wyszukiwania w prostokątnym widocznym obszarze pojawiają się w odpowiedzi, niektóre wyniki znajdują się poza zdefiniowanymi granicami ze względu na faworyzowanie. 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żyj includedPrimaryTypes

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

W tym przykładzie podajesz ciąg znaków input „Soccer” 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ą obejmować placówki typu, którego nie chcesz, np. "athletic_field".

Żądanie podpowiedzi dotyczących zapytania

Podpowiedzi zapytań nie są domyślnie zwracane. Aby dodać do odpowiedzi podpowiedzi zapytania, użyj parametru żądania includeQueryPredictions. 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 podpowiedzi miejsc, jak i podpowiedzi zapytań, jak pokazano powyżej w sekcji Informacje o odpowiedzi. Każda podpowiedź zapytania zawiera pole text z zalecanym ciągiem tekstowym wyszukiwania. Możesz wysłać żądanie Wyszukaj tekst (Nowe), aby uzyskać więcej informacji o zwróconych podpowiedziach.

Użyj punktu początkowego

W tym przykładzie uwzględnij w żądaniu origin jako współrzędne szerokości i długości geograficznej. Gdy uwzględnisz parametr origin, Autouzupełnianie (nowe) uwzględni w odpowiedzi 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 centrum 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
      }
    }
  ]
}

Znajdowanie firm, które zostaną otwarte w przyszłości

Poniższy przykład pokazuje żądanie Autouzupełniania (nowego) dotyczące firm, które zostaną otwarte w przyszłości w New Meadows w Idaho:

curl -X POST \
-H "Content-Type: application/json" \
-H "X-Goog-Api-Key: API_KEY" \
-d '{
  "input": "Roberts Greenhouse and Tree Farm",
  "includeFutureOpeningBusinesses": true,
  "locationBias": {
    "circle": {
      "center": {"latitude": 44.9755100, "longitude": -116.2842180},
      "radius": 20
    }
  }
}' \
"https://places.googleapis.com/v1/places:autocomplete"

Odpowiedź zawiera szczegółowe informacje o miejscu, ale nie zawiera daty otwarcia.

{
  "suggestions": [
    {
      "placePrediction": {
        "place": "places/ChIJp1-VoKWJplQRMz8g-7Wa3Do",
        "placeId": "ChIJp1-VoKWJplQRMz8g-7Wa3Do",
        "text": {
          "text": "Roberts Greenhouse and Tree Farm, McLain Street, New Meadows, ID, USA",
          "matches": [
            {
              "endOffset": 32
            }
          ]
        },
        "structuredFormat": {
          "mainText": {
            "text": "Roberts Greenhouse and Tree Farm",
            "matches": [
              {
                "endOffset": 32
              }
            ]
          },
          "secondaryText": {
            "text": "McLain Street, New Meadows, ID, USA"
          }
        },
        "types": [
          "garden_center",
          "establishment",
          "service",
          "store",
          "point_of_interest"
        ]
      }
    }
  ]
}

W odpowiedzi brakuje odległości

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

• distanceMeters nie jest uwzględniana w przypadku prognoz dotyczących route.
• distanceMeters nie jest uwzględniany, gdy jego wartość wynosi 0, co ma miejsce w przypadku prognoz, które są oddalone o mniej niż 1 metr od podanej lokalizacji origin.

Biblioteki klienta próbujące 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 0.

Optymalizacja autouzupełniania (nowa wersja)

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

Oto ogólne wskazówki:

• Najszybszym sposobem na stworzenie działającego interfejsu użytkownika jest użycie widżetu autouzupełniania (nowego) z Maps JavaScript API, widżetu autouzupełniania (nowego) z pakietu SDK Miejsc na Androida lub widżetu autouzupełniania (nowego) z pakietu SDK Miejsc na iOS.
• Od samego początku poznaj najważniejsze pola danych autouzupełniania (nowej wersji).
• Pola ukierunkowania na lokalizację i ograniczenia lokalizacji są opcjonalne, ale mogą mieć znaczący wpływ na działanie autouzupełniania.
• Użyj obsługi błędów, aby upewnić się, że aplikacja będzie działać prawidłowo, jeśli interfejs API zwróci błąd.
• Upewnij się, że aplikacja obsługuje sytuację, gdy nie ma wyboru, i oferuje użytkownikom sposób na kontynuowanie.

Sprawdzone metody optymalizacji kosztów

Podstawowa optymalizacja kosztów

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

Zaawansowana optymalizacja kosztów

Rozważ automatyczne wdrożenie autouzupełniania (nowego), aby uzyskać dostęp do SKU: ceny żądań autouzupełniania i poprosić o wyniki Geocoding API dotyczące wybranego miejsca zamiast informacji o miejscu (nowych). 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 miejsca wybranego przez użytkownika, Geocoding API dostarcza te informacje za mniej niż wywołanie informacji o miejscu (New).
• Jeśli użytkownicy wybierają podpowiedź autouzupełniania średnio w ciągu maksymalnie 4 żądań podpowiedzi autouzupełniania (nowych), ceny za żądanie mogą być bardziej opłacalne niż ceny za sesję.

W zależności od wydajności Autouzupełniania (nowego) interfejs Geocoding API może być dla Twojej aplikacji bardziej opłacalny niż informacje o miejscu (nowe). Skuteczność autouzupełniania (nowego) w każdej aplikacji zależy od tego, co wpisują użytkownicy, gdzie aplikacja jest używana i czy wdrożono sprawdzone metody optymalizacji skuteczności.

Aby znaleźć średnią liczbę żądań dla tabeli, przeanalizuj, ile znaków użytkownik wpisuje średnio przed wybraniem podpowiedzi autouzupełniania (nowej) w aplikacji.

Autouzupełnianie (nowe) oparte na sesji z informacjami o miejscu (nowe)

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

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

Implementacja automatyczna
Używaj tokena sesji w żądaniach autouzupełniania (nowych). W żądaniu informacji o miejscu (nowych) dotyczących wybranej podpowiedzi uwzględnij te parametry:

1. Identyfikator miejsca z odpowiedzi Autouzupełniania (nowego).
2. Token sesji użyty w żądaniu Autouzupełniania (nowego).
3. Parametr fields określający potrzebne pola danych autouzupełniania (nowego).

Autouzupełnianie (nowe) na żądanie z Geocoding API

Zaimplementuj Autouzupełnianie (nowe) automatycznie bez tokenów sesji i wywołaj interfejs Geocoding API w przypadku wybranej podpowiedzi miejsca.
Geocoding API dostarcza adresy oraz współrzędne szerokości i długości geograficznej. Wykonanie 4 żądań autouzupełniania i wywołanie Geocoding API w przypadku wybranej podpowiedzi miejsca kosztuje mniej niż autouzupełnianie (nowe) na sesję.¹

Rozważ zastosowanie sprawdzonych metod dotyczących wydajności, aby ułatwić użytkownikom uzyskiwanie podpowiedzi, których szukają, przy użyciu jeszcze mniejszej liczby znaków.

Autouzupełnianie (nowe) oparte na sesjach w przypadku aplikacji, które korzystają tylko z adresów

Używaj autouzupełniania opartego na sesji (nowego) z informacjami o miejscu (nowymi).
Średnia liczba żądań, których oczekujesz, zanim użytkownik wybierze podpowiedź autouzupełniania (nowego), przekracza koszt rozliczania za sesję, dlatego Twoja implementacja autouzupełniania (nowego) powinna używać tokena sesji zarówno w przypadku żądań autouzupełniania (nowego), jak i powiązanych żądań informacji o miejscu (nowych) za sesję. ¹

Implementacja widżetu
Zarządzanie sesjami jest automatycznie wbudowane w widżety JavaScript, Android i iOS. Obejmuje to zarówno żądania autouzupełniania (nowe), jak i żądania dotyczące informacji o miejscu (nowe) w przypadku wybranej podpowiedzi. Pamiętaj, aby określić parametr fields, aby mieć pewność, że żądasz tylko tych pól, których potrzebujesz.

Implementacja automatyczna
Używaj tokena sesji w żądaniach autouzupełniania (nowych). Gdy prosisz o informacje o miejscu (nowe) dotyczące wybranej podpowiedzi, uwzględnij te parametry:

1. Identyfikator miejsca z odpowiedzi Autouzupełniania (nowego).
2. Token sesji użyty w żądaniu Autouzupełniania (nowego).
3. Parametr fields określający pola, takie jak adres i geometria.

Rozważ opóźnienie żądań autouzupełniania (nowa wersja)
Możesz zastosować strategie takie jak opóźnienie żądania autouzupełniania (nowa wersja), dopóki użytkownik nie wpisze pierwszych 3 lub 4 znaków, dzięki czemu aplikacja będzie wysyłać mniej żądań. Jeśli na przykład wysyłasz żądania Autouzupełniania (nowego) dla każdego znaku po wpisaniu przez użytkownika trzeciego znaku, oznacza to, że jeśli użytkownik wpisze 7 znaków, a następnie wybierze podpowiedź, dla której wysyłasz jedno żądanie do interfejsu Geocoding API, łączny koszt będzie obejmował 4 żądania Autouzupełniania (nowego) i żądanie do interfejsu Geocoding API¹.

Jeśli opóźnienie żądań może spowodować, że średnia liczba żądań automatycznych spadnie poniżej 4, możesz postępować zgodnie ze wskazówkami dotyczącymi implementacji wydajnego autouzupełniania (nowego) z interfejsem Geocoding API. Pamiętaj, że opóźnianie żądań może być postrzegane przez użytkownika jako opóźnienie, ponieważ może on oczekiwać podpowiedzi po każdym naciśnięciu klawisza.

Rozważ zastosowanie sprawdzonych metod dotyczących wydajności, aby pomóc użytkownikom uzyskać podpowiedź, której szukają, przy użyciu mniejszej liczby znaków.

Sprawdzone metody dotyczące skuteczności

Te wskazówki opisują sposoby optymalizacji wydajności autouzupełniania (nowego):

• Dodaj do implementacji Autouzupełniania (nowego) ograniczenia związane z krajem, ustawienia lokalizacji i (w przypadku implementacji automatycznych) ustawienia języka. Ustawienia języka nie są potrzebne w przypadku widżetów, ponieważ pobierają one ustawienia języka z przeglądarki lub urządzenia mobilnego użytkownika.
• Jeśli autouzupełnianiu (nowemu) towarzyszy mapa, możesz zmienić lokalizację według widocznego obszaru mapy.
• W sytuacjach, gdy użytkownik nie wybierze żadnej z podpowiedzi autouzupełniania (nowego), zwykle dlatego, że żadna z nich nie jest adresem, którego szuka, możesz ponownie użyć oryginalnych danych wejściowych użytkownika, aby spróbować uzyskać trafniejsze wyniki:
  • Jeśli oczekujesz, że użytkownik wpisze tylko informacje o adresie, użyj ponownie oryginalnych danych wejściowych użytkownika w wywołaniu interfejsu Geocoding API.
  • Jeśli spodziewasz się, że użytkownik będzie wpisywać zapytania dotyczące konkretnego miejsca według nazwy lub adresu, użyj żądania informacji o miejscu (nowego). Jeśli wyniki są oczekiwane tylko w określonym regionie, użyj ustawienia lokalizacji.
  Inne scenariusze, w których najlepiej jest użyć Geocoding API:
  • Użytkownicy wpisują adresy podlokali, 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 (nowym).
  • Użytkownicy wpisujący adresy z prefiksami segmentów dróg, np. „23-30 29th St, Queens” w Nowym Jorku lub „47-380 Kamehameha Hwy, Kaneohe” na wyspie Kauai na Hawajach.

Ustalanie lokalizacji na podstawie preferencji

Możesz ukierunkować wyniki na określony obszar, przekazując parametry location i radius. Dzięki temu autouzupełnianie (nowe) będzie 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 określonego przez parametry location i radius, dodając parametr locationRestriction. Dzięki temu autouzupełnianie (nowe) zwraca wyniki tylko 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 kliknij ikonę interfejsu API api.

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

3. Kliknij przycisk Wykonaj. W oknie wybierz konto, którego chcesz użyć do wysłania prośby.

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