دریافت کلید نسخه نمایشی Maps: با «کلید نسخه نمایشی Maps» برخی‌از ویژگی‌های Maps JavaScript API و «کیت میانای کاربر جاها» را بدون هزینه امتحان کنید—اطلاعات صورت‌حساب لازم نیست.

‫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

کدهای جلسه

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

برای ایجاد کردن کد جلسه جدید و افزودن آن به درخواست، نمونه‌ای از 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» ایجاد می‌کند.
همان‌طور که کاربر تایپ می‌کند، API هر چند نویسه یک درخواست تکمیل خودکار ایجاد می‌کند و فهرست جدیدی از نتایج احتمالی را برای هرکدام نمایش می‌دهد:
«P»
«Par»
«Paris,»
«Paris, Fr»
وقتی کاربر انتخابی انجام می‌دهد:
- همه درخواست‌های حاصل از پُرسمان گروه‌بندی می‌شوند و به‌عنوان درخواستی واحد به جلسه نشان‌داده‌شده با «رمز A» اضافه می‌شوند.
- انتخاب کاربر به‌عنوان درخواست «جزئیات جا» محاسبه می‌شود و به جلسه‌ای که با «ژتون الف» نشان داده شده است اضافه می‌شود.
جلسه به‌پایان می‌رسد و برنامه «رمز 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 است.
از همان ابتدا، فیلدهای داده ضروری «تکمیل خودکار (جدید)» را درک کنید.
فیلدهای سوگیری مکان و محدودیت مکان اختیاری هستند اما می‌توانند تأثیر قابل‌توجهی بر عملکرد تکمیل خودکار داشته باشند.
از مدیریت خطا استفاده کنید تا مطمئن شوید که اگر میانای برنامه‌سازی کاربردی خطایی برگرداند، برنامه شما به‌خوبی تنزل پیدا می‌کند.
مطمئن شوید که برنامه‌تان وقتی انتخابی وجود ندارد، این وضعیت را مدیریت می‌کند و راهی برای ادامه دادن به کاربران ارائه می‌دهد.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Per-request Autocomplete (New) with the Geocoding API

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Per-request Autocomplete (New) with the Geocoding API

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

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

سوگیری مکانی

محدود کردن مکان

Place Autocomplete Data API