Place Autocomplete Data API

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

אם כתובת החיוב שלכם נמצאת באזור הכלכלי האירופי, החל מ-8 ביולי 2025, התנאים וההגבלות של Google Maps Platform למשתמשים באזור הכלכלי האירופי יחולו על השימוש שלכם בשירותים. הפונקציונליות יכולה להיות שונה בין אזור לאזור. מידע נוסף

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

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

בקשות להשלמה אוטומטית

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

קטע הקוד הבא מראה איך ליצור גוף בקשה ולהוסיף טוקן לסשן, ואז לקרוא ל-fetchAutocompleteSuggestions() כדי לקבל רשימה של PlacePrediction.

// Add an initial request body.
const request = {
    input: 'Tadi',
    locationRestriction: {
        west: -122.44,
        north: 37.8,
        east: -122.39,
        south: 37.78,
    },
    origin: { lat: 37.7893, lng: -122.4039 },
    includedPrimaryTypes: ['restaurant'],
    language: 'en-US',
    region: 'us',
};

// Create a session token.
const token = new AutocompleteSessionToken();
// Add the token to the request.
request.sessionToken = token;
index.js

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

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

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

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

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

לעיון במאמרי העזרה של ה-API

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

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

const place = suggestions[0].placePrediction.toPlace(); // Get first predicted place.
await place.fetchFields({
    fields: ['displayName', 'formattedAddress'],
});

const placeInfo = document.getElementById('prediction');
placeInfo.textContent = `First predicted place: ${place.displayName}: ${place.formattedAddress}`;
index.js

טוקנים לסשנים

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

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

// Create a session token.
const token = new AutocompleteSessionToken();
// Add the token to the request.
request.sessionToken = token;
index.js

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

await place.fetchFields({
    fields: ['displayName', 'formattedAddress'],
});
index.js

כדי ליצור טוקן לסשן הבא, יוצרים מופע חדש של AutocompleteSessionToken.

המלצות לגבי טוקנים לסשנים:

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

אפשר להשמיט את הטוקן לסשן של ההשלמה האוטומטית מהבקשה. אם לא תשלחו טוקן לסשן, כל בקשה תחויב בנפרד לפי המק"ט Autocomplete - Per Request. אם תשתמשו שוב בטוקן לסשן, הסשן ייחשב לא חוקי והבקשות יחויבו כאילו לא סופק טוקן לסשן.

דוגמה

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

מנקודת המבט של האפליקציה, רצף האירועים הוא כזה:

1. משתמש מתחיל להקליד שאילתה כדי לחפש את "פריז, צרפת".
2. כשהאפליקציה מזהה קלט מהמשתמש, היא יוצרת טוקן חדש לסשן, "טוקן א'".
3. בזמן שהמשתמש מקליד, ה-API שולח בקשה להשלמה אוטומטית כל כמה תווים, ומציג רשימה חדשה של תוצאות אפשריות לכל אחת מהן:
   "P"
   "Par"
   "Paris,"
   "Paris, Fr"
   
4. כשהמשתמש בוחר אפשרות:
   • כל הבקשות שנובעות מהשאילתה מקובצות ומתווספות לסשן שמיוצג על ידי "אסימון א'" כבקשה אחת.
   • הבחירה של המשתמש נספרת כבקשה ל-Place Details, ומתווספת לסשן שמיוצג על ידי "אסימון א'".
5. הסשן מסתיים והאפליקציה מוחקת את "אסימון א'".

מידע ולמידה על איך מתבצע החיוב על סשנים

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

בקטע הזה מופיעות דוגמאות מלאות שמראות איך להשתמש ב-Place Autocomplete Data API .

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

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

TypeScript

async function init() {
    const { AutocompleteSessionToken, AutocompleteSuggestion } =
        await google.maps.importLibrary('places');

    // Add an initial request body.
    const request: google.maps.places.AutocompleteRequest = {
        input: 'Tadi',
        locationRestriction: {
            west: -122.44,
            north: 37.8,
            east: -122.39,
            south: 37.78,
        },
        origin: { lat: 37.7893, lng: -122.4039 },
        includedPrimaryTypes: ['restaurant'],
        language: 'en-US',
        region: 'us',
    };

    // Create a session token.
    const token = new AutocompleteSessionToken();
    // Add the token to the request.
    request.sessionToken = token;
    // Fetch autocomplete suggestions.
    const { suggestions } =
        await AutocompleteSuggestion.fetchAutocompleteSuggestions(request);

    const title = document.getElementById('title')!;
    title.appendChild(
        document.createTextNode(
            'Query predictions for "' + request.input + '":'
        )
    );

    const resultsElement = document.getElementById('results')!;

    for (const suggestion of suggestions) {
        const placePrediction = suggestion.placePrediction;

        // Create a new list element.
        const listItem = document.createElement('li');

        listItem.appendChild(
            document.createTextNode(placePrediction!.text.toString())
        );
        resultsElement.appendChild(listItem);
    }

    const place = suggestions[0].placePrediction!.toPlace(); // Get first predicted place.
    await place.fetchFields({
        fields: ['displayName', 'formattedAddress'],
    });

    const placeInfo = document.getElementById('prediction')!;
    placeInfo.textContent = `First predicted place: ${place.displayName}: ${place.formattedAddress}`;
}

void init();
index.ts

הערה: כדאי לקרוא את המדריך לשימוש ב-TypeScript ובמפות Google.

JavaScript

async function init() {
    const { AutocompleteSessionToken, AutocompleteSuggestion } =
        await google.maps.importLibrary('places');

    // Add an initial request body.
    const request = {
        input: 'Tadi',
        locationRestriction: {
            west: -122.44,
            north: 37.8,
            east: -122.39,
            south: 37.78,
        },
        origin: { lat: 37.7893, lng: -122.4039 },
        includedPrimaryTypes: ['restaurant'],
        language: 'en-US',
        region: 'us',
    };

    // Create a session token.
    const token = new AutocompleteSessionToken();
    // Add the token to the request.
    request.sessionToken = token;
    // Fetch autocomplete suggestions.
    const { suggestions } =
        await AutocompleteSuggestion.fetchAutocompleteSuggestions(request);

    const title = document.getElementById('title');
    title.appendChild(
        document.createTextNode(
            'Query predictions for "' + request.input + '":'
        )
    );

    const resultsElement = document.getElementById('results');

    for (const suggestion of suggestions) {
        const placePrediction = suggestion.placePrediction;

        // Create a new list element.
        const listItem = document.createElement('li');

        listItem.appendChild(
            document.createTextNode(placePrediction.text.toString())
        );
        resultsElement.appendChild(listItem);
    }

    const place = suggestions[0].placePrediction.toPlace(); // Get first predicted place.
    await place.fetchFields({
        fields: ['displayName', 'formattedAddress'],
    });

    const placeInfo = document.getElementById('prediction');
    placeInfo.textContent = `First predicted place: ${place.displayName}: ${place.formattedAddress}`;
}

void init();
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;
}
style.css

HTML

<html>
    <head>
        <title>Place Autocomplete Data API Predictions</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>
        <div id="title"></div>
        <ul id="results"></ul>
        <p><span id="prediction"></span></p>
        <img
            class="powered-by-google"
            src="./powered_by_google_on_white.png"
            alt="Powered by Google" />
    </body>
</html>
index.html

השלמה אוטומטית למקומות עם סשנים

הדוגמה הזו ממחישה את המושגים הבאים:

• קריאה ל-fetchAutocompleteSuggestions() על סמך שאילתות של משתמשים והצגת רשימה של מקומות חזויים בתגובה.
• שימוש בטוקנים לסשן כדי לקבץ שאילתת משתמש עם הבקשה הסופית של Place Details.
• אחזור פרטי המקום שנבחר והצגת סמן.
• שימוש ב-control slotting כדי להטמיע רכיב בממשק המשתמש ברכיב gmp-map.

TypeScript

const mapElement = document.querySelector('gmp-map')!;
let innerMap: google.maps.Map;
let marker: google.maps.marker.AdvancedMarkerElement;
const titleElement = document.querySelector<HTMLElement>('.title')!;
const resultsContainerElement = document.querySelector('.results')!;
const inputElement = document.querySelector('input')!;
const tokenStatusElement = document.querySelector('.token-status')!;
let newestRequestId = 0;
let tokenCount = 0;

// Create an initial request body.
const request: google.maps.places.AutocompleteRequest = {
    input: '',
    includedPrimaryTypes: [
        'restaurant',
        'cafe',
        'museum',
        'park',
        'botanical_garden',
    ],
};

async function init() {
    await google.maps.importLibrary('maps');
    innerMap = mapElement.innerMap;
    innerMap.setOptions({
        mapTypeControl: false,
    });

    // Update request center and bounds when the map bounds change.
    innerMap.addListener('bounds_changed', () => {
        request.locationRestriction = innerMap.getBounds();
        request.origin = innerMap.getCenter();
    });

    inputElement.addEventListener('input', makeAutocompleteRequest);
}

async function makeAutocompleteRequest(inputEvent: Event) {
    // To avoid race conditions, store the request ID and compare after the request.
    const requestId = ++newestRequestId;

    const { AutocompleteSuggestion } =
        await google.maps.importLibrary('places');

    if (!(inputEvent.target as HTMLInputElement)?.value) {
        titleElement.textContent = '';
        resultsContainerElement.replaceChildren();
        return;
    }

    // Add the latest char sequence to the request.
    request.input = (inputEvent.target as HTMLInputElement).value;

    // Fetch autocomplete suggestions and show them in a list.
    const { suggestions } =
        await AutocompleteSuggestion.fetchAutocompleteSuggestions(request);

    // If the request has been superseded by a newer request, do not render the output.
    if (requestId !== newestRequestId) return;

    titleElement.innerText = `Place predictions for "${request.input}"`;

    // Clear the list first.
    resultsContainerElement.replaceChildren();

    for (const suggestion of suggestions) {
        const placePrediction = suggestion.placePrediction;

        if (!placePrediction) {
            continue;
        }

        // Create a link for the place, add an event handler to fetch the place.
        // We are using a button element to take advantage of its a11y capabilities.
        const placeButton = document.createElement('button');
        placeButton.addEventListener('click', () => {
            void onPlaceSelected(placePrediction.toPlace());
        });

        placeButton.textContent = placePrediction.text.toString();
        placeButton.classList.add('place-button');

        // Create a new list item element.
        const li = document.createElement('li');
        li.appendChild(placeButton);
        resultsContainerElement.appendChild(li);
    }
}

// Event handler for clicking on a suggested place.
async function onPlaceSelected(place: google.maps.places.Place) {
    const { AdvancedMarkerElement } = await google.maps.importLibrary('marker');

    await place.fetchFields({
        fields: ['displayName', 'formattedAddress', 'location'],
    });

    resultsContainerElement.textContent = `${place.displayName}: ${place.formattedAddress}`;
    titleElement.textContent = 'Selected Place:';
    inputElement.value = '';

    await refreshToken();

    // Remove the previous marker, if it exists.
    if (marker) {
        marker.remove();
    }

    // Create a new marker.
    marker = new AdvancedMarkerElement({
        map: innerMap,
        position: place.location,
        title: place.displayName,
    });

    // Center the map on the selected place.
    if (place.location) {
        innerMap.setCenter(place.location);
        innerMap.setZoom(15);
    }
}

// Helper function to refresh the session token.
async function refreshToken() {
    const { AutocompleteSessionToken } =
        await google.maps.importLibrary('places');

    // Increment the token counter.
    tokenCount++;

    // Create a new session token and add it to the request.
    request.sessionToken = new AutocompleteSessionToken();
    tokenStatusElement.textContent = `Session token count: ${tokenCount}`;
}

void init();
index.ts

הערה: כדאי לקרוא את המדריך לשימוש ב-TypeScript ובמפות Google.

JavaScript

const mapElement = document.querySelector('gmp-map');
let innerMap;
let marker;
const titleElement = document.querySelector('.title');
const resultsContainerElement = document.querySelector('.results');
const inputElement = document.querySelector('input');
const tokenStatusElement = document.querySelector('.token-status');
let newestRequestId = 0;
let tokenCount = 0;

// Create an initial request body.
const request = {
    input: '',
    includedPrimaryTypes: [
        'restaurant',
        'cafe',
        'museum',
        'park',
        'botanical_garden',
    ],
};

async function init() {
    await google.maps.importLibrary('maps');
    innerMap = mapElement.innerMap;
    innerMap.setOptions({
        mapTypeControl: false,
    });

    // Update request center and bounds when the map bounds change.
    innerMap.addListener('bounds_changed', () => {
        request.locationRestriction = innerMap.getBounds();
        request.origin = innerMap.getCenter();
    });

    inputElement.addEventListener('input', makeAutocompleteRequest);
}

async function makeAutocompleteRequest(inputEvent) {
    // To avoid race conditions, store the request ID and compare after the request.
    const requestId = ++newestRequestId;

    const { AutocompleteSuggestion } =
        await google.maps.importLibrary('places');

    if (!inputEvent.target?.value) {
        titleElement.textContent = '';
        resultsContainerElement.replaceChildren();
        return;
    }

    // Add the latest char sequence to the request.
    request.input = inputEvent.target.value;

    // Fetch autocomplete suggestions and show them in a list.
    const { suggestions } =
        await AutocompleteSuggestion.fetchAutocompleteSuggestions(request);

    // If the request has been superseded by a newer request, do not render the output.
    if (requestId !== newestRequestId) return;

    titleElement.innerText = `Place predictions for "${request.input}"`;

    // Clear the list first.
    resultsContainerElement.replaceChildren();

    for (const suggestion of suggestions) {
        const placePrediction = suggestion.placePrediction;

        if (!placePrediction) {
            continue;
        }

        // Create a link for the place, add an event handler to fetch the place.
        // We are using a button element to take advantage of its a11y capabilities.
        const placeButton = document.createElement('button');
        placeButton.addEventListener('click', () => {
            void onPlaceSelected(placePrediction.toPlace());
        });

        placeButton.textContent = placePrediction.text.toString();
        placeButton.classList.add('place-button');

        // Create a new list item element.
        const li = document.createElement('li');
        li.appendChild(placeButton);
        resultsContainerElement.appendChild(li);
    }
}

// Event handler for clicking on a suggested place.
async function onPlaceSelected(place) {
    const { AdvancedMarkerElement } = await google.maps.importLibrary('marker');

    await place.fetchFields({
        fields: ['displayName', 'formattedAddress', 'location'],
    });

    resultsContainerElement.textContent = `${place.displayName}: ${place.formattedAddress}`;
    titleElement.textContent = 'Selected Place:';
    inputElement.value = '';

    await refreshToken();

    // Remove the previous marker, if it exists.
    if (marker) {
        marker.remove();
    }

    // Create a new marker.
    marker = new AdvancedMarkerElement({
        map: innerMap,
        position: place.location,
        title: place.displayName,
    });

    // Center the map on the selected place.
    if (place.location) {
        innerMap.setCenter(place.location);
        innerMap.setZoom(15);
    }
}

// Helper function to refresh the session token.
async function refreshToken() {
    const { AutocompleteSessionToken } =
        await google.maps.importLibrary('places');

    // Increment the token counter.
    tokenCount++;

    // Create a new session token and add it to the request.
    request.sessionToken = new AutocompleteSessionToken();
    tokenStatusElement.textContent = `Session token count: ${tokenCount}`;
}

void init();
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-button {
    height: 3rem;
    width: 100%;
    background-color: transparent;
    text-align: left;
    border: none;
    cursor: pointer;
}

.place-button:focus-visible {
    outline: 2px solid #0056b3;
    border-radius: 2px;
}

.input {
    width: 300px;
    font-size: small;
    margin-bottom: 1rem;
}

/* Styles for the floating panel */
.controls {
    background-color: #fff;
    border-radius: 8px;
    box-shadow: 0 2px 6px rgba(0, 0, 0, 0.3);
    font-family: sans-serif;
    font-size: small;
    margin: 12px;
    padding: 1rem;
}

.title {
    font-weight: bold;
    margin-top: 1rem;
    margin-bottom: 0.5rem;
}

.results {
    list-style-type: none;
    margin: 0;
    padding: 0;
}

.results li:not(:last-child) {
    border-bottom: 1px solid #ddd;
}

.results li:hover {
    background-color: #eee;
}
style.css

HTML

<html>
    <head>
        <title>Place Autocomplete Data API Session</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="37.7893, -122.4039" zoom="12" map-id="DEMO_MAP_ID">
            <div class="controls" slot="control-inline-start-block-start">
                <input
                    type="text"
                    class="input"
                    placeholder="Search for a place..."
                    autocomplete="off" /><!-- Turn off the input's own autocomplete (not supported by all browsers).-->
                <div class="token-status"></div>
                <div class="title"></div>
                <ol class="results"></ol>
            </div>
        </gmp-map>
    </body>
</html>
index.html

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

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

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

• הדרך המהירה ביותר לפתח ממשק משתמש פעיל היא להשתמש בווידג'ט ההשלמה האוטומטית (חדש) של Maps JavaScript API, בווידג'ט ההשלמה האוטומטית (חדש) של Places SDK ל-Android או בווידג'ט ההשלמה האוטומטית (חדש) של Places SDK ל-iOS.
• להבין את שדות הנתונים החיוניים של ההשלמה האוטומטית (חדש) כבר מההתחלה.
• השדות "הטיה לפי מיקום" ו"הגבלת מיקום" הם אופציונליים, אבל יכולה להיות להם השפעה משמעותית על הביצועים של ההשלמה האוטומטית.
• כדאי להשתמש בטיפול בשגיאות כדי לוודא שהאפליקציה תפעל בצורה תקינה אם ה-API יחזיר שגיאה.
• חשוב לוודא שהאפליקציה מטפלת במצב שבו אין בחירה ומציעה למשתמשים דרך להמשיך.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

כן

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

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

לא

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

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

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

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

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

אם עיכוב הבקשות יכול להפחית את הממוצע של הבקשות הפרוגרמטיות לפחות מ-4, אתם יכולים לפעול לפי ההנחיות להטמעה של Autocomplete (חדש) עם 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 כדי לסנן את התוצאות כך שיוצגו רק המקומות במדינה מסוימת.

אזהרה: אם לא מציינים את radius, המערכת מתעלמת מהפרמטר location.

בדרך כלל, הדירוג של תוצאות החיפוש של בתי עסק לא גבוה מספיק כדי שהן יוצגו בתוצאות כשאזור החיפוש גדול. אם רוצים שבתי עסק יופיעו בתוצאות מעורבות של בתי עסק וקואורדינטות, אפשר לציין רדיוס קטן יותר. לחלופין, אפשר להשתמש ב-types=establishment כדי להגביל את התוצאות למוסדות בלבד.

הגבלת מיקום

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

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

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