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 tekstowy Wyszukaj tekst i granice geograficzne, które określają obszar wyszukiwania.

Autouzupełnianie (nowe) może dopasowywać całe słowa i podciągi wejściowe, rozpoznając nazwy miejsc, adresy i kody plus. Aplikacje mogą więc wysyłać zapytania w trakcie wpisywania przez użytkownika, aby na bieżąco wyświetlać prognozy dotyczące miejsc i zapytań.

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

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

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ę 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 informacji o miejscu (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 POST HTTP 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 pojedynczej prognozie miejsca, w tym identyfikator miejsca i opis tekstowy.
  • Aby lepiej dopasować się do danych wejściowych użytkownika podanych w parametrze input, opis tekstowy prognozy dotyczącej 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 szczegółów miejsca 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 wejściowych użytkownika.
• Pole queryPrediction zawiera szczegółowe informacje o pojedynczej prognozie 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

  Ciąg tekstowy, w którym ma zostać przeprowadzone wyszukiwanie. Możesz podawać pełne słowa i podłańcuchy, nazwy miejsc, adresy i plus codes. 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, 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

  Użyj *, aby pobrać wszystkie pola.

    X-Goog-FieldMask: *

• includeFutureOpeningBusinesses

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

• includedPrimaryTypes

  Miejsce może mieć tylko jeden typ podstawowy z typów wymienionych w tabeli A lub tabeli B. Na przykład typem podstawowym 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 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 znaków: (regions) lub (cities). Kolekcja typu (regions) filtruje obszary lub podziały, takie jak dzielnice i kody pocztowe. Kolekcja typów (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 wartości (cities) lub (regions) określono dowolny typ.
  • Występują 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 wartość tego parametru to false, interfejs API zwraca tylko firmy z fizyczną lokalizacją.

• includeQueryPredictions

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

• includedRegionCodes

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

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

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

• inputOffset

  Indeks znaku Unicode liczony od zera, który wskazuje pozycję kursora w 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ż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 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 podasz żadnej z tych wartości, domyślną wartością będzie 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 zbiór wyników, które interfejs API wybiera do zwrócenia, oraz na kolejność, w jakiej są one zwracane. Wpływa to również na możliwość poprawiania błędów ortograficznych przez interfejs API.
  • Prognozy dotyczące miejsc są formatowane inaczej 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 ustawieniem języka wskazanym przez parametr languageCode, jeśli są dostępne, a w przeciwnym razie nazwy najlepiej pasujące do danych wprowadzonych przez 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 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 obie te wartości. locationRestriction oznacza region, w którym muszą się znajdować wyniki, a locationBias – 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 w pobliżu określonej lokalizacji, w tym wyniki poza określonym obszarem.

  • 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 okrąg.

  • Okrąg jest zdefiniowany 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 określony przez szerokość i długość geograficzną, reprezentowany przez 2 przeciwległe punkty low i wysokie. Widok jest uważany za obszar zamknięty, 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 obszar widoku obejmuje w całości 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. Musi być podana jako współrzędne szerokości i długości geograficznej:

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

• regionCode

  Kod regionu użyty do sformatowania 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 Wielkiej Brytanii 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ż 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. W zależności od obowiązujących przepisów parametr może wpływać na wyniki.

• sessionToken

  Tokeny sesji to generowane przez użytkownika ciągi znaków, które śledzą wywołania Autouzupełniania (nowego) jako „sesje”. Autouzupełnianie (nowe) 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 (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, 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 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ć locationRestriction, aby ograniczyć wyszukiwanie do prostokątnego obszaru widocznego. 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"
          ]
        }
      }
    ]
  }

Zawężanie wyszukiwania do określonego 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 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 pozycji, w tym wyniki spoza promienia 5000 m:

{
  "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 ukierunkować wyszukiwanie na prostokątny obszar widoku. 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 obszarze widoku pojawiają się w odpowiedzi, 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żyj parametru 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 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 typu, którego nie chcesz, np. "athletic_field".

Żądanie prognoz zapytań

Domyślnie nie są zwracane prognozy zapytań. 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 prognoza zapytania zawiera pole text z rekomendowanym ciągiem tekstowym wyszukiwania. Możesz wysłać żądanie Wyszukaj tekst (New), aby uzyskać więcej informacji o dowolnej zwróconej podpowiedzi zapytania.

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. Jeśli uwzględnisz origin, Autocomplete (New) 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

Ten przykład pokazuje żądanie Autocomplete (New) 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 elementu distanceMeters, nawet jeśli element origin jest uwzględniony w żądaniu. Może się tak zdarzyć w tych sytuacjach:

• distanceMeters nie jest uwzględniana w prognozach route.
• distanceMeters nie jest uwzględniana, gdy jej wartość wynosi 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 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 zero.

Optymalizacja autouzupełniania (nowa)

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

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 (nowego).
• 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ć koszty korzystania z usługi Autouzupełnianie (nowa wersja), użyj masek pól w widżetach informacje o miejscu (nowa wersja) i Autouzupełnianie (nowa wersja), aby zwracać tylko potrzebne pola danych Autouzupełniania (nowa wersja).

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 interfejsem Geocoding API są bardziej opłacalne niż ceny za sesję (oparte na sesji), jeśli spełnione są oba te warunki:

• Jeśli potrzebujesz tylko szerokości i długości geograficznej lub adresu wybranego miejsca użytkownika, Geocoding API dostarczy te informacje za niższą cenę niż wywołanie informacji o miejscu (New).
• Jeśli użytkownicy wybiorą podpowiedź autouzupełniania w ramach średnio 4 lub mniej żądań podpowiedzi autouzupełniania (nowych), ceny za żądanie mogą być bardziej opłacalne niż ceny 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 Autouzupełniania (nowego) ograniczenia związane z krajem, ustawienia lokalizacji i (w przypadku implementacji automatycznych) 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 usłudze Autocomplete (New) towarzyszy mapa, możesz określić lokalizację na podstawie widocznego obszaru mapy.
• W sytuacjach, gdy użytkownik nie wybierze żadnej z podpowiedzi autouzupełniania (nowego), zwykle dlatego, że żadna z nich nie jest szukanym adresem, możesz ponownie użyć pierwotnych danych wejściowych użytkownika, aby uzyskać bardziej trafne 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 informacji o miejscu (nowe). Jeśli wyniki są oczekiwane tylko w określonym regionie, użyj ustawiania 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” daje częściową podpowiedź w autouzupełnianiu (nowym).
  • 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. Dzięki temu autouzupełnianie (nowe) będzie preferować wyświetlanie wyników w zdefiniowanym 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 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 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 pełny ekran, aby rozwinąć okno narzędzia.