הווידג'ט 'השלמה אוטומטית למקומות'

מפתחים באזור הכלכלי האירופי (EEA)

הווידג'ט של ההשלמה האוטומטית למקומות יוצר שדה להזנת טקסט, מספק הצעות למקומות ברשימת בחירה בממשק המשתמש ומחזיר פרטי מקום בתגובה לבחירת המשתמש. אתם יכולים להשתמש בווידג'ט השלמה אוטומטית למקומות כדי להטמיע בדף האינטרנט ממשק משתמש מלא ועצמאי להשלמה אוטומטית. למאמרי העזרה המלאים של ה-API, קראו את PlaceAutocompleteElement.

דרישות מוקדמות

כדי להשתמש בהשלמה אוטומטית למקומות, צריך להפעיל את Places API (חדש) בפרויקט ב-Google Cloud. פרטים נוספים מופיעים במאמר בנושא תחילת העבודה.

מה חדש

ההשלמה האוטומטית למקומות שופרה בדרכים הבאות:

  • ממשק המשתמש של הווידג'ט Autocomplete תומך בלוקליזציה אזורית (כולל שפות RTL), עבור ה-placeholder של קלט הטקסט, הלוגו של רשימת החיזויים והחיזויים של המקומות.
  • נגישות משופרת, כולל תמיכה בקוראי מסך ובאינטראקציה באמצעות המקלדת.
  • הווידג'ט "השלמה אוטומטית" מחזיר את המחלקה החדשה Place (הפניית Place) כדי לפשט את הטיפול באובייקט שמוחזר.
  • שיפור התמיכה במכשירים ניידים ובמסכים קטנים.
  • ביצועים טובים יותר ומראה גרפי משופר.

הוספת ווידג'ט של השלמה אוטומטית

הווידג'ט של ההשלמה האוטומטית יוצר שדה להזנת טקסט, מספק הצעות למקומות ברשימת בחירה בממשק המשתמש ומחזיר פרטי מקום בתגובה לקליק של המשתמש באמצעות המאזין gmp-select. בקטע הזה מוסבר איך להוסיף ווידג'ט של השלמה אוטומטית לדף אינטרנט או למפת Google.

הוספת ווידג'ט של השלמה אוטומטית לדף אינטרנט

כדי להוסיף את הווידג'ט של ההשלמה האוטומטית לדף אינטרנט, יוצרים google.maps.places.PlaceAutocompleteElement חדש ומוסיפים אותו לדף כמו בדוגמה הבאה:

TypeScript

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

JavaScript

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

דוגמה לקוד המלא

הוספת ווידג'ט של השלמה אוטומטית למפה

אם כתובת החיוב שלכם נמצאת מחוץ לאזור הכלכלי האירופי (EEA), אתם יכולים להשתמש בווידג'ט של ההשלמה האוטומטית גם במפת Google.

כדי להוסיף ווידג'ט של השלמה אוטומטית למפה, קודם צריך לשלוח בקשה לספריות הנדרשות, כמו שמוצג כאן:

// In your TS or JS, request the needed libraries.
const { PlaceAutocompleteElement } = await google.maps.importLibrary("places");

אחר כך, בקוד ה-HTML, מקננים רכיב gmp-place-autocomplete חדש בתוך div, ומקננים את div בתוך gmp-map, כמו בדוגמה הבאה:

<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">
        <gmp-place-autocomplete
            placeholder="Search for a place..."></gmp-place-autocomplete>
    </div>
</gmp-map>

כדי להוסיף ווידג'ט של השלמה אוטומטית למפה באופן פרוגרמטי, יוצרים מופע חדש של google.maps.places.PlaceAutocompleteElement, מוסיפים את PlaceAutocompleteElement ל-div ומחילים את המאפיין slot על div, כמו בדוגמה הבאה: 

// In your TS or JS, request the needed libraries.
const { PlaceAutocompleteElement } = await google.maps.importLibrary("places");

// Get the map element.
const mapElement = document.querySelector('gmp-map') as google.maps.MapElement;

// Create the PlaceAutocompleteElement instance.
const placeAutocomplete = new PlaceAutocompleteElement({});

// Create a div and append the PlaceAutocompleteElement to it.
const card = document.createElement("div");
card.appendChild(placeAutocomplete);

// Apply the slot attribute to the div.
// This positions the control in the top-left corner of the map.
card.setAttribute("slot", "control-inline-start-block-start");

// Append the div to the map element (check for null).
if (mapElement) {
    mapElement.appendChild(card);
}

דוגמה לקוד המלא

הוספת טקסט לדוגמה

כדי להוסיף טקסט לדוגמה, צריך להשתמש במאפיין placeholder. בדוגמה הבאה מוגדר טקסט לדוגמה ב-HTML:

<gmp-place-autocomplete
  placeholder="Search for a place..."
></gmp-place-autocomplete>

אפשר גם להגדיר את הטקסט לדוגמה באופן פרוגרמטי:

placeAutocomplete.placeholder = 'Search for a place...';

הגבלת ההצעות להשלמת החיפוש

כברירת מחדל, השלמה אוטומטית למקומות מציגה את כל סוגי המקומות, עם הטיה לחיזויים של מקומות קרובים למיקום של המשתמש, ומאחזרת את כל שדות הנתונים הזמינים של המקום שהמשתמש בחר. הגדרת PlaceAutocompleteElementOptions כדי להציג תחזיות רלוונטיות יותר, על ידי הגבלת התוצאות או הטיה שלהן.

הגבלת התוצאות גורמת לווידג'ט של ההשלמה האוטומטית להתעלם מתוצאות שנמצאות מחוץ לאזור המוגבל. שיטה נפוצה היא להגביל את התוצאות לגבולות המפה. הטיית התוצאות גורמת לווידג'ט ההשלמה האוטומטית להציג תוצאות בתוך האזור שצוין, אבל יכול להיות שחלק מההתאמות יהיו מחוץ לאזור הזה.

אם לא תספקו גבולות או אזור תצוגה של מפה, ה-API ינסה לזהות את מיקום המשתמש לפי כתובת ה-IP שלו, ויטה את התוצאות למיקום הזה. הגדירו גבולות כשזה אפשרי. אחרת, משתמשים שונים עשויים לקבל תחזיות שונות. כדי לשפר את התחזיות באופן כללי, חשוב לספק אזור תצוגה הגיוני, למשל אזור תצוגה שהוגדר על ידי הזזה או שינוי קנה מידה במפה, או אזור תצוגה שהוגדר על ידי מפתח על סמך מיקום המכשיר והרדיוס. אם לא מצוין רדיוס, ברירת המחדל הסבירה להשלמה אוטומטית למקומות היא 5 ק"מ. אל תגדירו אזור תצוגה עם רדיוס אפס (נקודה אחת), אזור תצוגה שרוחבו כמה מטרים בלבד (פחות מ-100 מטרים) או אזור תצוגה שמשתרע על פני כל העולם.

הגבלת חיפוש מקומות לפי מדינה

כדי להגביל את חיפוש המקומות למדינה ספציפית אחת או יותר, משתמשים במאפיין includedRegionCodes כדי לציין את קודי המדינות, כמו שמוצג בקטע הקוד הבא (ההנחה היא שכבר יצרתם מופע בשם placeAutocomplete):

placeAutocomplete.includedRegionCodes = ['us', 'au'];;

הגבלת החיפוש של מקומות לגבולות המפה

כדי להגביל את חיפוש המקומות לגבולות של מפה, משתמשים במאפיין locationRestriction. בקטע הקוד הבא אפשר לראות איך מוסיפים מאזין כדי לעדכן את הגבולות כשהם משתנים:

// 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();
});

כדי להסיר את locationRestriction, מגדירים אותו לערך null.

הטיית תוצאות חיפוש מקומות

כדי להטות את תוצאות החיפוש של מקומות לאזור מעגלי, משתמשים במאפיין locationBias, כמו שמוצג כאן:

placeAutocomplete.locationBias = {radius: 100, center: {lat: 40.749933, lng: -73.98633}};

כדי להסיר את locationBias, מגדירים אותו לערך null.

הגבלת תוצאות החיפוש של מקומות לסוגים מסוימים

כדי להגביל את תוצאות החיפוש של מקומות לסוגים מסוימים של מקומות, משתמשים במאפיין includedPrimaryTypes ומציינים סוג אחד או יותר, כמו שמוצג כאן:

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

לרשימה המלאה של הסוגים הנתמכים, ראו טבלאות א' וב' של סוגי מקומות.

קבלת פרטי המקום

כדי לקבל את פרטי המקום שנבחר, מוסיפים gmp-select listener ל-PlaceAutocompleteElement, כמו בדוגמה הבאה:

TypeScript

// Add the gmp-select listener, and display the results.
placeAutocomplete.addEventListener(
    'gmp-select',
    async ({
        placePrediction,
    }: google.maps.places.PlacePredictionSelectEvent) => {
        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
        );
    }
);

JavaScript

// Add the gmp-select listener, and display the results.
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
        );
    }
);

דוגמה לקוד המלא

בדוגמה הקודמת, רכיב event listener מקבל PlacePredictionSelectEvent וקורא ל-placePrediction.toPlace() כדי לקבל מופע של Place class (הפניה ל-Place). מפעילים את place.fetchFields() כדי לקבל את שדות הנתונים של Place Details שנדרשים לאפליקציה.

המאזין בדוגמה הבאה מבקש את השדות displayName,‏ formattedAddress,‏ location ו-viewport ב-place.fetchFields(), ואז משתמש ב-place.viewport עם fitBounds() כדי להציג את המקום שנבחר במפה.

TypeScript

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

        // 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);
        }

        const content = document.createElement('div');
        const nameText = document.createElement('span');
        nameText.textContent = place.displayName ?? 'No name';
        content.appendChild(nameText);
        content.appendChild(document.createElement('br'));
        const addressText = document.createElement('span');
        addressText.textContent = place.formattedAddress ?? 'No address';
        content.appendChild(addressText);

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

JavaScript

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

        // 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);
        }

        const content = document.createElement('div');
        const nameText = document.createElement('span');
        nameText.textContent = place.displayName ?? 'No name';
        content.appendChild(nameText);
        content.appendChild(document.createElement('br'));
        const addressText = document.createElement('span');
        addressText.textContent = place.formattedAddress ?? 'No address';
        content.appendChild(addressText);

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

דוגמה לקוד המלא

מפות לדוגמה

בקטע הזה מופיע הקוד המלא של מפות לדוגמה שמוצגות בדף הזה.

רכיב השלמה אוטומטית

בדוגמה הזו מוסיפים ווידג'ט של השלמה אוטומטית לדף אינטרנט, ומציגים את התוצאות לכל מקום שנבחר.

TypeScript

async function init(): Promise<void> {
    // Request needed libraries.
    const { PlaceAutocompleteElement } =
        await google.maps.importLibrary('places');
    // Create the input HTML element, and append it.
    const placeAutocomplete = new 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-select listener, and display the results.
    placeAutocomplete.addEventListener(
        'gmp-select',
        async ({
            placePrediction,
        }: google.maps.places.PlacePredictionSelectEvent) => {
            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
            );
        }
    );
}

void init();

JavaScript

async function init() {
    // Request needed libraries.
    const { PlaceAutocompleteElement } =
        await google.maps.importLibrary('places');
    // Create the input HTML element, and append it.
    const placeAutocomplete = new 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-select listener, and display the results.
    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
            );
        }
    );
}

void init();

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;
}

HTML

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

        <link rel="stylesheet" type="text/css" href="./style.css" />
        <script type="module" src="./index.js"></script>
        <script>
            // prettier-ignore
            (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: "GOOGLE_MAPS_API_KEY"
            });
        </script>
    </head>
    <body>
        <p style="font-family: roboto, sans-serif">Search for a place here:</p>
    </body>
</html>

מפת השלמה אוטומטית

בדוגמה הזו מוסבר איך להוסיף ווידג'ט של השלמה אוטומטית למפת Google.

TypeScript

const mapElement = document.querySelector('gmp-map')!;
const placeAutocomplete = document.querySelector('gmp-place-autocomplete')!;
let innerMap: google.maps.Map;
let marker: google.maps.marker.AdvancedMarkerElement;
let infoWindow: google.maps.InfoWindow;
async function init(): Promise<void> {
    // Request needed libraries.
    const [{ AdvancedMarkerElement }, { InfoWindow }] = await Promise.all([
        google.maps.importLibrary('marker'),
        google.maps.importLibrary('maps'),
        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.
    innerMap.addListener('bounds_changed', () => {
        placeAutocomplete.locationRestriction = innerMap.getBounds()!;
    });

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

    infoWindow = new InfoWindow();

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

            // 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);
            }

            const content = document.createElement('div');
            const nameText = document.createElement('span');
            nameText.textContent = place.displayName ?? 'No name';
            content.appendChild(nameText);
            content.appendChild(document.createElement('br'));
            const addressText = document.createElement('span');
            addressText.textContent = place.formattedAddress ?? 'No address';
            content.appendChild(addressText);

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

// Helper function to create an info window.
function updateInfoWindow(
    content: string | Element | Text | null | undefined,
    center: google.maps.LatLng | google.maps.LatLngLiteral | null | undefined
) {
    infoWindow.setContent(content);
    infoWindow.setPosition(center);
    infoWindow.open({
        map: innerMap,
        anchor: marker,
        shouldFocus: false,
    });
}

void init();

JavaScript

const mapElement = document.querySelector('gmp-map');
const placeAutocomplete = document.querySelector('gmp-place-autocomplete');
let innerMap;
let marker;
let infoWindow;
async function init() {
    // Request needed libraries.
    const [{ AdvancedMarkerElement }, { InfoWindow }] = await Promise.all([
        google.maps.importLibrary('marker'),
        google.maps.importLibrary('maps'),
        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.
    innerMap.addListener('bounds_changed', () => {
        placeAutocomplete.locationRestriction = innerMap.getBounds();
    });

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

    infoWindow = new InfoWindow();

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

            // 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);
            }

            const content = document.createElement('div');
            const nameText = document.createElement('span');
            nameText.textContent = place.displayName ?? 'No name';
            content.appendChild(nameText);
            content.appendChild(document.createElement('br'));
            const addressText = document.createElement('span');
            addressText.textContent = place.formattedAddress ?? 'No address';
            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,
    });
}

void init();

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: small;
}

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

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

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

HTML

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

        <link rel="stylesheet" type="text/css" href="./style.css" />
        <script type="module" src="./index.js"></script>
        <script>
            // prettier-ignore
            (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: "GOOGLE_MAPS_API_KEY"
            });
        </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">
                <gmp-place-autocomplete
                    placeholder="Search for a place..."></gmp-place-autocomplete>
            </div>
        </gmp-map>
    </body>
</html>

אופטימיזציה של השלמה אוטומטית (חדש)

בקטע הזה מתוארות שיטות מומלצות שיעזרו לכם להפיק את המקסימום משירות ההשלמה האוטומטית (החדש).

הנה כמה הנחיות כלליות:

שיטות מומלצות לאופטימיזציה של עלויות

אופטימיזציה בסיסית של עלויות

כדי להוזיל את עלות השימוש בשירות Autocomplete (חדש), אתם יכולים להשתמש במסכות שדות בווידג'טים של Place Details (חדש) ושל השלמה אוטומטית (חדש) כדי להחזיר רק את שדות הנתונים של ההשלמה האוטומטית (חדש) שאתם צריכים.

אופטימיזציה מתקדמת של עלויות

כדאי לשקול הטמעה פרוגרמטית של Autocomplete (חדש) כדי לגשת אל מק"ט: תמחור של בקשות להשלמה אוטומטית ולבקש תוצאות של Geocoding API לגבי המקום שנבחר במקום Place Details (חדש). התמחור לפי בקשה בשילוב עם Geocoding API הוא חסכוני יותר מהתמחור לפי סשן (מבוסס-סשן) אם מתקיימים שני התנאים הבאים:

  • אם אתם צריכים רק את קו הרוחב וקו האורך או את הכתובת של המקום שהמשתמש בחר, תוכלו לקבל את המידע הזה באמצעות Geocoding API במחיר נמוך יותר מאשר קריאה ל-Place Details (New).
  • אם המשתמשים בוחרים הצעת השלמה אוטומטית מתוך ממוצע של ארבע בקשות להצעות להשלמת החיפוש (חדש) או פחות, תמחור לפי בקשה יכול להיות משתלם יותר מתמחור לפי סשן.
כדי לבחור את שיטת ההטמעה של ההשלמה האוטומטית (חדש) שמתאימה לצרכים שלכם, בחרו את הכרטיסייה שמתאימה לתשובה שלכם לשאלה הבאה.

האם האפליקציה שלך דורשת מידע כלשהו מלבד הכתובת וקו הרוחב/קו האורך של החיזוי שנבחר?

כן, צריך עוד פרטים

שימוש בהשלמה אוטומטית (חדשה) מבוססת-סשן עם פרטי מקום (חדש).
מכיוון שהאפליקציה שלכם דורשת Place Details (חדש), כמו שם המקום, הסטטוס של העסק או שעות הפעילות, ההטמעה של ההשלמה האוטומטית (חדש) צריכה להשתמש בטוקן לסשן (באופן פרוגרמטי או מובנה בווידג'טים של JavaScript, Android או iOS) לכל סשן, בנוסף למק"טים הרלוונטיים של מקומות, בהתאם לשדות הנתונים של המקומות שאתם מבקשים.1

הטמעת ווידג'ט
ניהול הסשנים מובנה באופן אוטומטי בווידג'טים של JavaScript, Android, או iOS. החיוב כולל גם את הבקשות של ההשלמה האוטומטית (חדש) וגם את הבקשה של Place Details (חדש) לגבי החיזוי שנבחר. חשוב לציין את הפרמטר fields כדי לוודא שאתם מבקשים רק את שדות הנתונים של ההשלמה האוטומטית (חדש) שאתם צריכים.

הטמעה פרוגרמטית
משתמשים בטוקן לסשן בבקשות של ההשלמה האוטומטית (חדש). כשמבקשים Place Details (חדש) לגבי התחזית שנבחרה, צריך לכלול את הפרמטרים הבאים:

  1. מזהה המקום מהתשובה של Autocomplete (חדש)
  2. טוקן הסשן שמשמש בבקשה של ההשלמה האוטומטית (חדשה)
  3. הפרמטר fields שמציין את שדות הנתונים של Autocomplete (חדש) שאתם צריכים

לא, צריך רק כתובת ומיקום

יכול להיות ש-Geocoding API יהיה אפשרות חסכונית יותר מ-Place Details (חדש) לאפליקציה שלכם, בהתאם לביצועים של השימוש ב-Autocomplete (חדש). היעילות של ההשלמה האוטומטית (חדש) בכל אפליקציה משתנה בהתאם למה שהמשתמשים מזינים, איפה נעשה שימוש באפליקציה והאם הוטמעו שיטות מומלצות לאופטימיזציה של הביצועים.

כדי לענות על השאלה הבאה, צריך לנתח כמה תווים משתמש מקליד בממוצע לפני שהוא בוחר חיזוי של השלמה אוטומטית (חדשה) באפליקציה.

האם המשתמשים בוחרים חיזוי של השלמה אוטומטית (חדשה) בארבע בקשות או פחות, בממוצע?

כן

הטמעה פרוגרמטית של Autocomplete (חדש) ללא טוקנים של סשנים וקריאה ל-Geocoding API לגבי החיזוי של המקום שנבחר.
‫Geocoding API מספק כתובות וקואורדינטות של קווי רוחב ואורך. ביצוע ארבע בקשות Autocomplete ועוד קריאה ל-Geocoding API לגבי החיזוי של המקום שנבחר, עולה פחות מהעלות של כל סשן של Autocomplete (חדש).1

כדאי להשתמש בשיטות מומלצות לשיפור הביצועים כדי לעזור למשתמשים לקבל את התחזית שהם מחפשים גם אם הם מקלידים פחות תווים.

לא

שימוש בהשלמה אוטומטית (חדשה) מבוססת-סשן עם Place Details (חדש).
מכיוון שהמספר הממוצע של הבקשות שאתם צפויים לשלוח לפני שמשתמש בוחר חיזוי של השלמה אוטומטית (חדשה) חורג מהעלות של התמחור לכל סשן, ההטמעה של ההשלמה האוטומטית (חדשה) צריכה להשתמש בטוקן לסשן גם לבקשות של ההשלמה האוטומטית (חדשה) וגם לבקשות המשויכות של פרטי מקום (חדש) לכל סשן. 1

הטמעת ווידג'ט
ניהול הסשנים מובנה באופן אוטומטי בווידג'טים של JavaScript, Android או iOS. החיוב כולל גם את הבקשות של ההשלמה האוטומטית (חדש) וגם את הבקשה של Place Details (חדש) לגבי החיזוי שנבחר. חשוב לציין את הפרמטר fields כדי לוודא שאתם מבקשים רק את השדות שאתם צריכים.

הטמעה פרוגרמטית
משתמשים בטוקן סשן עם הבקשות של Autocomplete (חדש). כששולחים בקשה לקבלת פרטי מקום (חדש) לגבי החיזוי שנבחר, צריך לכלול את הפרמטרים הבאים:

  1. מזהה המקום מהתגובה של ההשלמה האוטומטית (חדש)
  2. טוקן הסשן שמשמש בבקשה של ההשלמה האוטומטית (חדשה)
  3. הפרמטר fields שמציין שדות כמו כתובת וגיאומטריה

כדאי לשקול לדחות בקשות של השלמה אוטומטית (חדשה)
אפשר להשתמש באסטרטגיות כמו דחיית בקשה של השלמה אוטומטית (חדשה) עד שהמשתמש יקליד את שלושת או ארבעת התווים הראשונים, כדי שהאפליקציה תשלח פחות בקשות. לדוגמה, אם שולחים בקשות של Autocomplete (New)‎ לכל תו אחרי שהמשתמש מקליד את התו השלישי, והמשתמש מקליד שבעה תווים ואז בוחר הצעה שאתם שולחים עבורה בקשה אחת של Geocoding API, העלות הכוללת תהיה עבור 4 בקשות של Autocomplete (New)‎ לפי בקשה + Geocoding.1

אם עיכוב הבקשות יכול להפחית את הממוצע של הבקשות הפרוגרמטיות לפחות מ-4, אתם יכולים לפעול לפי ההנחיות להטמעה של Autocomplete (חדש) עם Geocoding API. חשוב לזכור שעיכוב בבקשות יכול להיתפס כזמן אחזור על ידי המשתמש, שאולי מצפה לראות חיזויים בכל הקשה חדשה על מקש.

כדאי להשתמש בשיטות מומלצות לשיפור הביצועים כדי לעזור למשתמשים לקבל את התחזית שהם מחפשים בפחות תווים.

  1. למידע על העלויות, קראו את המחירונים של Google Maps Platform.

שיטות מומלצות לשיפור הביצועים

בהנחיות הבאות מתוארות דרכים לאופטימיזציה של הביצועים של ההשלמה האוטומטית (חדש):

  • מוסיפים הגבלות לפי מדינה, הטיה לפי מיקום והעדפת שפה (להטמעות פרוגרמטיות) להטמעה של Autocomplete (חדש). אין צורך בהעדפת שפה בווידג'טים, כי הם בוחרים את העדפות השפה מתוך הדפדפן או המכשיר הנייד של המשתמש.
  • אם ההשלמה האוטומטית (חדש) מלווה במפה, אתם יכולים להטות את המיקום לפי אזור התצוגה של המפה.
  • במצבים שבהם המשתמש לא בוחר באחת מההצעות של ההשלמה האוטומטית (חדש), בדרך כלל כי אף אחת מההצעות האלה היא לא הכתובת הרצויה, אתם יכולים להשתמש שוב בקלט המקורי של המשתמש כדי לנסות לקבל תוצאות רלוונטיות יותר:
    • אם אתם מצפים שהמשתמש יזין רק פרטי כתובת, תוכלו להשתמש מחדש בקלט המקורי של המשתמש בקריאה ל-Geocoding API.
    • אם אתם מצפים שהמשתמש יזין שאילתות לגבי מקום ספציפי לפי שם או כתובת, תשתמשו בבקשה של Place Details (חדש). אם אתם מצפים לתוצאות רק באזור מסוים, אתם יכולים להשתמש בהטיה לפי מיקום.
    תרחישים נוספים שבהם מומלץ לחזור ל-Geocoding API כוללים:
    • משתמשים שמזינים כתובות של יחידות משנה, כמו כתובות של יחידות או דירות ספציפיות בתוך בניין. לדוגמה, הכתובת בצ'כיה "Stroupežnického 3191/17, Praha" מניבה חיזוי חלקי בהשלמה האוטומטית (החדשה).
    • משתמשים שמזינים כתובות עם קידומות של קטע רחוב כמו '23-30 29th St, Queens' בניו יורק או '47-380 Kamehameha Hwy, Kaneohe' באי קוואי בהוואי.

הטיית מיקום

כדי להטות את התוצאות לאזור מסוים, מעבירים פרמטר location ופרמטר radius. ההגדרה הזו מנחה את ההשלמה האוטומטית (חדש) להעדיף להציג תוצאות בתוך האזור שהוגדר. יכול להיות שיוצגו תוצאות מחוץ לאזור שהוגדר. אפשר להשתמש בפרמטר includedRegionCodes כדי לסנן את התוצאות כך שיוצגו רק המקומות במדינה מסוימת.

הגבלת מיקום

כדי להגביל את התוצאות לאזור מסוים, מעבירים פרמטר locationRestriction.

אפשר גם להגביל את התוצאות לאזור שמוגדר על ידי location ופרמטר radius, על ידי הוספת הפרמטר locationRestriction. ההוראה הזו גורמת ל-Autocomplete (חדש) להחזיר רק תוצאות באזור הזה.