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

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

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

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

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

מה חדש

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

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

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

הווידג'ט Autocomplete יוצר שדה להזנת טקסט, מספק הצעות למקומות ברשימת בחירה בממשק המשתמש ומחזיר פרטי מקום בתגובה לקליק של המשתמש באמצעות המאזין 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'],
});

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

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

כדי לקבל את Place Details עבור המקום שנבחר, מוסיפים listener מסוג gmp-select אל 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 ). מפעילים את 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 (חדש) כדי להחזיר רק את שדות הנתונים של Autocomplete (חדש) שאתם צריכים.

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

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

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

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

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

השלמה אוטומטית מבוססת-סשן (חדש) עם Place Details (חדש)

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

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

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

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

השלמה אוטומטית (חדשה) לכל בקשה באמצעות Geocoding API

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

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

השלמה אוטומטית (חדשה) מבוססת-סשן לאפליקציות של כתובות בלבד

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

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

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

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

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

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

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

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

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

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

  • מוסיפים להטמעה של ההשלמה האוטומטית (חדש) הגבלות לפי מדינה, הטיית מיקום והעדפת שפה (להטמעות פרוגרמטיות). אין צורך בהעדפת שפה בווידג'טים, כי הם בוחרים את העדפות השפה מהדפדפן או מהמכשיר הנייד של המשתמש.
  • אם ההשלמה האוטומטית (חדש) מלווה במפה, אתם יכולים להטות את המיקום לפי אזור התצוגה של המפה.
  • במקרים שבהם המשתמש לא בוחר באחת מההצעות של ההשלמה האוטומטית (חדש), בדרך כלל כי אף אחת מההצעות האלה היא לא הכתובת הרצויה, אתם יכולים להשתמש שוב בקלט המקורי של המשתמש כדי לנסות לקבל תוצאות רלוונטיות יותר:
    • אם אתם מצפים שהמשתמש יזין רק פרטי כתובת, השתמשו שוב בקלט המקורי של המשתמש בקריאה ל-Geocoding API.
    • אם אתם מצפים שהמשתמש יזין שאילתות לגבי מקום ספציפי לפי שם או כתובת, השתמשו בבקשה לפרטי מקום (חדש). אם התוצאות צפויות רק באזור ספציפי, השתמשו בהטיית מיקום.
    תרחישים נוספים שבהם מומלץ להשתמש ב-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. ההגדרה הזו מנחה את ההשלמה האוטומטית (חדש) להחזיר רק תוצאות באזור הזה.