حزمة أدوات Places UI Kit: هي مكتبة جاهزة للاستخدام تتيح للمطوّرين إمكانية التخصيص والتحكّم. ننصحك بتجربتها ومشاركة ملاحظاتك حول تجربتك مع حزمة واجهة المستخدم.

تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

واجهة برمجة التطبيقات الخاصة بميزة "الإكمال التلقائي للأماكن"

المطوّرون في المنطقة الاقتصادية الأوروبية

تتيح لك واجهة برمجة التطبيقات Place Autocomplete Data API جلب توقعات الأماكن آليًا، وذلك لإنشاء تجارب إكمال تلقائي مخصّصة مع درجة تحكّم أدقّ من تلك المتاحة باستخدام أداة الإكمال التلقائي. سيوضّح لك هذا الدليل كيفية استخدام واجهة برمجة التطبيقات Place Autocomplete Data API لتقديم طلبات إكمال تلقائي استنادًا إلى طلبات المستخدمين.

يعرض المثال التالي عملية دمج مبسطة لميزة "البحث المسبق". أدخِل طلب البحث، مثل "بيتزا" أو "بوكي"، ثم انقر لاختيار النتيجة التي تريدها.

طلبات الإكمال التلقائي

يتلقّى طلب الإكمال التلقائي سلسلة إدخال لطلب بحث ويعرض قائمة بتوقّعات الأماكن. لإجراء طلب إكمال تلقائي، اتّصِل بالدالة 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

تقييد عبارات البحث المقترَحة من ميزة "الإكمال التلقائي"

تعرض خدمة "الإكمال التلقائي للأماكن" تلقائيًا جميع أنواع الأماكن، مع إعطاء الأولوية للتوقّعات القريبة من الموقع الجغرافي للمستخدم، كما تسترد جميع حقول البيانات المتاحة للمكان الذي اختاره المستخدم. اضبط خيارات الإكمال التلقائي في Place لتقديم توقّعات أكثر صلة بالموضوع، وذلك عن طريق تقييد النتائج أو تحسينها.

يؤدي حصر النتائج إلى تجاهل أداة الإكمال التلقائي لأي نتائج خارج منطقة الحصر. من الممارسات الشائعة حصر النتائج في حدود الخريطة. يؤدي تحيز النتائج إلى عرض أداة الإكمال التلقائي لنتائج ضمن المنطقة المحدّدة، ولكن قد تكون بعض النتائج المطابقة خارج هذه المنطقة.

استخدِم السمة origin لتحديد نقطة البداية التي سيتم منها احتساب المسافة الجيوديسية إلى الوجهة. في حال عدم إدخال هذه القيمة، لن يتم عرض المسافة.

استخدِم السمة includedPrimaryTypes لتحديد ما يصل إلى خمسة أنواع أماكن. في حال عدم تحديد أي أنواع، سيتم عرض الأماكن من جميع الأنواع.

الاطّلاع على مرجع واجهة برمجة التطبيقات

الحصول على تفاصيل المكان

لعرض عنصر 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

رموز الجلسات المميزة

تجمع رموز الجلسات بين مرحلتَي طلب البحث والاختيار في عملية بحث الإكمال التلقائي التي يجريها المستخدم، وذلك في جلسة منفصلة لأغراض الفوترة. تبدأ الجلسة عندما يبدأ المستخدم في الكتابة. تنتهي الجلسة عندما يختار المستخدم مكانًا ويتم إجراء طلب إلى "تفاصيل المكان".

لإنشاء رمز مميّز جديد للجلسة وإضافته إلى طلب، أنشئ مثيلاً من 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.

اقتراحات الرموز المميزة للجلسة:

استخدِم رموز الجلسات لجميع طلبات Place Autocomplete.
إنشاء رمز مميّز جديد لكل جلسة
مرِّر رمزًا مميزًا فريدًا للجلسة لكل جلسة جديدة. سيؤدي استخدام الرمز المميز نفسه لأكثر من جلسة واحدة إلى تحصيل رسوم كل طلب على حدة.

يمكنك اختياريًا حذف رمز الجلسة للإكمال التلقائي من الطلب. في حال عدم تضمين رمز الجلسة، يتم تحصيل رسوم كل طلب على حدة، ما يؤدي إلى تفعيل وحدة حفظ المخزون الإكمال التلقائي - لكل طلب. في حال إعادة استخدام رمز مميّز للجلسة، سيتم اعتبار الجلسة غير صالحة وسيتم تحصيل رسوم مقابل الطلبات كما لو لم يتم تقديم رمز مميّز للجلسة.

مثال

أثناء كتابة المستخدم لطلب بحث، يتم إرسال طلب إكمال تلقائي كل بضع ضغطات على المفاتيح (وليس لكل حرف)، ويتم عرض قائمة بالنتائج المحتملة. عندما يختار المستخدم نتيجة من قائمة النتائج، يتم احتساب هذا الاختيار كطلب، ويتم تجميع كل الطلبات التي تم إجراؤها أثناء البحث واحتسابها كطلب واحد. إذا اختار المستخدم مكانًا، سيكون طلب البحث متاحًا بدون أي رسوم، وسيتم تحصيل رسوم طلب بيانات المكان فقط. إذا لم يحدّد المستخدم أي خيار خلال بضع دقائق من بداية الجلسة، سيتم تحصيل رسوم مقابل طلب البحث فقط.

من منظور التطبيق، يكون تسلسل الأحداث على النحو التالي:

يبدأ المستخدم في كتابة طلب بحث عن "باريس، فرنسا".
عند رصد إدخال من المستخدم، ينشئ التطبيق رمزًا مميزًا جديدًا للجلسة، وهو "الرمز المميز أ".
أثناء كتابة المستخدم، يرسل واجهة برمجة التطبيقات طلب إكمال تلقائي كل بضعة أحرف، ويعرض قائمة جديدة بالنتائج المحتملة لكل منها:
"ب"
"بر"
"برلين"
"برلين، ألمانيا"
عندما يحدّد المستخدم خيارًا:
- يتم تجميع جميع الطلبات الناتجة عن طلب البحث وإضافتها إلى الجلسة الممثّلة بالرمز المميز "أ"، وذلك كطلب واحد.
- يتم احتساب اختيار المستخدِم كطلب تفاصيل مكان، ويتم إضافته إلى الجلسة الممثّلة بالرمز المميز "الرمز المميز أ".
تنتهي الجلسة، ويتجاهل التطبيق الرمز المميّز "أ".

مزيد من المعلومات حول كيفية فوترة الجلسات

مثال على الرمز البرمجي الكامل

يحتوي هذا القسم على أمثلة كاملة توضّح كيفية استخدام 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() استنادًا إلى طلبات البحث التي يقدّمها المستخدمون وعرض قائمة بالأماكن المتوقّعة استجابةً لذلك
استخدام رموز الجلسات المميزة لتجميع طلب بحث مستخدم مع طلب "تفاصيل المكان" النهائي
استرداد تفاصيل المكان المحدّد وعرض علامة.
استخدام ميزة "تضمين عناصر التحكّم" لتضمين عناصر واجهة المستخدم في العنصر 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.
التعرّف على حقول البيانات الأساسية لخاصية "الإكمال التلقائي" (جديد) من البداية
حقلَي "تفضيل الموقع الجغرافي" و"حظر الموقع الجغرافي" اختياريان، ولكن يمكن أن يكون لهما تأثير كبير في أداء ميزة "الإكمال التلقائي".
استخدِم ميزة معالجة الأخطاء للتأكّد من أنّ تطبيقك يتراجع بشكل سليم في حال عرض واجهة برمجة التطبيقات رسالة خطأ.
تأكَّد من أنّ تطبيقك يتعامل مع الحالات التي لا يتم فيها تحديد أي خيار، وأنّه يوفّر للمستخدمين طريقة لمواصلة الاستخدام.

أفضل الممارسات لتحسين التكلفة

تحسين التكلفة الأساسية

لتحسين تكلفة استخدام خدمة "الإكمال التلقائي" (الإصدار الجديد)، استخدِم أقنعة الحقول في أدوات "تفاصيل المكان" (الإصدار الجديد) و"الإكمال التلقائي" (الإصدار الجديد) لعرض حقول البيانات التي تحتاج إليها فقط في "الإكمال التلقائي" (الإصدار الجديد).

تحسين التكلفة بشكلٍ متقدّم

ننصحك بتنفيذ ميزة "الإكمال التلقائي (جديدة)" آليًا للوصول إلى رمز التخزين التعريفي: أسعار طلبات الإكمال التلقائي وطلب نتائج Geocoding API حول المكان المحدّد بدلاً من "تفاصيل المكان (جديدة)". يكون التسعير لكل طلب مقترنًا بواجهة برمجة التطبيقات Geocoding API أكثر فعالية من حيث التكلفة من التسعير لكل جلسة (استنادًا إلى الجلسة) في حال استيفاء الشرطَين التاليَين:

إذا كنت تحتاج فقط إلى خطوط الطول والعرض أو عنوان المكان الذي اختاره المستخدم، تقدّم Geocoding API هذه المعلومات بتكلفة أقل من طلب Place Details (New).
إذا اختار المستخدمون نتيجة بحث مقترَحة من ميزة "الإكمال التلقائي" في غضون أربعة طلبات أو أقل من ميزة "الإكمال التلقائي (جديد)"، قد يكون التسعير لكل طلب أكثر فعالية من حيث التكلفة من التسعير لكل جلسة.

للحصول على مساعدة في اختيار عملية تنفيذ ميزة "الإكمال التلقائي (جديد)" التي تناسب احتياجاتك، اختَر علامة التبويب التي تتوافق مع إجابتك عن السؤال التالي.

هل يتطلّب تطبيقك أي معلومات أخرى غير العنوان وخط العرض/خط الطول الخاص بالتوقّع المحدّد؟

نعم، يجب إضافة المزيد من التفاصيل

استخدام ميزة "الإكمال التلقائي" المستندة إلى الجلسة (جديدة) مع ميزة "تفاصيل المكان" (جديدة)
بما أنّ تطبيقك يتطلّب استخدام Place Details (New)، مثل اسم المكان أو حالة النشاط التجاري أو ساعات العمل، يجب أن يستخدم تطبيقك لميزة "الإكمال التلقائي (جديد)" رمزًا مميزًا للجلسة (برمجيًا أو مضمّنًا في أدوات JavaScript أو Android أو iOS) لكل جلسة بالإضافة إلى وحدات SKU المناسبة في Places، وذلك استنادًا إلى حقول بيانات الأماكن التي تطلبها.¹

تنفيذ الأداة
تتضمّن الأدوات JavaScript وAndroid وiOS إدارة الجلسات تلقائيًا. ويشمل ذلك طلبات "الإكمال التلقائي (جديد)" وطلبات "تفاصيل المكان (جديد)" بشأن العبارة المقترَحة المحدّدة. احرص على تحديد المَعلمة fields لضمان طلب حقول البيانات الخاصة بميزة "الإكمال التلقائي" (الجديدة) فقط.

التنفيذ الآلي
استخدِم رمز الجلسة مع طلباتك إلى ميزة "الإكمال التلقائي (الجديدة)". عند طلب تفاصيل المكان (جديد) حول عبارة البحث المقترَحة المحدّدة، أدرِج المَعلمات التالية:

رقم تعريف المكان من ردّ الإكمال التلقائي (جديد)
الرمز المميز للجلسة المستخدَم في طلب "الإكمال التلقائي (جديد)"
المَعلمة fields التي تحدّد حقول البيانات للإكمال التلقائي (جديد) التي تحتاج إليها

لا، يحتاج فقط إلى العنوان والموقع الجغرافي

قد تكون Geocoding API خيارًا أكثر فعالية من حيث التكلفة من Place Details (New) لتطبيقك، وذلك استنادًا إلى أداء استخدامك لخدمة الإكمال التلقائي (جديدة). تختلف كفاءة ميزة "الإكمال التلقائي (جديدة)" في كل تطبيق حسب ما يدخله المستخدمون ومكان استخدام التطبيق وما إذا تم تنفيذ أفضل الممارسات لتحسين الأداء.

للإجابة عن السؤال التالي، حلِّل عدد الأحرف التي يكتبها المستخدم في المتوسط قبل اختيار توقّع "الإكمال التلقائي (جديد)" في تطبيقك.

هل يختار المستخدمون توقّعًا من ميزة "الإكمال التلقائي (جديد)" في أربعة طلبات أو أقل، في المتوسط؟

نعم

تنفيذ ميزة "الإكمال التلقائي" (جديدة) آليًا بدون رموز مميّزة للجلسة واستدعاء Geocoding API بشأن توقّع المكان المحدّد
تقدّم Geocoding API العناوين وإحداثيات خطوط العرض والطول. إنّ إجراء أربعة طلبات إكمال تلقائي بالإضافة إلى طلب Geocoding API بشأن عبارة البحث المقترَحة الخاصة بالمكان المحدّد أقل من تكلفة الإكمال التلقائي (الجديد) لكل جلسة.¹

ننصحك باتّباع أفضل الممارسات المتعلّقة بالأداء لمساعدة المستخدمين في الحصول على التوقّع الذي يبحثون عنه بعدد أقل من الأحرف.

لا

استخدام ميزة "الإكمال التلقائي" المستندة إلى الجلسة (جديدة) مع ميزة "تفاصيل المكان" (جديدة)
بما أنّ متوسط عدد الطلبات التي تتوقّع إرسالها قبل أن يختار المستخدم توقّعًا من "الإكمال التلقائي (جديد)" يتجاوز تكلفة التسعير لكل جلسة، يجب أن يستخدم تطبيقك لميزة "الإكمال التلقائي (جديد)" رمزًا مميّزًا للجلسة لكلّ من طلبات "الإكمال التلقائي (جديد)" وطلب "تفاصيل المكان (جديد)" المرتبط لكل جلسة. ¹

تنفيذ الأداة
تتضمّن الأدوات JavaScript أو Android أو iOS إدارة الجلسات تلقائيًا. ويشمل ذلك طلبات "الإكمال التلقائي (جديد)" وطلبات "تفاصيل المكان (جديد)" بشأن العبارة المقترَحة المحدّدة. احرص على تحديد المَعلمة fields للتأكّد من أنّك تطلب الحقول التي تحتاج إليها فقط.

التنفيذ الآلي
استخدِم رمز الجلسة مع طلبات "الإكمال التلقائي (جديد)". عند طلب تفاصيل المكان (جديد) حول نتيجة البحث المحدّدة، يجب تضمين المَعلمات التالية:

رقم تعريف المكان من ردّ الإكمال التلقائي (جديد)
الرمز المميز للجلسة المستخدَم في طلب "الإكمال التلقائي (جديد)"
المَعلمة fields التي تحدّد الحقول، مثل العنوان والشكل الهندسي

تأخير طلبات "الإكمال التلقائي (جديد)"
يمكنك استخدام استراتيجيات مثل تأخير طلب "الإكمال التلقائي (جديد)" إلى أن يكتب المستخدم الأحرف الثلاثة أو الأربعة الأولى، وذلك لكي يقدّم تطبيقك عددًا أقل من الطلبات. على سبيل المثال، يعني تقديم طلبات "الإكمال التلقائي (جديد)" لكل حرف بعد أن يكتب المستخدم الحرف الثالث أنّه إذا كتب المستخدم سبعة أحرف ثم اختار عبارة بحث مقترَحة تقدّم لها طلبًا واحدًا إلى Geocoding API، ستكون التكلفة الإجمالية هي 4 طلبات "إكمال تلقائي (جديد)" لكل طلب + Geocoding.¹

إذا كان تأخير الطلبات سيؤدي إلى خفض متوسط طلبات الإعلانات الآلية إلى أقل من أربعة، يمكنك اتّباع الإرشادات المتعلّقة بتنفيذ ميزة "الإكمال التلقائي" (الجديدة) عالية الأداء باستخدام 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. يوجّه هذا الخيار ميزة "الإكمال التلقائي (جديد)" إلى تفضيل عرض النتائج ضمن المنطقة المحدّدة. قد يستمر عرض النتائج خارج المنطقة المحدّدة. يمكنك استخدام المَعلمة components لفلترة النتائج وعرض الأماكن الواقعة ضمن بلد محدّد فقط.

تحذير: إذا لم يتم توفير radius، سيتم تجاهل المَعلمة location.

لا تحقّق نتائج المؤسسات عادةً ترتيبًا عاليًا يكفي لعرضها في النتائج عندما تكون مساحة البحث كبيرة. إذا أردت أن تظهر المؤسسات في نتائج مختلطة بين المؤسسات والرموز الجغرافية، يمكنك تحديد نطاق أصغر. يمكنك بدلاً من ذلك استخدام types=establishment لحصر النتائج على المؤسسات فقط.

تقييد الموقع الجغرافي

لحصر النتائج في منطقة محدّدة، أضِف المَعلمة locationRestriction.

يمكنك أيضًا حصر النتائج بالمنطقة المحدّدة بواسطة location والمَعلمة radius، وذلك من خلال إضافة المَعلمة locationRestriction. يوجّه هذا الإعداد ميزة "الإكمال التلقائي (الجديدة)" لعرض نتائج فقط ضمن تلك المنطقة.

واجهة برمجة التطبيقات الخاصة بميزة "الإكمال التلقائي للأماكن" تنظيم صفحاتك في مجموعات يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.

طلبات الإكمال التلقائي

تقييد عبارات البحث المقترَحة من ميزة "الإكمال التلقائي"

الحصول على تفاصيل المكان

رموز الجلسات المميزة

اقتراحات الرموز المميزة للجلسة:

مثال

مثال على الرمز البرمجي الكامل

عبارات البحث المقترحة من ميزة "الإكمال التلقائي للأماكن"

TypeScript

JavaScript

CSS

HTML

تجربة عيّنة

الإكمال التلقائي للأماكن أثناء الكتابة مع الجلسات

TypeScript

JavaScript

CSS

HTML

تجربة عيّنة

تحسين ميزة "الإكمال التلقائي" (جديد)

أفضل الممارسات لتحسين التكلفة

تحسين التكلفة الأساسية

تحسين التكلفة بشكلٍ متقدّم

نعم، يجب إضافة المزيد من التفاصيل

لا، يحتاج فقط إلى العنوان والموقع الجغرافي

نعم

لا

أفضل الممارسات المتعلّقة بالأداء

تفضيل المواقع الجغرافية

تقييد الموقع الجغرافي

واجهة برمجة التطبيقات الخاصة بميزة "الإكمال التلقائي للأماكن"