Autouzupełnianie (nowość)

Usługa autouzupełniania (nowa) to usługa internetowa, która zwraca prognozy miejsc i prognozy zapytań w odpowiedzi na żądanie HTTP. W żądaniu podaj ciąg tekstowy wyszukiwania i granice geograficzne, które kontrolują obszar wyszukiwania.

Usługa autouzupełniania (nowa) może dopasowywać pełne słowa i podłańcuchy danych wejściowych, rozpoznając nazwy miejsc, adresy i kody plus. Aplikacje mogą więc wysyłać zapytania w ramach typów użytkowników, aby dostarczać aktualne informacje o miejscach i zapytaniach.

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

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

Na przykład wywoływasz interfejs API, używając jako danych wejściowych ciągu, który zawiera część danych wejściowych użytkownika („piz sycylijski”) z obszarem wyszukiwania ograniczonym do San Francisco w Kalifornii. Odpowiedź zawiera listę podpowiedzi dotyczących miejsc, które pasują do wyszukiwanego hasła i obszaru wyszukiwania, np. restauracji „Pizzeria sycylijska” oraz szczegółowe informacje o miejscu.

Zwrócone prognozy dotyczące miejsc są wyświetlane użytkownikom, aby ułatwić im wybór odpowiedniego miejsca. Możesz wysłać żądanie Place Details (nowość), aby uzyskać więcej informacji o zwróconych prognozach miejsc.

Odpowiedź może też zawierać listę podpowiedzi zapytania, które pasują do wyszukiwanego ciągu i obszaru wyszukiwania, np. „Pizza sycylijska i makarony”. Każda prognoza zapytania w odpowiedzi zawiera pole text zawierające zalecany ciąg znaków wyszukiwania. Użyj tego ciągu jako danych wejściowych do wyszukiwania (nowego), aby przeprowadzić bardziej szczegółowe wyszukiwanie.

Żądania autouzupełniania (nowe)

Żądanie autouzupełniania (nowe) to żądanie HTTP POST kierowane do adresu URL w tym formularzu:

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

Przesyłanie prośby przy użyciu autouzupełniania (nowość)

Places API obsługuje istniejące interfejsy API autouzupełniania i autouzupełniania. Jeśli znasz te interfejsy API, nowa wersja testowa autouzupełniania wprowadza następujące zmiany:

  • Nowe autouzupełnianie korzysta z żądań POST HTTP. Przekazuj parametry w treści żądania lub w nagłówkach w ramach żądania POST HTTP. W przeciwieństwie do istniejących interfejsów API parametry adresu URL przekazujesz za pomocą żądania HTTP GET.
  • Nowe autouzupełnianie obsługuje jako mechanizm uwierzytelniania zarówno klucze interfejsu API, jak i tokeny OAuth.
  • Nowe autouzupełnianie obsługuje tylko format JSON jako format odpowiedzi.

W tabeli poniżej znajdziesz listę parametrów istniejących interfejsów API autouzupełniania i zapytań, które zostały zmienione lub zmodyfikowane pod kątem nowego autouzupełniania albo te, które nie są już obsługiwane.

Bieżący parametr Nowy parametr Uwagi
components includedRegionCodes
language languageCode
location locationBias
ipbias Jeśli pominiesz zarówno locationBias, jak i locationRestriction, interfejs API używa domyślnie promowania ze względu na adres IP.
offset inputOffset
radius locationBias lub locationRestriction
region regionCode
stricbounds locationRestriction
sessiontoken sessionToken
types includedPrimaryTypes

Limity wykorzystania

W wersji przedpremierowej możesz utworzyć maksymalnie 600 zapytań na minutę na projekt.

Opcje pomocy dotyczące wersji przedpremierowych

Google nie ma obowiązku zapewnienia pomocy w zakresie wersji przedpremierowych, funkcji ani funkcji Usług, jednak prośby na takich etapach rozpatrujemy indywidualnie.

  • Wersje przedpremierowe nie są objęte gwarancją jakości usług Google Maps Platform.
  • Zalecamy użycie mechanizmów zastępczych, zwłaszcza jeśli używasz wersji przedpremierowej w środowisku produkcyjnym. Przykłady sytuacji awaryjnych to: przekroczenie limitu, nieoczekiwane kody odpowiedzi i czas oczekiwania lub nieoczekiwane odpowiedzi w porównaniu z istniejącym autouzupełnianiem.

Możesz z niego korzystać, aby prosić o nowe funkcje lub sugerować modyfikacje dotychczasowych. Opisz konkretną funkcję, którą powinniśmy dodać, i podaj powód, dla którego uważasz, że jest ona ważna. Jeśli to możliwe, podaj szczegółowe informacje o swoim przypadku użycia i nowych możliwościach, jakie daje ta funkcja:

Jeśli masz inne pytania dotyczące funkcji, wyślij e-maila na adres newplacesapi@google.com.

Informacje o odpowiedzi

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

  • Tablica suggestions zawiera wszystkie przewidywane miejsca i zapytania w kolejności na podstawie 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 prognozie dotyczącej pojedynczego miejsca, w tym identyfikator miejsca i opis tekstowy.
  • Pole queryPrediction zawiera szczegółowe informacje o prognozie pojedynczego zapytania.

Pełny obiekt JSON ma postać:

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

Wymagane parametry

  • dane wejściowe

    Ciąg tekstowy służący do wyszukiwania. Podaj pełne słowa i podłańcuchy, nazwy miejsc, adresy i kody plus. Usługa autouzupełniania (nowa) zwraca kandydujące dopasowania na podstawie tego ciągu i porządkuje wyniki na podstawie ich postrzeganej trafności.

Parametry opcjonalne

  • includedPrimaryTypes

    Miejsce może mieć tylko jeden typ podstawowy z powiązanych z nim typów tabeli A lub tabeli B. Typem podstawowym może być na przykład "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 danym miejscem. Możesz ograniczyć wyniki do określonego typu głównego, przekazując parametr includedPrimaryTypes.

    Za pomocą tego parametru możesz określić maksymalnie 5 wartości typu z tabeli A lub tabeli B. Aby miejsce zostało uwzględnione w odpowiedzi, musi pasować do jednej z określonych wartości typu podstawowego.

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

    • Określono więcej niż 5 typów.
    • Podano nierozpoznane typy.

  • includeQueryPredictions

    Jeśli true, odpowiedź zawiera zarówno prognozy dotyczące miejsc, jak i zapytań. Wartość domyślna 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 w postaci tablicy zawierającej maksymalnie 15 dwuliterowych wartości ccTLD („domena najwyższego poziomu”). Jeśli zostanie pominięty, do odpowiedzi nie zostaną zastosowane żadne ograniczenia. Aby np. ograniczyć regiony do Niemiec i Francji:

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

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

  • inputOffset

    Przesunięcie znaku Unicode liczone od zera wskazujące pozycję kursora w input. Położenie kursora może mieć wpływ na zwracane prognozy. Jeśli pole jest puste, domyślnie przyjmuje długość input.

  • languageCode

    Preferowany język, w którym mają być zwracane wyniki. Wyniki mogą być w różnych językach, jeśli język używany w zasadzie input jest inny niż wartość określona przez atrybut languageCode lub jeśli dla zwracanego miejsca nie ma tłumaczenia z języka lokalnego na languageCode.

    • Aby określić preferowany język, musisz użyć kodów języka IETF BCP-47.
    • Jeśli nie podano languageCode, interfejs API używa wartości podanej w nagłówku Accept-Language. Jeśli nie podasz żadnej z nich, wartość domyślna to 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ść ich zwracania. Wpływa to również na możliwość poprawiania błędów pisowni przez interfejs API.
    • Interfejs API stara się podać adres, który jest czytelny zarówno dla użytkownika, jak i lokalnej populacji, a jednocześnie odzwierciedla dane wejściowe użytkownika. Prognozy dotyczące miejsc są formatowane w różny sposób 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 nazwami zgodnymi z preferencjami językowymi określonymi w parametrze languageCode (jeśli są dostępne) lub w innych przypadkach z nazwami najlepiej pasującymi do danych wejściowych użytkownika.
      • Adresy są formatowane w języku lokalnym, w miarę możliwości przy użyciu skryptu zrozumiałego dla użytkownika pod warunkiem, że pasujące hasła pasują do haseł w parametrze input.
      • Wszystkie inne adresy są zwracane w preferowanym języku, gdy pasujące hasła pasują 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 ograniczenie lokalizacji

    Aby określić obszar wyszukiwania, możesz użyć właściwości locationBias lub locationRestriction, ale nie obu naraz. locationRestriction to raczej region, w którym powinny znajdować się wyniki, a locationBias – region, w którym wyniki muszą znajdować się w pobliżu, ale mogą być poza tym obszarem.

    • locationBias

      Określa obszar wyszukiwania. Ta lokalizacja jest odchyleniem, 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 okrąg.

    • Okrąg jest określony 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 właściwości locationRestriction promień musisz ustawić 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 obejmujący szerokość i długość geograficzną wyrażony jako 2 położone na ukos kąty naprzeciwległe o boku low i najwyższego punktu. Widoczny obszar jest traktowany jako zamknięty obszar, co oznacza, że obejmuje swoją granicę. Granice szerokości geograficznej muszą mieścić się w zakresie od -90 do 90 stopni włącznie, a długość geograficzna – 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 180 stopni).
      • Jeśli low.longitude = -180 stopni, high.longitude = 180 stopni, widoczny obszar obejmuje wszystkie długości geograficzne.
      • Jeśli low.longitude = 180 stopni, high.longitude = -180 stopni, zakres długości geograficznej jest pusty.

      Musisz wypełnić zarówno pole low, jak i high, a reprezentowane pole nie może być puste. Pusty widoczny obszar powoduje wystąpienie błędu.

      Na przykład ten widoczny obszar w pełni 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 należy obliczyć odległość w linii prostej do miejsca docelowego (zwrócony jako distanceMeters). Jeśli pominiesz tę wartość, odległość w linii prostej nie zostanie zwrócona. Należy podać je 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 domen ccTLD jest identyczna z kodami ISO 3166-1 z kilkoma wyjątkami. Na przykład domena ccTLD w Wielkiej Brytanii to „uk” (.co.uk), a kod ISO 3166-1 to „gb” (technicznie oznaczający jednostkę „Wielka Brytania i Irlandia Północna”).

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

  • sessionToken

    Tokeny sesji to ciągi tekstowe generowane przez użytkownika, które śledzą (nowe) wywołania autouzupełniania jako „sesje”. Funkcja autouzupełniania (nowa) używa tokenów sesji do grupowania faz zapytania i wyboru autouzupełniania wyszukiwania użytkownika w oddzielną sesję na potrzeby rozliczeń. Więcej informacji znajdziesz w artykule o tokenach sesji.

Przykłady autouzupełniania (nowe)

Użyj ograniczeń lokalizacji i lokalizacji Biias

Do sterowania obszarem wyszukiwania interfejs API używa domyślnie promowania ze względu na adres IP. W przypadku promowania wyników ze względu na adres IP interfejs API korzysta z adresu IP urządzenia. Opcjonalnie możesz określić obszar wyszukiwania, używając właściwości locationRestriction lub locationBias, ale nie obu naraz.

locationRestriction określa obszar wyszukiwania. Wyniki spoza określonego obszaru nie są zwracane. W poniższym przykładzie użyjesz funkcji locationRestriction, aby ograniczyć żądanie do okręgu o promieniu 5000 metrów 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 znajdują się 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 służy do odchyleń, co oznacza, że zwracane są wyniki dotyczące wskazanej lokalizacji, w tym wyniki spoza określonego obszaru. W następnym przykładzie zmieniasz żądanie, aby użyć 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żywaj uwzględnionych typów Podstawowych

Parametr includedPrimaryTypes pozwala ograniczyć wyniki żądania do określonego typu, zgodnie z opisem w tabelach A i tabeli B. Możesz określić tablicę z maksymalnie 5 wartościami. W przypadku jego pominięcia zwracane są wszystkie typy.

W poniższym przykładzie określisz ciąg input „Piłka nożna” i użyjesz parametru includedPrimaryTypes, aby ograniczyć wyniki do instytucji 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 typu, którego nie potrzebujesz, np. "athletic_field".

Wysyłanie żądań prognoz zapytań

Prognozy zapytań nie są domyślnie zwracane. Aby dodać prognozy zapytań do odpowiedzi, 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 prognozy miejsc, jak i prognozy zapytań, tak jak to pokazano powyżej w sekcji Informacje o odpowiedzi. Każda prognoza zapytania zawiera pole text zawierające zalecany ciąg znaków wyszukiwania. Możesz utworzyć żądanie wyszukiwania tekstu (nowego), aby uzyskać więcej informacji o dowolnych zwróconych prognozach zapytań.

Użyj punktu początkowego

W tym przykładzie uwzględnij w żądaniu origin jako szerokość i długość geograficzną. Gdy uwzględnisz origin, interfejs API umieszcza w odpowiedzi pole distanceMeters, które zawiera odległość w linii prostej od miejsca origin do miejsca docelowego. Ten przykład ustawia początek lokalizacji w 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
      }
    }
  ]
}