Autouzupełnianie (nowość)

Wybierz platformę: Android iOS JavaScript Usługa internetowa

Usługa autouzupełniania (nowa) to usługa sieciowa, która zwraca miejsca w odpowiedzi na żądania HTTP. W żądaniu wpisz tekst ciąg znaków i granice geograficzne, które kontrolują obszar wyszukiwania.

Funkcja autouzupełniania (nowa) może uwzględniać pełne słowa oraz podłańcucha danych wejściowych, rozpoznawanie nazw miejsc, adresów i kodów plus. W związku z tym aplikacje mogą wysyłać zapytań wprowadzanych przez użytkownika, zapewniając błyskawiczne wyniki i prognozy zapytań.

Odpowiedź z interfejsu API autouzupełniania (nowego) może zawierać 2 typy prognoz:

  • Przewidywane miejsca: miejsca, takie jak firmy, adresy i punkty. na podstawie podanego ciągu tekstowego i obszaru wyszukiwania. Prognozy miejsc są zwracanych domyślnie.
  • Prognozy zapytań: ciągi zapytań pasujące do wejściowego ciągu tekstowego oraz obszar wyszukiwania. Prognozy zapytań nie są domyślnie zwracane. Użyj Parametr żądania includeQueryPredictions, który pozwala dodać prognozy zapytań do funkcji .

Na przykład wywołujesz interfejs API, używając jako danych wejściowych ciągu znaków zawierającego częściowe dane wejściowe użytkownika, „Pizza sycylijska” z obszarem wyszukiwania ograniczonych do San Francisco, Kalifornia. Odpowiedź zawiera wtedy listę przewidywanych miejsc, które pasują do wyszukiwanego ciągu i obszaru wyszukiwania, na przykład „Sycylijska pizza kulinarna” wraz z dodatkowymi informacjami o tym miejscu.

Zwrócone prognozy dotyczące miejsc mają zostać przedstawione użytkownikowi jako pomocne ich przy wyborze odpowiedniego miejsca. Możesz Szczegóły miejsca (nowe) żądania uzyskania dodatkowych informacji o dowolnym ze zwróconych prognoz dotyczących miejsc.

Odpowiedź może też zawierać listę prognoz zapytania, które pasują do zapytania ciągu wyszukiwania i obszaru wyszukiwania, np. „Pizza sycylijska Makaron”. Każda prognoza zapytania w kolumnie odpowiedź zawiera pole text zawierające zalecany ciąg wyszukiwania tekstowego. Użyj jako danych wejściowych w celu Wyszukiwanie tekstowe (nowość) aby przeprowadzić bardziej szczegółowe wyszukiwanie.

API Explorer umożliwia wysyłanie żądań na żywo, dzięki czemu możesz zapoznać się z interfejsem API Opcje interfejsu API:

Wypróbuj

Żądania autouzupełniania (nowe)

Nowe (nowe) żądanie autouzupełniania to żądanie HTTP POST wysyłane do adresu URL w formularz:

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

Przekazuj 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

Informacje o odpowiedzi

Autouzupełnianie (nowe) zwraca w odpowiedzi obiekt JSON. W odpowiedzi:

  • Tablica suggestions zawiera wszystkie prognozowane miejsca i zapytania w kolejności na podstawie ich postrzeganej trafności. Każde miejsce jest reprezentowane przez pole placePrediction i uwzględniane jest każde zapytanie pole queryPrediction.
  • Pole placePrediction zawiera szczegółowe informacje o jednym przewidywane miejsce, w tym identyfikator miejsca i opis.
  • Pole queryPrediction zawiera szczegółowe informacje o jednym w prognozie zapytania.
.

Pełny obiekt JSON ma następujący format:

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

  • dane wejściowe

    Ciąg tekstowy, który ma być przeszukiwany. określać pełne słowa i podłańcuchy; nazwy miejsc, adresy i kody plus. Usługa autouzupełniania (nowa) zwraca dopasowania kandydatów na podstawie tego ciągu i ustala kolejność wyników na podstawie ich postrzeganej trafności.

Parametry opcjonalne

  • includedPrimaryTypes

    Miejsce może mieć tylko jeden typ główny spośród typów wymienionych w Tabela A lub Tabela B. Przykład: typ podstawowy to "mexican_restaurant" lub "steak_house".

    Domyślnie interfejs API zwraca wszystkie miejsca na podstawie parametru input, niezależnie od tego podstawowego typu powiązanego z miejscem. Ogranicz wyniki, aby miały określoną wartość podstawowych lub głównych, przekazując parametr includedPrimaryTypes.

    Za pomocą tego parametru możesz określić maksymalnie 5 wartości typów z tabeli A lub Tabela B. Miejsce musi pasują do jednej z określonych wartości typu podstawowego, które mają być uwzględnione w odpowiedzi.

    Ten parametr może też zawierać wartość (regions) lub (cities). Kolekcja typu (regions) filtruje obszary lub okręgi, np. dzielnice i kody pocztowe. Zbiór typu (cities) filtruje miejsca, które Google identyfikuje jako miasto.

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

    • Określono więcej niż 5 typów.
    • Oprócz (cities) i (regions) jest określony każdy typ.
    • Wszystkie nierozpoznane typy są określone.
    .

  • includeQueryPredictions

    Jeśli parametr ma wartość true, odpowiedź zawiera zarówno prognozy dotyczące miejsc, jak i zapytań. Domyślny wartość to false, co oznacza, że odpowiedź zawiera tylko prognozy dotyczące miejsc.

  • includedRegionCodes

    Uwzględnij tylko wyniki z listy określonych regionów, określonej jako tablica do 15 znaków ccTLD („domena najwyższego poziomu”) dwuznakowych. Jeśli go pominiesz, do odpowiedzi nie będą stosowane żadne ograniczenia. Przykład: aby ograniczyć regiony do Niemiec i Francji:

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

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

  • inputOffset

    Przesunięcie znaków Unicode liczone od zera, które wskazuje pozycję kursora w polu input. Pozycja kursora może wpływać na wyświetlane podpowiedzi. Jeśli jest pusta, stosowana jest domyślna wartość o długości 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 jest inny niż wartość określona przez languageCode lub jeśli zwrócone miejsce nie ma tłumaczenia z z języka lokalnego na languageCode.

    • Musisz użyć interfejsu IETF kody języków BCP-47, aby określić preferowany język.
    • Jeśli nie podano languageCode, interfejs API używa wartości określonej w parametrze 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 błąd.
    • Preferowany język ma niewielki wpływ na zestaw wyników, które zwracany przez interfejs API i kolejność ich zwrócenia. Dotyczy to również możliwości poprawiania błędów pisowni przez interfejs API.
    • Interfejs API stara się dostarczyć adres, który będzie czytelny zarówno dla użytkownika, jak i lokalnej populacji, odzwierciedlając jednocześnie dane wejściowe użytkownika. Prognozy miejsc są formatować się różnie w zależności od danych wejściowych użytkownika w każdym żądaniu.
      • Pasujące hasła w parametrze input są wybierane jako pierwsze z wyrównaniem nazw z preferowanym językiem wskazanym przez parametr languageCode, gdy pod względem ich dostępności, jednak w innych przypadkach używa się nazw najlepiej pasujących do danych wejściowych użytkownika.
      • Adresy muszą być sformatowane w lokalnym języku, a alfabet zrozumiały dla użytkownika. tylko po wybraniu pasujących haseł pasujących do haseł w input.
      • Pozostałe adresy są zwracane w preferowanym języku, a pasujące hasła mają został wybrany tak, aby pasował do haseł w parametrze input. Jeśli nazwa nie jest dostępny w preferowanym języku, interfejs API używa najbliższego dopasowania.

  • Promowanie lokalizacji lub ograniczenie związane z lokalizacją

    Możesz wybrać locationBias lub locationRestriction, ale nie jednocześnie, aby zdefiniować obszar wyszukiwania. Traktuj locationRestriction jako określenie region, w którym muszą się znajdować wyniki, oraz locationBias jako określenie regionu, w którym wyniki muszą znajdować się w pobliżu, ale mogą się znajdować poza regionem. w pobliżu.

    • locationBias

      Określa obszar wyszukiwania. Ta lokalizacja działa dyskryminująco, co oznacza, że wyniki dotyczące określonej lokalizacji, w tym wyniki poza określonym obszarem.

    • locationRestriction

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

    Określ region locationBias lub locationRestriction jako prostokątnego widocznego obszaru lub okręgu.

    • Okrąg jest wyznaczany przez punkt środkowy i promień w metrach. Promień musi się mieścić w zakresie między 0,0 i 50000,0 włącznie. Wartością domyślną jest 0,0. W przypadku usługi locationRestriction, musisz ustawić promień na wartość większą niż 0,0. W przeciwnym razie żądanie zwraca Brak wyników.

      Na przykład:

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

    • Prostokąt to widoczny obszar o długości i szerokości szerokości geograficznej, reprezentowany przez dwa elementy. na przekątnej low i najwyższych punktach. Widoczny obszar jest uważany za obszar zamknięty, co oznacza, że obejmuje jego granicę. Granice szerokości geograficznej musi mieścić się w przedziale od -90 do 90 stopni włącznie i musi mieścić się w granicach długości geograficznej musi mieścić się w zakresie od -180 do 180 stopni włącznie:

      • 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 przecina 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.

      Musisz wypełnić zarówno pola low, jak i high, a także reprezentowane pole. nie może być pusta. Gdy to zrobisz, pojawi się 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, z którego ma zostać obliczona bezpośrednia odległość do miejsce docelowe (zwrócone jako distanceMeters). Jeśli ta wartość to zostanie pominięty, odległość wprost nie zostanie zwrócona. Wartość musi być określona jako współrzędne geograficzne:

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

  • regionCode

    Kod regionu używany do formatowania odpowiedzi podany jako ccTLD („domena najwyższego poziomu”) dwuznakową. Większość kodów ccTLD jest identyczna z kodami ISO 3166-1. z kilkoma istotnymi wyjątkami. Na przykład domena ccTLD Wielkiej Brytanii to „uk” (co.uk), natomiast kod ISO 3166-1 to „gb”. (technicznie dla funkcji podmiotu „Wielkiej Brytanii i Irlandii Północnej”).

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

  • sessionToken

    Tokeny sesji to generowane przez użytkownika ciągi znaków, które śledzą autouzupełnianie (Nowe) jako „sesje”. Autouzupełnianie (nowość) korzysta z tokenów sesji do Pogrupować fazy zapytania i wyboru wyszukiwania autouzupełniania przez użytkownika w oddzielną sesję w celach rozliczeniowych. Więcej informacji: Tokeny sesji.

Przykłady autouzupełniania (nowe)

Używanie ograniczeń lokalizacji i uprzedzeń według lokalizacji

Do kontroli obszaru wyszukiwania interfejs API wykorzystuje domyślnie promowanie adresów IP. W przypadku promowania ze względu na adres IP interfejs API korzysta z metody Adres IP urządzenia, aby zniekształcać wyniki. Opcjonalnie możesz użyć parametru locationRestriction lub locationBias (ale nie obie te opcje), aby określić obszar wyszukiwania.

locationRestriction określa obszar do przeszukania. Wyniki poza określonym obszarem nie są zwracane. W poniższym przykładzie używasz locationRestriction do ograniczenia do okręgu o promieniu 5000 metrów ze środkiem wyśrodkowanym na San Francisco:

curl -X POST -d '{
  "input": "Amoeba",
  "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/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",
          "store",
          "point_of_interest",
          "electronics_store"
        ]
      }
    }
  ]
}

W przypadku funkcji locationBias lokalizacja działa jako stronniczość, czyli wyniki w okolicy można zwrócić określoną lokalizację, łącznie z wynikami spoza określonego obszaru. W ciągu następnych na przykład zmień żądanie tak, aby używało locationBias:

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"
        ]
      }
    },
    ...
  ]
}

Użyj uwzględnionych podstawowych typów

Parametr includedPrimaryTypes umożliwia określenie maksymalnie 5 typów wartości z zakresu Tabela A Tabela B, albo tylko (regions) lub tylko (cities). Miejsce musi pasować do jednego z podanych podstawowych wartości typów, które mają być uwzględnione w odpowiedzi.

W poniższym przykładzie określasz ciąg input „Piłka nożna” i użyj parametru includedPrimaryTypes, aby ograniczyć wyniki do instytucje 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ć instytucje wybranego typu, takich jak "athletic_field".

Żądanie prognoz zapytań

Prognozy zapytań nie są domyślnie zwracane. Użyj funkcji includeQueryPredictions żądania, 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 miejsc, jak i prognozy zapytań jak pokazano powyżej w sekcji Informacje o odpowiedzi. Każda prognoza zapytania zawiera pole text zawierające zalecany ciąg wyszukiwania tekstowego. Możesz Wyszukiwanie tekstowe (nowość) żądania, aby uzyskać więcej informacji o dowolnym ze zwróconych prognoz zapytań.

Użyj punktu początkowego

W tym przykładzie uwzględnij w żądaniu parametr origin jako szerokość i długość geograficzną. Jeśli użyjesz właściwości origin, interfejs API uwzględni pole distanceMeters w polu odpowiedź zawierającą prostą odległość od miejsca docelowego (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
      }
    }
  ]
}

Wypróbuj

API Explorer umożliwia wysyłanie przykładowych żądań, aby zapoznać się z interfejsem API i jego opcjami.

  1. Kliknij ikonę interfejsu API Rozwiń interfejs API Explorer.. w prawej części strony.
  2. Opcjonalnie rozwiń opcję Pokaż parametry standardowe i ustaw parametr fields do maski pola.
  3. Opcjonalnie edytuj Treść żądania.
  4. Kliknij przycisk Wykonaj. W wyskakującym okienku wybierz konto, z którego chcesz przesłać prośbę.

  5. W panelu Eksplorator API kliknij ikonę rozwijania. Rozwiń interfejs API Explorer., aby rozwinąć okno Eksploratora interfejsów API.