‫ Places UI Kit: ספרייה מוכנה לשימוש שמאפשרת למפתחים להתאים אישית ולשלוט. כדאי לנסות ולשתף את המשוב שלך על חוויית השימוש בערכת ממשק המשתמש.

Place Autocomplete Data API

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

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

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

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

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

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

// Add an initial request body.
let 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.
// @ts-ignore
request.sessionToken = token;index.js

הגבלת ההצעות להשלמה אוטומטית

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

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

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

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

לעיון בהפניית ה-API

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

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

let 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.
// @ts-ignore
request.sessionToken = token;index.js

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

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

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

המלצות לטוקן סשן:

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

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

דוגמה

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

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

משתמש מתחיל להקליד שאילתה כדי לחפש את 'פריז, צרפת'.
כשמזוהה קלט של משתמשים, האפליקציה יוצרת טוקן לסשן חדש, Token A.
בזמן שהמשתמש מקליד, ה-API שולח בקשה להשלמה אוטומטית אחרי כל כמה תווים, ומציג רשימה חדשה של תוצאות אפשריות לכל אחד מהם:
'P'
'Par'
'Paris'
'Paris, Fr'
כשהמשתמש בוחר:
- כל הבקשות שנובעות מהשאילתה מקובצות ונוספות לסשן שמיוצג על ידי Token A כבקשה אחת.
- הבחירה של המשתמש נספרת כבקשה לפרטי מקום, והיא מתווספת לסשן שמיוצג על ידי Token A.
הסשן מסתיים והאפליקציה מבטלת את האסימון A.

מידע על חיוב על סשנים

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

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

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

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

TypeScript

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

    // Add an initial request body.
    let 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.
    // @ts-ignore
    request.sessionToken = token;
    // Fetch autocomplete suggestions.
    const { suggestions } =
        await AutocompleteSuggestion.fetchAutocompleteSuggestions(request);

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

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

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

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

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

init();index.ts

JavaScript

async function init() {
    const { Place, AutocompleteSessionToken, AutocompleteSuggestion } = (await google.maps.importLibrary('places'));
    // Add an initial request body.
    let 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.
    // @ts-ignore
    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 (let 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);
    }
    let 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}`;
}
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>
        <!-- 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>
        <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

דוגמה לניסיון

JSFiddle.net

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

בדוגמה הזו אפשר לראות את המושגים הבאים:

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

TypeScript

const mapElement = document.querySelector('gmp-map') as google.maps.MapElement;
let innerMap: google.maps.Map;
let marker: google.maps.marker.AdvancedMarkerElement;
let titleElement = document.querySelector('.title') as HTMLElement;
let resultsContainerElement = document.querySelector('.results') as HTMLElement;
let inputElement = document.querySelector('input') as HTMLInputElement;
let tokenStatusElement = document.querySelector('.token-status') as HTMLElement;
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.
    google.maps.event.addListener(innerMap, 'bounds_changed', async () => {
        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'
    )) as google.maps.PlacesLibrary;

    if (!inputEvent.target?.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', () => {
            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'
    )) as google.maps.MarkerLibrary;

    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'
    )) as google.maps.PlacesLibrary;

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

init();index.ts

JavaScript

const mapElement = document.querySelector('gmp-map');
let innerMap;
let marker;
let titleElement = document.querySelector('.title');
let resultsContainerElement = document.querySelector('.results');
let inputElement = document.querySelector('input');
let 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.
    google.maps.event.addListener(innerMap, 'bounds_changed', async () => {
        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', () => {
            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}`;
}
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>
        <!-- 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="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

דוגמה לניסיון

JSFiddle.net

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

כן

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

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

לא

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

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

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

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

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

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

למידע על עלויות, אפשר לעיין ברשימות המחירים של הפלטפורמה של מפות Google.

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

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

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

Place Autocomplete Data API קל לארגן דפים בעזרת אוספים אפשר לשמור ולסווג תוכן על סמך ההעדפות שלך.

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

הגבלת ההצעות להשלמה אוטומטית

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

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

המלצות לטוקן סשן:

דוגמה

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

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

TypeScript

JavaScript

CSS

HTML

דוגמה לניסיון

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

TypeScript

JavaScript

CSS

HTML

דוגמה לניסיון

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

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

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

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

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

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

כן

לא

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

הטיה לפי מיקום

הגבלת מיקום

Place Autocomplete Data API