Autouzupełnianie (nowość)

Wprowadzenie

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

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

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

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

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

Zwrócone prognozy miejsc są przeznaczone do wyświetlania użytkownikowi, aby ułatwić mu wybór zamierzonego miejsca. Możesz wysłać żądanie informacje 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 HTTP POST wysyłane na adres URL w formacie:

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

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

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

Obsługiwane parametry

Informacje o odpowiedzi

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

• Tablica suggestions zawiera wszystkie przewidywane miejsca i zapytania w kolejności określonej na podstawie ich trafności. Każde miejsce jest reprezentowane przez pole placePrediction, a każde zapytanie – przez pole queryPrediction.
• Pole placePrediction zawiera szczegółowe informacje o jednej prognozie miejsca, w tym identyfikator miejsca i opis tekstowy.
  • Aby lepiej dopasować dane wejściowe użytkownika podane w parametrze input, opis tekstowy prognozy 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 adres 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 zgodne z danymi wejściowymi użytkownika.
• Pole queryPrediction zawiera szczegółowe informacje o pojedynczej prognozie zapytania.

Pełny obiekt JSON ma postać:

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

Wymagane parametry

• dane wejściowe

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

Parametry opcjonalne

• FieldMask

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

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

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

  Użyj *, aby pobrać wszystkie pola.

    X-Goog-FieldMask: *

• 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 typ podstawowy może mieć wartość "mexican_restaurant" lub "steak_house".

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

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

  Ten parametr może też zawierać zamiast tego jeden z tych symboli: (regions) lub (cities). Kolekcja 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:

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

• includePureServiceAreaBusinesses

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

• includeQueryPredictions

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

• includedRegionCodes

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

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

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

• inputOffset

  Indeks znaku Unicode liczony od zera, który wskazuje pozycję kursora w polu input. Pozycja kursora może wpływać na zwracane prognozy. Jeśli to pole jest puste, domyślnie przyjmuje długość input.

• languageCode

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

  • Aby określić preferowany język, musisz użyć kodów języków IETF BCP-47.
  • Jeśli parametr languageCode nie zostanie podany, interfejs API użyje wartości określonej w nagłówku Accept-Language. Jeśli nie określisz żadnej z tych wartości, zostanie użyta wartość domyślna en. Jeśli podasz nieprawidłowy kod języka, interfejs API zwróci błąd INVALID_ARGUMENT.
  • Preferowany język ma niewielki wpływ na zestaw wyników, które interfejs API wybiera do zwrócenia, oraz na kolejność, w jakiej są one zwracane. Wpływa to również na możliwość poprawiania błędów ortograficznych przez interfejs API.
  • Prognozy miejsc są formatowane w różny sposób w zależności od danych wejściowych użytkownika w każdym żądaniu.
    • Najpierw wybierane są pasujące terminy w parametrze input, przy czym w miarę możliwości używane są nazwy zgodne z ustawieniem języka wskazanym przez parametr languageCode, a w pozostałych przypadkach – nazwy najlepiej pasujące do danych wejściowych użytkownika.
    • Nazwy miejsc mogą być formatowane przy użyciu nazw alternatywnych, aby pasowały do terminów 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 będą zgodne z terminami w parametrze input.
    • Wszystkie pozostałe adresy są zwracane w preferowanym języku po wybraniu pasujących terminów, które odpowiadają terminom w parametrze input. Jeśli nazwa nie jest dostępna w preferowanym języku, interfejs API użyje najbliższego dopasowania.

• locationBias lub locationRestriction

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

  • locationBias

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

  • locationRestriction

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

  Określ region locationBias lub locationRestriction jako prostokątny 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ścią domyślną jest 0,0. W przypadku locationRestriction musisz ustawić promień na wartość większą niż 0,0. W przeciwnym razie żądanie nie zwraca ż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 wysoki. Widoczny obszar jest uważany za zamknięty region, co oznacza, że obejmuje swoje granice. Zakres szerokości geograficznej musi mieścić się w przedziale od -90 do 90 stopni włącznie, a zakres długości geograficznej musi mieścić się w przedziale od -180 do 180 stopni włącznie:

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

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

    Na przykład ten widok 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, od którego należy obliczyć odległość w linii prostej do miejsca docelowego (zwracany jako distanceMeters). Jeśli ta wartość zostanie pominięta, odległość w linii prostej nie zostanie zwrócona. Musi być określony jako współrzędne szerokości i długości geograficznej:

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

• regionCode

  Kod regionu używany do formatowania odpowiedzi, określony jako 2-znakowa wartość ccTLD („domena najwyższego poziomu”). Większość kodów ccTLD jest identyczna z kodami ISO 3166-1, z kilkoma wyjątkami. Na przykład krajowa domena najwyższego poziomu Zjednoczonego Królestwa to „uk” (.co.uk), a kod ISO 3166-1 to „gb” (technicznie dla podmiotu „Zjednoczone Królestwo Wielkiej Brytanii i Irlandii Północnej”).

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

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

• sessionToken

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

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

Przykłady autouzupełniania (nowość)

Ograniczanie wyszukiwania do obszaru za pomocą parametru locationRestriction

locationRestriction określa obszar wyszukiwania. Wyniki spoza określonego obszaru nie są zwracane. W poniższym przykładzie używasz parametru locationRestriction, aby ograniczyć żądanie do okręgu o promieniu 5000 metrów wyśrodkowanego 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ć znaku locationRestriction, aby ograniczyć wyszukiwanie do prostokątnego widocznego obszaru. Poniższy przykład ogranicza żądanie do centrum San Francisco:

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

Wyniki są zawarte w tablicy suggestions:

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

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

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

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

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

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

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

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

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

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

Używanie parametru includedPrimaryTypes

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

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

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

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

Żądanie prognoz zapytań

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

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

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

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) w odpowiedzi umieści pole distanceMeters, które zawiera odległość w linii prostej od origin do miejsca docelowego. W tym przykładzie punkt początkowy jest ustawiony na środek San Francisco:

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

Odpowiedź zawiera teraz distanceMeters:

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

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

Poniższy przykład przedstawia żądanie Autocomplete (New) dotyczące firm, które zostaną otwarte w przyszłości w New Meadows w stanie 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 parametru distanceMeters, nawet jeśli w żądaniu jest parametr origin. Może się tak zdarzyć w tych sytuacjach:

• distanceMeters nie jest uwzględniana w prognozach route.
• distanceMeters nie jest uwzglę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, które próbują odczytać pole distanceMeters z przeanalizowanego obiektu, zwrócą pole o wartości 0. Aby nie wprowadzać użytkowników w błąd, nie wyświetlaj im odległości równej zero.

Optymalizacja autouzupełniania (nowość)

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

Oto kilka ogólnych wskazówek:

• Najszybszym sposobem na stworzenie działającego interfejsu użytkownika jest użycie widżetu autouzupełniania (nowego) z interfejsu 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.
• Poznaj najważniejsze pola danych autouzupełniania (nowość) od samego początku.
• Pola dotyczące preferowania lokalizacji i ograniczania lokalizacji są opcjonalne, ale mogą mieć znaczący wpływ na skuteczność autouzupełniania.
• Używaj obsługi błędów, aby zapewnić prawidłowe działanie aplikacji, gdy interfejs API zwróci błąd.
• Upewnij się, że aplikacja obsługuje sytuacje, w których użytkownik nie dokonał wyboru, i zapewnia mu możliwość kontynuowania.

Sprawdzone metody optymalizacji kosztów

Podstawowa optymalizacja kosztów

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

Zaawansowana optymalizacja kosztów

Rozważ programowe wdrożenie Autocomplete (New), aby uzyskać dostęp do SKU: Autocomplete Request pricing i wysyłać zapytania o wyniki interfejsu Geocoding API dotyczące wybranego miejsca zamiast informacji o miejscu (New). Cena za żądanie w połączeniu z interfejsem Geocoding API jest bardziej opłacalna niż cena za sesję (oparta 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, interfejs Geocoding API dostarczy te informacje za niższą cenę niż wywołanie interfejsu Place Details (New).
• Jeśli użytkownicy wybierają podpowiedź autouzupełniania średnio w 4 lub mniejszej liczbie żądań podpowiedzi autouzupełniania (nowych), cena za żądanie może być bardziej opłacalna niż cena za sesję.

Czy Twoja aplikacja wymaga innych informacji niż adres i szerokość/długość geograficzna wybranej prognozy?

Sprawdzone metody dotyczące wydajności

Poniższe wytyczne opisują sposoby optymalizacji skuteczności autouzupełniania (nowego):

• Dodaj do implementacji Autocomplete (New) ograniczenia związane z krajem, ustawienia lokalizacji i (w przypadku implementacji programowych) preferencje językowe. W przypadku widżetów nie trzeba określać preferencji językowych, ponieważ są one pobierane z przeglądarki lub urządzenia mobilnego użytkownika.
• Jeśli usłudze Autouzupełnianie (nowa) towarzyszy mapa, możesz określić lokalizację na podstawie widocznego obszaru mapy.
• 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 poda tylko informacje o adresie, użyj ponownie pierwotnych danych wejściowych użytkownika w wywołaniu interfejsu Geocoding API.
  • Jeśli oczekujesz, że użytkownik będzie wpisywać zapytania dotyczące konkretnego miejsca według nazwy lub adresu, użyj żądania informacji o miejscu (nowe). Jeśli wyniki mają być wyświetlane tylko w określonym regionie, użyj ustawień lokalizacji.
  Inne scenariusze, w których warto wrócić do Geocoding API:
  • użytkownicy wpisujący adresy podrzędne, np. adresy konkretnych lokali lub mieszkań w budynku; Na przykład czeski adres „Stroupežnického 3191/17, Praha” generuje częściową podpowiedź w autouzupełnianiu (nowym).
  • Użytkownicy wpisujący adresy z prefiksami odcinków dróg, np. „23–30 29th St, Queens” w Nowym Jorku lub „47–380 Kamehameha Hwy, Kaneohe” na wyspie Kauai na Hawajach.

Preferowanie lokalizacji

Aby zawęzić wyniki do określonego obszaru, przekaż parametr location i parametr radius. To polecenie informuje usługę Autocomplete (New), że ma preferować wyświetlanie wyników w określonym obszarze. Wyniki spoza zdefiniowanego obszaru mogą być nadal wyświetlane. Możesz użyć parametru 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 zdefiniowanego przez parametr location i radius, dodając parametr locationRestriction. To polecenie informuje interfejs Autocomplete (New), że ma zwracać tylko wyniki z tego regionu.

Wypróbuj

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

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

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

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

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