Places UI Kit : یک کتابخانه آماده برای استفاده که فضایی را برای سفارشی‌سازی و توسعه کم کد فراهم می‌کند. آن را امتحان کنید و نظرات خود را در مورد تجربه کیت UI خود به اشتراک بگذارید.

‫Google برای ترجمه محتوا به زبان ترجیحی شما از فناوری هوشواره استفاده می‌کند. ترجمه‌های هوشواره‌ای ممکن است اشتباه داشته باشند.

Place Autocomplete Data API

توسعه‌دهندگان منطقه اقتصادی اروپا (EEA)

‫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 برای مشخص کردن حداکثر پنج نوع مکان استفاده کنید. اگر هیچ نوعی مشخص نشده باشد، مکان‌های همه انواع برگردانده خواهد شد.

مشاهده مرجع میانای برنامه‌سازی کاربردی

دریافت جزئیات جا

برای برگرداندن شیء 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

کدهای جلسه

‫Session tokens group the query and selection phases of a user autocomplete search into a discrete session for billing purposes. جلسه زمانی آغاز می‌شود که کاربر شروع به تایپ کردن می‌کند. وقتی کاربر مکانی را انتخاب می‌کند و تماسی با «جزئیات جا» برقرار می‌شود، جلسه به پایان می‌رسد.

برای ایجاد کردن کد جلسه جدید و افزودن آن به درخواست، نمونه‌ای از 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، کد جلسه‌ای برای جلسه بعدی بسازید.

توصیه‌های کد جلسه:

از کد جلسه برای همه تماس‌های «تکمیل خودکار جا» استفاده کنید.
برای هر جلسه، یک کد جدید تولید کنید.
برای هر جلسه جدید، یک کد جلسه یکتا ارسال کنید. استفاده از یک کد برای بیش‌از یک جلسه منجر به صدور صورت‌حساب جداگانه برای هر درخواست می‌شود.

می‌توانید به‌طور اختیاری کد جلسه تکمیل خودکار را از درخواست حذف کنید. اگر کد جلسه حذف شود، هر درخواست به‌طور جداگانه صورت‌حساب می‌شود و شناسه محصول تکمیل خودکار - به‌ازای هر درخواست را فعال می‌کند. اگر از کد جلسه مجدداً استفاده کنید، جلسه نامعتبر تلقی می‌شود و درخواست‌ها به‌گونه‌ای محاسبه می‌شوند که گویی هیچ کد جلسه‌ای ارائه نشده است.

مثال

وقتی کاربر پُرسمانی را تایپ می‌کند، هر چند کلیدزنی یک‌بار (نه برای هر نویسه) درخواست تکمیل خودکار فراخوانی می‌شود و فهرستی از نتایج احتمالی برگردانده می‌شود. وقتی کاربر از فهرست نتایج انتخابی انجام می‌دهد، آن انتخاب به‌عنوان یک درخواست محسوب می‌شود و همه درخواست‌های انجام‌شده درطول جستجو دسته‌بندی می‌شوند و به‌عنوان یک درخواست واحد محسوب می‌شوند. اگر کاربر مکانی را انتخاب کند، پرسمان جستجو بدون هزینه دردسترس است و فقط درخواست داده‌های «مکان» هزینه دارد. اگر کاربر در چند دقیقه اول جلسه انتخابی نکند، فقط هزینه پرسمان جستجو کسر می‌شود.

از دیدگاه برنامه، جریان رویدادها به این صورت است:

کاربری شروع به تایپ پُرسمانی برای جستجوی «پاریس، فرانسه» می‌کند.
پس‌از شناسایی ورودی کاربر، برنامه کد جلسه جدیدی به‌نام «کد A» ایجاد می‌کند.
همان‌طور که کاربر تایپ می‌کند، میانای برنامه‌سازی کاربردی هر چند نویسه یک‌بار درخواست تکمیل خودکار می‌کند و فهرست جدیدی از نتایج احتمالی را برای هرکدام نمایش می‌دهد:
«P»
«Par»
«Paris,»
«Paris, Fr»
وقتی کاربر انتخابی انجام می‌دهد:
- همه درخواست‌های حاصل از پُرسمان گروه‌بندی می‌شوند و به‌عنوان یک درخواست واحد به جلسه‌ای که با «ژتون الف» نشان داده می‌شود اضافه می‌شوند.
- انتخاب کاربر به‌عنوان درخواست «جزئیات مکان» شمرده می‌شود و به جلسه‌ای که با «ژتون الف» نشان داده شده است اضافه می‌شود.
جلسه به‌پایان می‌رسد و برنامه «رمز A» را دور می‌اندازد.

با نحوه صدور صورت‌حساب برای جلسه‌ها آشنا شوید

کد نمونه کامل

این بخش حاوی نمونه‌های کاملی است که نحوه استفاده از 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

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() براساس پرسمان‌های کاربر و نمایش فهرستی از مکان‌های پیش‌بینی‌شده در پاسخ.
استفاده از کد جلسه برای گروه‌بندی پرسمان کاربر با درخواست نهایی «جزئیات جا».
بازیابی جزئیات مکان برای مکان انتخاب‌شده و نمایش نشانگر.
استفاده از جای‌گذاری کنترل برای قرار دادن عناصر میانای کاربر در عنصر 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

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 for Android، یا ابزاره «تکمیل خودکار (جدید)» در Places SDK for iOS است.
از همان ابتدا با فیلدهای داده ضروری «تکمیل خودکار» (جدید) آشنا شوید.
فیلدهای سوگیری مکان و محدودیت مکان اختیاری هستند اما می‌توانند تأثیر قابل‌توجهی بر عملکرد تکمیل خودکار داشته باشند.
از مدیریت خطا استفاده کنید تا مطمئن شوید که اگر میانای برنامه‌سازی کاربردی خطایی برگرداند، برنامه شما به‌خوبی تنزل پیدا می‌کند.
مطمئن شوید که برنامه‌تان شرایطی را که هیچ انتخابی وجود ندارد مدیریت می‌کند و راهی برای ادامه دادن به کاربران ارائه می‌دهد.

روال‌های مطلوب بهینه‌سازی هزینه

بهینه‌سازی هزینه پایه

برای بهینه‌سازی هزینه استفاده از سرویس «تکمیل خودکار (جدید)»، از ماسک‌های فیلد در ابزاره‌های «جزئیات مکان (جدید)» و «تکمیل خودکار (جدید)» استفاده کنید تا فقط فیلدهای داده «تکمیل خودکار (جدید)» موردنیازتان برگردانده شود.

بهینه‌سازی پیشرفته هزینه

برای دسترسی به واحد نگهداری موجودی: قیمت‌گذاری درخواست «تکمیل خودکار» و درخواست نتایج Geocoding API درباره مکان انتخاب‌شده به‌جای «جزئیات مکان» (جدید)، پیاده‌سازی برنامه‌ای «تکمیل خودکار» (جدید) را درنظر بگیرید. اگر هر دو شرط زیر برقرار باشد، قیمت‌گذاری به‌ازای درخواست همراه با Geocoding API مقرون‌به‌صرفه‌تر از قیمت‌گذاری به‌ازای جلسه (جلسه‌محور) است:

اگر فقط به طول و عرض جغرافیایی یا نشانی مکان انتخابی کاربر نیاز دارید، Geocoding API این اطلاعات را با هزینه کمتری نسبت‌به فراخوانی Place Details (New)‎ ارائه می‌دهد.
اگر کاربران پیش‌بینی تکمیل خودکار را به‌طور میانگین در چهار درخواست پیش‌بینی «تکمیل خودکار» (جدید) یا کمتر انتخاب کنند، قیمت‌گذاری براساس درخواست می‌تواند مقرون‌به‌صرفه‌تر از قیمت‌گذاری براساس جلسه باشد.

برای دریافت راهنمایی درباره انتخاب پیاده‌سازی «تکمیل خودکار (جدید)» که با نیازهایتان مطابقت داشته باشد، برگه‌ای را انتخاب کنید که با پاسخ شما به سؤال زیر مطابقت دارد.

آیا برنامه شما به اطلاعاتی غیراز نشانی و عرض/طول جغرافیایی پیش‌بینی انتخاب‌شده نیاز دارد؟

بله، به جزئیات بیشتری نیاز دارد

از «تکمیل خودکار» (جدید) مبتنی بر جلسه با «جزئیات مکان» (جدید) استفاده کنید.
ازآنجایی‌که برنامه شما به «جزئیات مکان (جدید)» مانند نام مکان، وضعیت کسب‌وکار، یا ساعت کاری نیاز دارد، پیاده‌سازی شما از «تکمیل خودکار (جدید)» باید از کد جلسه استفاده کند (به‌صورت برنامه‌نویسی‌شده یا تعبیه‌شده در ابزاره‌های JavaScript، Android، یا iOS) به‌ازای هر جلسه به‌علاوه شناسه‌های یکتای کالای «مکان‌ها»ی مربوطه، بسته به اینکه کدام فیلدهای داده مکان را درخواست می‌کنید.^۱

پیاده‌سازی ابزاره
مدیریت جلسه به‌طور خودکار در ابزاره‌های JavaScript، Android، یا iOS ساخته می‌شود. این شامل درخواست‌های «تکمیل خودکار» (جدید) و درخواست «جزئیات مکان» (جدید) در پیش‌بینی انتخاب‌شده می‌شود. حتماً پارامتر fields را مشخص کنید تا مطمئن شوید فقط فیلدهای داده «تکمیل خودکار (جدید)» موردنیازتان را درخواست می‌کنید.

پیاده‌سازی برنامه‌ریزی‌شده
از کد جلسه با درخواست‌های «تکمیل خودکار» (جدید) استفاده کنید. هنگام درخواست «جزئیات مکان (جدید)» درباره پیش‌بینی انتخاب‌شده، پارامترهای زیر را اضافه کنید:

شناسه جا از پاسخ «تکمیل خودکار» (جدید)
کد جلسه استفاده‌شده در درخواست «تکمیل خودکار (جدید)»
پارامتر fields که فیلدهای داده «تکمیل خودکار (جدید)» موردنیازتان را مشخص می‌کند

نه، فقط به نشانی و مکان نیاز دارد

Geocoding API می‌تواند گزینه مقرون‌به‌صرفه‌تری نسبت‌به Place Details (New) برای برنامه شما باشد، بسته به عملکرد استفاده شما از Autocomplete (New). کارایی «تکمیل خودکار (جدید)» هر برنامه بسته به آنچه کاربران وارد می‌کنند، جایی که برنامه استفاده می‌شود، و اینکه آیا روال‌های مطلوب بهینه‌سازی عملکرد اجرا شده است یا نه متفاوت است.

برای پاسخ دادن به سؤال زیر، تحلیل کنید که کاربر به‌طور میانگین چند نویسه تایپ می‌کند تا پیش‌بینی «تکمیل خودکار» (جدید) را در برنامه‌تان انتخاب کند.

آیا کاربران شما به‌طور میانگین با چهار درخواست یا کمتر، پیش‌بینی «تکمیل خودکار (جدید)» را انتخاب می‌کنند؟

بله

«تکمیل خودکار» (جدید) را به‌صورت برنامه‌نویسی‌شده بدون کد جلسه پیاده‌سازی کنید و Geocoding API را در پیش‌بینی مکان انتخاب‌شده فراخوانی کنید.
Geocoding API نشانی‌ها و مختصات طول/عرض جغرافیایی را ارائه می‌دهد. انجام چهار درخواست تکمیل خودکار به‌علاوه یک فراخوانی Geocoding API درباره پیش‌بینی مکان انتخاب‌شده کمتر از هزینه هر جلسه «تکمیل خودکار (جدید)» است.^۱

بهترین روش‌های عملکرد را به‌کار بگیرید تا به کاربران کمک کنید پیش‌بینی موردنظرشان را با نویسه‌های کمتری دریافت کنند.

نه

از «تکمیل خودکار» (جدید) مبتنی بر جلسه با «جزئیات مکان» (جدید) استفاده کنید.
ازآنجایی‌که میانگین تعداد درخواست‌هایی که انتظار دارید قبل‌از اینکه کاربر پیش‌بینی «تکمیل خودکار (جدید)» را انتخاب کند، از هزینه قیمت‌گذاری هر جلسه فراتر می‌رود، پیاده‌سازی شما از «تکمیل خودکار (جدید)» باید از یک کد جلسه برای هر دو درخواست «تکمیل خودکار (جدید)» و درخواست مرتبط «جزئیات مکان (جدید)» استفاده کند. هر جلسه. ^۱

پیاده‌سازی ابزاره
مدیریت جلسه به‌طور خودکار در ابزاره‌های JavaScript، Android، یا iOS ساخته می‌شود. این شامل درخواست‌های «تکمیل خودکار» (جدید) و درخواست «جزئیات مکان» (جدید) در پیش‌بینی انتخاب‌شده می‌شود. حتماً پارامتر fields را مشخص کنید تا مطمئن شوید فقط فیلدهای موردنیازتان را درخواست می‌کنید.

شناسه جا از پاسخ «تکمیل خودکار» (جدید)
کد جلسه استفاده‌شده در درخواست «تکمیل خودکار (جدید)»
پارامتر fields که فیلدهایی مثل نشانی و هندسه را مشخص می‌کند

به‌تأخیر انداختن درخواست‌های «تکمیل خودکار» (جدید) را مدنظر قرار دهید
می‌توانید از استراتژی‌هایی مانند به‌تأخیر انداختن درخواست «تکمیل خودکار» (جدید) تا زمانی که کاربر سه یا چهار نویسه اول را تایپ کند استفاده کنید تا برنامه‌تان درخواست‌های کمتری ارسال کند. برای مثال، ارسال درخواست‌های «تکمیل خودکار (جدید)» برای هر نویسه پس‌از اینکه کاربر نویسه سوم را تایپ کرد به این معنی است که اگر کاربر هفت نویسه تایپ کند و سپس پیش‌بینی‌ای را انتخاب کند که برای آن یک درخواست Geocoding API ارسال می‌کنید، هزینه کل برای ۴ درخواست «تکمیل خودکار (جدید)» به‌ازای هر درخواست + Geocoding خواهد بود.^۱

اگر با به‌تأخیر انداختن درخواست‌ها می‌توانید میانگین درخواست‌های برنامه‌ریزی‌شده را به زیر چهار برسانید، می‌توانید راهنمای پیاده‌سازی «تکمیل خودکار (جدید)» با Geocoding API را دنبال کنید. توجه داشته باشید که تأخیر در درخواست‌ها می‌تواند ازسوی کاربر به‌عنوان تأخیر درک شود، زیرا ممکن است کاربر انتظار داشته باشد با هر ضربه کلید جدید، پیش‌بینی‌ها را ببیند.

برای کمک به کاربران در دریافت پیش‌بینی موردنظرشان با نویسه‌های کمتر، روال‌های مطلوب عملکرد را به‌کار بگیرید.

برای اطلاع از هزینه‌ها، فهرست‌های قیمت‌گذاری «پلاتفرم Google Maps» را ببینید.

روال‌های مطلوب عملکرد

دستورالعمل‌های زیر روش‌های بهینه‌سازی عملکرد «تکمیل خودکار» (جدید) را شرح می‌دهد:

محدودیت‌های کشور، سوگیری مکان، و (برای پیاده‌سازی‌های برنامه‌ای) اولویت زبان را به پیاده‌سازی «تکمیل خودکار» (جدید) خود اضافه کنید. برای ابزاره‌ها به اولویت زبان نیازی نیست چون آن‌ها اولویت‌های زبان را از مرورگر یا دستگاه همراه کاربر انتخاب می‌کنند.
اگر «تکمیل خودکار (جدید)» با نقشه همراه باشد، می‌توانید مکان را براساس نمای نقشه سوگیری کنید.
در شرایطی که کاربر یکی از پیش‌بینی‌های Autocomplete (New) را انتخاب نمی‌کند، معمولاً به این دلیل که هیچ‌کدام از آن پیش‌بینی‌ها نشانی نتیجه موردنظر نیست، می‌توانید از ورودی اصلی کاربر مجدداً استفاده کنید تا نتایج مرتبط‌تری دریافت کنید:
- اگر انتظار دارید کاربر فقط اطلاعات نشانی را وارد کند، از ورودی اصلی کاربر در فراخوانی به 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، نتایج را به منطقه مشخصی محدود کنید.

همچنین می‌توانید با افزودن پارامتر locationRestriction نتایج را به منطقه‌ای که با location و پارامتر radius تعریف شده است محدود کنید. این به «تکمیل خودکار» (جدید) دستور می‌دهد فقط نتایج درون آن منطقه را برگرداند.

Place Autocomplete Data API با مجموعه‌ها، منظم بمانید ذخیره و طبقه‌بندی محتوا براساس اولویت‌های شما.

درخواست‌های تکمیل خودکار

محدود کردن پیش‌بینی‌های «تکمیل خودکار»

دریافت جزئیات جا

کدهای جلسه

توصیه‌های کد جلسه:

مثال

کد نمونه کامل

پیش‌بینی‌های تکمیل خودکار جا

TypeScript

JavaScript

CSS

HTML

تکمیل خودکار جا با پیش‌بینی تایپ با جلسات

TypeScript

JavaScript

CSS

HTML

بهینه‌سازی تکمیل خودکار (جدید)

روال‌های مطلوب بهینه‌سازی هزینه

بهینه‌سازی هزینه پایه

بهینه‌سازی پیشرفته هزینه

بله، به جزئیات بیشتری نیاز دارد

نه، فقط به نشانی و مکان نیاز دارد

بله

نه

روال‌های مطلوب عملکرد

سوگیری مکانی

محدودیت مکان

Place Autocomplete Data API