Widżet Autouzupełniania miejsc

Deweloperzy z Europejskiego Obszaru Gospodarczego (EOG)

Widżet autouzupełniania miejsc tworzy pole wprowadzania tekstu, wyświetla prognozy miejsc na liście wyboru interfejsu i zwraca szczegóły miejsca w odpowiedzi na wybór użytkownika. Użyj widżetu autouzupełniania miejsc, aby osadzić na stronie internetowej kompletny, samodzielny interfejs autouzupełniania.

Wymagania wstępne

Aby korzystać z funkcji automatycznego uzupełniania miejsc, musisz włączyć „Places API (new)” w projekcie Google Cloud. Więcej informacji znajdziesz w artykule Pierwsze kroki.

Nowości

Autouzupełnianie miejsc zostało ulepszone w tych obszarach:

  • Interfejs widżetu autouzupełniania obsługuje lokalizację regionalną (w tym języki pisane od prawej do lewej) w przypadku tekstu zastępczego w polu wprowadzania tekstu, logo listy prognoz i prognoz dotyczących miejsc.
  • Ulepszone ułatwienia dostępu, w tym obsługa czytników ekranu i interakcja za pomocą klawiatury.
  • Widżet autouzupełniania zwraca nową klasę Place, aby uprościć obsługę zwracanego obiektu.
  • Lepsza obsługa urządzeń mobilnych i małych ekranów.
  • Lepsza wydajność i lepszy wygląd graficzny.

Dodawanie widżetu autouzupełniania

Widżet autouzupełniania tworzy pole wpisywania tekstu, wyświetla prognozy miejsc na liście wyboru w interfejsie i zwraca szczegóły miejsca w odpowiedzi na kliknięcie użytkownika za pomocą słuchacza gmp-select. W tej sekcji dowiesz się, jak dodać widżet autouzupełniania do strony internetowej lub mapy Google.

Dodawanie widżetu autouzupełniania do strony internetowej

Aby dodać widżet autouzupełniania do strony internetowej, utwórz nowy element google.maps.places.PlaceAutocompleteElement i dołącz go do strony, jak pokazano w tym przykładzie:

TypeScript

// Request needed libraries.
(await google.maps.importLibrary('places')) as google.maps.PlacesLibrary;
// Create the input HTML element, and append it.
const placeAutocomplete = new google.maps.places.PlaceAutocompleteElement(
    {}
);
document.body.appendChild(placeAutocomplete);
index.ts

JavaScript

// Request needed libraries.
(await google.maps.importLibrary('places'));
// Create the input HTML element, and append it.
const placeAutocomplete = new google.maps.places.PlaceAutocompleteElement({});
document.body.appendChild(placeAutocomplete);
index.js

Zobacz pełny przykład kodu

Dodawanie widżetu autouzupełniania do mapy

Jeśli Twój adres rozliczeniowy znajduje się poza Europejskim Obszarem Gospodarczym, możesz też używać widżetu autouzupełniania z Mapą Google.

Aby dodać widżet autouzupełniania do mapy, utwórz nową instancję google.maps.places.PlaceAutocompleteElement, dołącz PlaceAutocompleteElement do div i dodaj ją do mapy jako niestandardowy element sterujący, jak pokazano w tym przykładzie:

TypeScript

// Get the inner map.
innerMap = mapElement.innerMap;
innerMap.setOptions({
    mapTypeControl: false,
});

// Use the bounds_changed event to restrict results to the current map bounds.
google.maps.event.addListener(innerMap, 'bounds_changed', async () => {
    placeAutocomplete.locationRestriction = innerMap.getBounds();
});
index.ts

JavaScript

// Get the inner map.
innerMap = mapElement.innerMap;
innerMap.setOptions({
    mapTypeControl: false,
});
// Use the bounds_changed event to restrict results to the current map bounds.
google.maps.event.addListener(innerMap, 'bounds_changed', async () => {
    placeAutocomplete.locationRestriction = innerMap.getBounds();
});
index.js

Zobacz pełny przykład kodu

Ograniczanie podpowiedzi autouzupełniania

Domyślnie usługa autouzupełniania miejsc wyświetla wszystkie typy miejsc, z większym prawdopodobieństwem wyświetlania prognoz w pobliżu lokalizacji użytkownika, i pobiera wszystkie dostępne pola danych dla wybranego przez użytkownika miejsca. Ustaw PlaceAutocompleteElementOptions, aby wyświetlać bardziej trafne prognozy, ograniczając lub faworyzując wyniki.

Ograniczenie wyników powoduje, że widżet autouzupełniania ignoruje wszystkie wyniki, które znajdują się poza obszarem ograniczenia. Często stosowaną praktyką jest ograniczenie wyników do granic mapy. W przypadku wyników z tendencją do odchylenia widżet autouzupełniania wyświetla wyniki w określonym obszarze, ale niektóre dopasowania mogą znajdować się poza tym obszarem.

Jeśli nie podasz żadnych granic ani widoku mapy, interfejs API spróbuje wykryć lokalizację użytkownika na podstawie jego adresu IP i dostosuje wyniki do tej lokalizacji. W miarę możliwości ustawiaj granice. W przeciwnym razie różni użytkownicy mogą otrzymywać różne prognozy. Aby ogólnie poprawić prognozy, ważne jest też podanie rozsądnego obszaru widoku, np. takiego, który ustawisz, przesuwając lub powiększając mapę, albo obszaru widoku ustawionego przez dewelopera na podstawie lokalizacji urządzenia i promienia. Jeśli promień nie jest dostępny, w przypadku funkcji autouzupełniania miejsca rozsądną wartością domyślną jest 5 km. Nie ustawiaj widocznego obszaru o zerowym promieniu (pojedynczy punkt), widocznego obszaru o średnicy zaledwie kilku metrów (mniej niż 100 m) ani widocznego obszaru obejmującego cały świat.

Ograniczanie wyszukiwania miejsc według kraju

Aby ograniczyć wyszukiwanie miejsc do co najmniej jednego konkretnego kraju, użyj właściwości includedRegionCodes do określenia kodów krajów, jak pokazano w tym fragmencie kodu:

const pac = new google.maps.places.PlaceAutocompleteElement({
  includedRegionCodes: ['us', 'au'],
});

Ograniczanie wyszukiwania miejsc do granic mapy

Aby ograniczyć wyszukiwanie miejsc do granic mapy, użyj właściwości locationRestrictions, aby dodać granice, jak pokazano w tym fragmencie kodu:

const pac = new google.maps.places.PlaceAutocompleteElement({
  locationRestriction: map.getBounds(),
});

Jeśli ograniczasz wyszukiwanie do granic mapy, dodaj odbiornik, który będzie aktualizować granice, gdy się zmienią:

map.addListener('bounds_changed', () => {
  autocomplete.locationRestriction = map.getBounds();
});

Aby usunąć locationRestriction, ustaw wartość null.

Odchylenia w wynikach wyszukiwania miejsc

Aby zawęzić wyniki wyszukiwania miejsc do obszaru w kształcie koła, użyj właściwości locationBias i podaj promień, jak pokazano poniżej:

const autocomplete = new google.maps.places.PlaceAutocompleteElement({
  locationBias: {radius: 100, center: {lat: 50.064192, lng: -130.605469}},
});

Aby usunąć locationBias, ustaw wartość null.

Ograniczanie wyników wyszukiwania miejsc do określonych typów

Możesz ograniczyć wyniki wyszukiwania miejsc do określonych typów miejsc, używając właściwości includedPrimaryTypes i określając co najmniej 1 typ, jak pokazano poniżej:

const autocomplete = new google.maps.places.PlaceAutocompleteElement({
  includedPrimaryTypes: ['establishment'],
});

Pełną listę obsługiwanych typów znajdziesz w tabelach A i B typów miejsc.

Pobieranie szczegółów miejsca

Aby uzyskać szczegóły wybranego miejsca, dodaj do elementu PlaceAutocompleteElement odbiornik gmp-select, jak pokazano w tym przykładzie:

TypeScript

// Add the gmp-placeselect listener, and display the results.
//prettier-ignore
//@ts-ignore
placeAutocomplete.addEventListener('gmp-select', async ({ placePrediction }) => {
    const place = placePrediction.toPlace();
    await place.fetchFields({ fields: ['displayName', 'formattedAddress', 'location'] });
    selectedPlaceTitle.textContent = 'Selected Place:';
    selectedPlaceInfo.textContent = JSON.stringify(
        place.toJSON(), /* replacer */ null, /* space */ 2);
});
index.ts

JavaScript

// Add the gmp-placeselect listener, and display the results.
//prettier-ignore
//@ts-ignore
placeAutocomplete.addEventListener('gmp-select', async ({ placePrediction }) => {
    const place = placePrediction.toPlace();
    await place.fetchFields({ fields: ['displayName', 'formattedAddress', 'location'] });
    selectedPlaceTitle.textContent = 'Selected Place:';
    selectedPlaceInfo.textContent = JSON.stringify(place.toJSON(), /* replacer */ null, /* space */ 2);
});
index.js

Zobacz pełny przykład kodu

W przykładzie powyżej detektor zdarzeń zwraca obiekt klasy Place. Zadzwoń pod numer place.fetchFields(), aby uzyskać pola danych szczegółów miejsca potrzebne w Twojej aplikacji.

W następnym przykładzie odbiornik wysyła prośbę o informacje o miejscu i wyświetla je na mapie.

TypeScript

// Add the gmp-placeselect listener, and display the results on the map.
  //prettier-ignore
  //@ts-ignore
  placeAutocomplete.addEventListener('gmp-select', async ({ placePrediction }) => {
    const place = placePrediction.toPlace();
    await place.fetchFields({
      fields: ['displayName', 'formattedAddress', 'location'],
    });

    // If the place has a geometry, then present it on a map.
    if (place.viewport) {
      innerMap.fitBounds(place.viewport);
    } else {
      innerMap.setCenter(place.location);
      innerMap.setZoom(17);
    }

    let content = document.createElement('div');
    let nameText = document.createElement('span');
    nameText.textContent = place.displayName;
    content.appendChild(nameText);
    content.appendChild(document.createElement('br'));
    let addressText = document.createElement('span');
    addressText.textContent = place.formattedAddress;
    content.appendChild(addressText);

    updateInfoWindow(content, place.location);
    marker.position = place.location;
  }
);
index.ts

JavaScript

// Add the gmp-placeselect listener, and display the results on the map.
//prettier-ignore
//@ts-ignore
placeAutocomplete.addEventListener('gmp-select', async ({ placePrediction }) => {
    const place = placePrediction.toPlace();
    await place.fetchFields({
        fields: ['displayName', 'formattedAddress', 'location'],
    });
    // If the place has a geometry, then present it on a map.
    if (place.viewport) {
        innerMap.fitBounds(place.viewport);
    }
    else {
        innerMap.setCenter(place.location);
        innerMap.setZoom(17);
    }
    let content = document.createElement('div');
    let nameText = document.createElement('span');
    nameText.textContent = place.displayName;
    content.appendChild(nameText);
    content.appendChild(document.createElement('br'));
    let addressText = document.createElement('span');
    addressText.textContent = place.formattedAddress;
    content.appendChild(addressText);
    updateInfoWindow(content, place.location);
    marker.position = place.location;
});
index.js

Zobacz pełny przykład kodu

Przykładowe mapy

Ta sekcja zawiera pełny kod przykładowych map przedstawionych na tej stronie.

Element autouzupełniania

W tym przykładzie do strony internetowej dodawany jest widżet autouzupełniania, a wyniki są wyświetlane dla każdego wybranego miejsca.

TypeScript

async function initMap(): Promise<void> {
    // Request needed libraries.
    (await google.maps.importLibrary('places')) as google.maps.PlacesLibrary;
    // Create the input HTML element, and append it.
    const placeAutocomplete = new google.maps.places.PlaceAutocompleteElement(
        {}
    );
    document.body.appendChild(placeAutocomplete);

    // Inject HTML UI.
    const selectedPlaceTitle = document.createElement('p');
    selectedPlaceTitle.textContent = '';
    document.body.appendChild(selectedPlaceTitle);

    const selectedPlaceInfo = document.createElement('pre');
    selectedPlaceInfo.textContent = '';
    document.body.appendChild(selectedPlaceInfo);

    // Add the gmp-placeselect listener, and display the results.
    //prettier-ignore
    //@ts-ignore
    placeAutocomplete.addEventListener('gmp-select', async ({ placePrediction }) => {
        const place = placePrediction.toPlace();
        await place.fetchFields({ fields: ['displayName', 'formattedAddress', 'location'] });
        selectedPlaceTitle.textContent = 'Selected Place:';
        selectedPlaceInfo.textContent = JSON.stringify(
            place.toJSON(), /* replacer */ null, /* space */ 2);
    });
}

initMap();
index.ts

JavaScript

async function initMap() {
    // Request needed libraries.
    (await google.maps.importLibrary('places'));
    // Create the input HTML element, and append it.
    const placeAutocomplete = new google.maps.places.PlaceAutocompleteElement({});
    document.body.appendChild(placeAutocomplete);
    // Inject HTML UI.
    const selectedPlaceTitle = document.createElement('p');
    selectedPlaceTitle.textContent = '';
    document.body.appendChild(selectedPlaceTitle);
    const selectedPlaceInfo = document.createElement('pre');
    selectedPlaceInfo.textContent = '';
    document.body.appendChild(selectedPlaceInfo);
    // Add the gmp-placeselect listener, and display the results.
    //prettier-ignore
    //@ts-ignore
    placeAutocomplete.addEventListener('gmp-select', async ({ placePrediction }) => {
        const place = placePrediction.toPlace();
        await place.fetchFields({ fields: ['displayName', 'formattedAddress', 'location'] });
        selectedPlaceTitle.textContent = 'Selected Place:';
        selectedPlaceInfo.textContent = JSON.stringify(place.toJSON(), /* replacer */ null, /* space */ 2);
    });
}
initMap();
index.js

CSS

/* 
 * Always set the map height explicitly to define the size of the div element
 * that contains the map. 
 */
#map {
    height: 100%;
}

/* 
 * Optional: Makes the sample page fill the window. 
 */
html,
body {
    height: 100%;
    margin: 0;
    padding: 0;
}

p {
    font-family: Roboto, sans-serif;
    font-weight: bold;
}

style.css

HTML

<html>
    <head>
        <title>Place Autocomplete element</title>

        <link rel="stylesheet" type="text/css" href="./style.css" />
        <script type="module" src="./index.js"></script>
    </head>
    <body>
        <p style="font-family: roboto, sans-serif">Search for a place here:</p>

        <!-- prettier-ignore -->
        <script>(g=>{var h,a,k,p="The Google Maps JavaScript API",c="google",l="importLibrary",q="__ib__",m=document,b=window;b=b[c]||(b[c]={});var d=b.maps||(b.maps={}),r=new Set,e=new URLSearchParams,u=()=>h||(h=new Promise(async(f,n)=>{await (a=m.createElement("script"));e.set("libraries",[...r]+"");for(k in g)e.set(k.replace(/[A-Z]/g,t=>"_"+t[0].toLowerCase()),g[k]);e.set("callback",c+".maps."+q);a.src=`https://maps.${c}apis.com/maps/api/js?`+e;d[q]=f;a.onerror=()=>h=n(Error(p+" could not load."));a.nonce=m.querySelector("script[nonce]")?.nonce||"";m.head.append(a)}));d[l]?console.warn(p+" only loads once. Ignoring:",g):d[l]=(f,...n)=>r.add(f)&&u().then(()=>d[l](f,...n))})
        ({key: "AIzaSyA6myHzS10YXdcazAFalmXvDkrYCp5cLc8", v: "weekly"});</script>
    </body>
</html>
index.html

Wypróbuj przykład

Mapa autouzupełniania

Ten przykład pokazuje, jak dodać widżet autouzupełniania do mapy Google.

TypeScript

const mapElement = document.querySelector('gmp-map') as google.maps.MapElement;
const placeAutocomplete = document.querySelector(
    'gmp-place-autocomplete'
) as google.maps.places.PlaceAutocompleteElement;
let innerMap;
let marker: google.maps.marker.AdvancedMarkerElement;
let infoWindow: google.maps.InfoWindow;
let center = { lat: 40.749933, lng: -73.98633 }; // New York City
async function initMap(): Promise<void> {
    // Request needed libraries.
    const [] = await Promise.all([
        google.maps.importLibrary('marker'),
        google.maps.importLibrary('places'),
    ]);

    // Get the inner map.
    innerMap = mapElement.innerMap;
    innerMap.setOptions({
        mapTypeControl: false,
    });

    // Use the bounds_changed event to restrict results to the current map bounds.
    google.maps.event.addListener(innerMap, 'bounds_changed', async () => {
        placeAutocomplete.locationRestriction = innerMap.getBounds();
    });

    // Create the marker and infowindow.
    marker = new google.maps.marker.AdvancedMarkerElement({
        map: innerMap,
    });

    infoWindow = new google.maps.InfoWindow({});

    // Add the gmp-placeselect listener, and display the results on the map.
    //prettier-ignore
    //@ts-ignore
    placeAutocomplete.addEventListener('gmp-select', async ({ placePrediction }) => {
      const place = placePrediction.toPlace();
      await place.fetchFields({
        fields: ['displayName', 'formattedAddress', 'location'],
      });

      // If the place has a geometry, then present it on a map.
      if (place.viewport) {
        innerMap.fitBounds(place.viewport);
      } else {
        innerMap.setCenter(place.location);
        innerMap.setZoom(17);
      }

      let content = document.createElement('div');
      let nameText = document.createElement('span');
      nameText.textContent = place.displayName;
      content.appendChild(nameText);
      content.appendChild(document.createElement('br'));
      let addressText = document.createElement('span');
      addressText.textContent = place.formattedAddress;
      content.appendChild(addressText);

      updateInfoWindow(content, place.location);
      marker.position = place.location;
    }
  );
}

// Helper function to create an info window.
function updateInfoWindow(content, center) {
    infoWindow.setContent(content);
    infoWindow.setPosition(center);
    infoWindow.open({
        map: innerMap,
        anchor: marker,
        shouldFocus: false,
    });
}

initMap();
index.ts

JavaScript

const mapElement = document.querySelector('gmp-map');
const placeAutocomplete = document.querySelector('gmp-place-autocomplete');
let innerMap;
let marker;
let infoWindow;
let center = { lat: 40.749933, lng: -73.98633 }; // New York City
async function initMap() {
    // Request needed libraries.
    const [] = await Promise.all([
        google.maps.importLibrary('marker'),
        google.maps.importLibrary('places'),
    ]);
    // Get the inner map.
    innerMap = mapElement.innerMap;
    innerMap.setOptions({
        mapTypeControl: false,
    });
    // Use the bounds_changed event to restrict results to the current map bounds.
    google.maps.event.addListener(innerMap, 'bounds_changed', async () => {
        placeAutocomplete.locationRestriction = innerMap.getBounds();
    });
    // Create the marker and infowindow.
    marker = new google.maps.marker.AdvancedMarkerElement({
        map: innerMap,
    });
    infoWindow = new google.maps.InfoWindow({});
    // Add the gmp-placeselect listener, and display the results on the map.
    //prettier-ignore
    //@ts-ignore
    placeAutocomplete.addEventListener('gmp-select', async ({ placePrediction }) => {
        const place = placePrediction.toPlace();
        await place.fetchFields({
            fields: ['displayName', 'formattedAddress', 'location'],
        });
        // If the place has a geometry, then present it on a map.
        if (place.viewport) {
            innerMap.fitBounds(place.viewport);
        }
        else {
            innerMap.setCenter(place.location);
            innerMap.setZoom(17);
        }
        let content = document.createElement('div');
        let nameText = document.createElement('span');
        nameText.textContent = place.displayName;
        content.appendChild(nameText);
        content.appendChild(document.createElement('br'));
        let addressText = document.createElement('span');
        addressText.textContent = place.formattedAddress;
        content.appendChild(addressText);
        updateInfoWindow(content, place.location);
        marker.position = place.location;
    });
}
// Helper function to create an info window.
function updateInfoWindow(content, center) {
    infoWindow.setContent(content);
    infoWindow.setPosition(center);
    infoWindow.open({
        map: innerMap,
        anchor: marker,
        shouldFocus: false,
    });
}
initMap();
index.js

CSS

/* 
 * Always set the map height explicitly to define the size of the div element
 * that contains the map. 
 */
gmp-map {
    height: 100%;
}

/* 
 * Optional: Makes the sample page fill the window. 
 */
html,
body {
    height: 100%;
    margin: 0;
    padding: 0;
}

.place-autocomplete-card {
    background-color: #fff;
    border-radius: 5px;
    box-shadow: rgba(0, 0, 0, 0.35) 0px 5px 15px;
    margin: 10px;
    padding: 5px;
    font-family: Roboto, sans-serif;
    font-size: large;
    font-weight: bold;
}

gmp-place-autocomplete {
    width: 300px;
}

#infowindow-content .title {
    font-weight: bold;
}

#map #infowindow-content {
    display: inline;
}

style.css

HTML

<html>
    <head>
        <title>Place Autocomplete map</title>

        <link rel="stylesheet" type="text/css" href="./style.css" />
        <script type="module" src="./index.js"></script>
        <!-- prettier-ignore -->
        <script>(g=>{var h,a,k,p="The Google Maps JavaScript API",c="google",l="importLibrary",q="__ib__",m=document,b=window;b=b[c]||(b[c]={});var d=b.maps||(b.maps={}),r=new Set,e=new URLSearchParams,u=()=>h||(h=new Promise(async(f,n)=>{await (a=m.createElement("script"));e.set("libraries",[...r]+"");for(k in g)e.set(k.replace(/[A-Z]/g,t=>"_"+t[0].toLowerCase()),g[k]);e.set("callback",c+".maps."+q);a.src=`https://maps.${c}apis.com/maps/api/js?`+e;d[q]=f;a.onerror=()=>h=n(Error(p+" could not load."));a.nonce=m.querySelector("script[nonce]")?.nonce||"";m.head.append(a)}));d[l]?console.warn(p+" only loads once. Ignoring:",g):d[l]=(f,...n)=>r.add(f)&&u().then(()=>d[l](f,...n))})
        ({key: "AIzaSyA6myHzS10YXdcazAFalmXvDkrYCp5cLc8", v: "weekly"});</script>
    </head>
    <body>
        <gmp-map center="40.749933,-73.98633" zoom="13" map-id="DEMO_MAP_ID">
            <div
                class="place-autocomplete-card"
                slot="control-inline-start-block-start">
                <p>Search for a place here:</p>
                <gmp-place-autocomplete></gmp-place-autocomplete>
            </div>
        </gmp-map>
    </body>
</html>
index.html

Wypróbuj przykład

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) w interfejsie Maps JavaScript API, widżetu autouzupełniania (nowego) w pakiecie SDK Miejsc na Androida lub widżetu autouzupełniania (nowego) w pakiecie 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.
  • Sprawdź, czy aplikacja obsługuje sytuacje, w których użytkownik nie dokonał wyboru, i czy oferuje mu możliwość kontynuowania.

Sprawdzone metody optymalizacji kosztów

Podstawowa optymalizacja kosztów

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

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 szczegółów miejsca (nowych). Ceny za żądanie w połączeniu z interfejsem Geocoding API są bardziej opłacalne niż ceny za sesję (oparte na sesjach), 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ą prognozę autouzupełniania w ramach średnio 4 lub mniej żądań prognoz autouzupełniania (nowych), cena za żądanie może być bardziej opłacalna niż cena za sesję.
Aby uzyskać pomoc w wyborze implementacji Autocomplete (nowa), która odpowiada Twoim potrzebom, kliknij kartę odpowiadającą Twojej odpowiedzi na to pytanie.

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

Tak, potrzebne są dodatkowe informacje

Używaj Autouzupełniania na podstawie sesji (nowość) z informacjami o miejscu (nowość).
Ponieważ Twoja aplikacja wymaga szczegółów miejsca (nowych), takich jak nazwa miejsca, status firmy lub godziny otwarcia, w implementacji autouzupełniania (nowego) należy używać tokena sesji (programowo lub wbudowanego w widżety JavaScript, Android lub iOS) na sesję oraz odpowiednich jednostek SKU Places, w zależności od tego, o które pola danych o miejscu prosisz.1

Implementacja widżetu
Zarządzanie sesją jest automatycznie wbudowane w widżety JavaScript, Android lub iOS. Obejmuje to zarówno żądania Autocomplete (New), jak i żądania Place Details (New) dotyczące wybranej prognozy. Pamiętaj, aby określić parametr fields, aby mieć pewność, że żądasz tylko potrzebnych pól danych autouzupełniania (nowego).

Implementacja programowa
W żądaniach autouzupełniania (nowego) używaj tokena sesji. Gdy wysyłasz żądanie szczegółów miejsca (nowe) dotyczące wybranej prognozy, uwzględnij te parametry:

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

Nie, wystarczy adres i lokalizacja

W zależności od skuteczności korzystania z funkcji Autocomplete (New) interfejs Geocoding API może być bardziej opłacalną opcją niż Place Details (New) w Twojej aplikacji. Skuteczność funkcji Autocomplete (New) w poszczególnych aplikacjach zależy od tego, co wpisują użytkownicy, gdzie aplikacja jest używana i czy wdrożono sprawdzone metody optymalizacji wydajności.

Aby odpowiedzieć na to pytanie, przeanalizuj, ile znaków użytkownik wpisuje średnio, zanim wybierze w aplikacji prognozę autouzupełniania (nową).

Czy użytkownicy wybierają prognozę autouzupełniania (nową) średnio w 4 lub mniejszej liczbie żądań?

Tak

Wdrażaj programowo funkcję Autocomplete (nową) bez tokenów sesji i wywołuj interfejs Geocoding API w przypadku wybranej prognozy miejsca.
Geocoding API dostarcza adresy oraz współrzędne szerokości i długości geograficznej. Wysłanie 4 żądań autouzupełniania i wywołanie interfejsu Geocoding API w przypadku wybranej podpowiedzi dotyczącej miejsca jest tańsze niż koszt autouzupełniania (nowego) na sesję.1

Rozważ zastosowanie sprawdzonych metod zwiększania wydajności, aby użytkownicy mogli uzyskać prognozę, której szukają, przy użyciu jeszcze mniejszej liczby znaków.

Nie

Używaj Autouzupełniania na podstawie sesji (nowość) z informacjami o miejscu (nowość).
Średnia liczba żądań, które prawdopodobnie wyślesz, zanim użytkownik wybierze prognozę autouzupełniania (nowego), przekracza koszt cen za sesję, więc w przypadku implementacji autouzupełniania (nowego) należy używać tokena sesji zarówno w przypadku żądań autouzupełniania (nowego), jak i powiązanego żądania szczegółów miejsca (nowego) za sesję. 1

Implementacja widżetu
Zarządzanie sesją jest automatycznie wbudowane w widżety JavaScript, Android i iOS. Obejmuje to zarówno żądania Autocomplete (New), jak i Place Details (New) w przypadku wybranej prognozy. Pamiętaj, aby określić parametr fields, aby mieć pewność, że żądasz tylko potrzebnych pól.

Implementacja programowa
W żądaniach autouzupełniania (nowego) używaj tokena sesji. Gdy wysyłasz żądanie szczegółów miejsca (nowe) dotyczące wybranej prognozy, uwzględnij te parametry:

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

Rozważ opóźnienie żądań Autocomplete (New)
Możesz zastosować strategie, takie jak opóźnienie żądania Autocomplete (New), dopóki użytkownik nie wpisze pierwszych 3–4 znaków, aby aplikacja wysyłała mniej żądań. Na przykład wysyłanie żądań autouzupełniania (nowego) dla każdego znaku po wpisaniu przez użytkownika trzeciego znaku oznacza, że jeśli użytkownik wpisze 7 znaków, a następnie wybierze prognozę, dla której wyślesz 1 żądanie do interfejsu Geocoding API, łączny koszt wyniesie 4 żądania autouzupełniania (nowego) + geokodowanie.1

Jeśli opóźnienie żądań może spowodować, że średnia liczba żądań programowych spadnie poniżej 4, możesz postępować zgodnie z instrukcjami dotyczącymi implementacji wydajnego interfejsu Autocomplete (nowego) z interfejsem Geocoding API. Pamiętaj, że opóźnianie żądań może być postrzegane przez użytkownika jako opóźnienie, ponieważ może on oczekiwać, że prognozy będą wyświetlane po każdym naciśnięciu klawisza.

Aby użytkownicy mogli uzyskać prognozę, której szukają, przy użyciu mniejszej liczby znaków, rozważ zastosowanie sprawdzonych metod dotyczących wydajności.

  1. Ceny znajdziesz w cennikach Google Maps Platform.

Sprawdzone metody dotyczące wydajności

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

  • Dodaj do implementacji Autocomplete (New) ograniczenia dotyczące kraju, 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.
  • Jeśli użytkownik nie wybierze żadnej z podpowiedzi Autocomplete (New), zwykle dlatego, że żadna z nich nie jest szukanym adresem, możesz ponownie użyć pierwotnego tekstu wpisanego przez użytkownika, aby uzyskać bardziej trafne wyniki:
    • Jeśli oczekujesz, że użytkownik wpisze 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 Szczegóły miejsca (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 usłudze Autouzupełnianie (nowa wersja).
    • 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 components, 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.