الإكمال التلقائي للأماكن

اختَر النظام الأساسي: Android iOS JavaScript خدمة الويب

مقدمة

الإكمال التلقائي هو ميزة في مكتبة الأماكن في واجهة برمجة تطبيقات JavaScript لـ "خرائط Google". يمكنك استخدام ميزة الإكمال التلقائي لمنح تطبيقاتك سلوك البحث المسبق في حقل البحث في "خرائط Google". ويمكن أن تتطابق خدمة الإكمال التلقائي مع الكلمات والسلاسل الفرعية الكاملة، ما يؤدي إلى معالجة أسماء الأماكن والعناوين ورموز الجمع. وبالتالي، يمكن للتطبيقات إرسال طلبات البحث حسب أنواع المستخدمين، وذلك لتوفير توقعات فورية عن الأماكن.

الخطوات الأولى

قبل استخدام مكتبة الأماكن في واجهة برمجة تطبيقات JavaScript للخرائط، تأكّد أولاً من تفعيل واجهة Places API في Google Cloud Console، في المشروع نفسه الذي أعددته لواجهة Maps JavaScript API.

لعرض قائمة واجهات برمجة التطبيقات المفعَّلة:

  1. انتقِل إلى Google Cloud Console.
  2. انقر على الزرّ اختيار مشروع، ثم اختَر المشروع نفسه الذي أعددته لواجهة برمجة تطبيقات JavaScript للخرائط وانقر على فتح.
  3. من قائمة واجهات برمجة التطبيقات في لوحة البيانات، ابحث عن واجهة برمجة تطبيقات الأماكن.
  4. إذا رأيت واجهة برمجة التطبيقات في القائمة، يعني ذلك أنّك جاهز. إذا لم تكن واجهة برمجة التطبيقات مدرَجة، يمكنك تفعيلها:
    1. في أعلى الصفحة، انقر على ENABLE API لعرض علامة تبويب المكتبة. يمكنك أيضًا اختيار المكتبة من القائمة الجانبية اليمنى.
    2. ابحث عن Places API، ثم اختَرها من قائمة النتائج.
    3. انقر على تفعيل. عند انتهاء العملية، تظهر Places API في قائمة واجهات برمجة التطبيقات في لوحة البيانات.

جارٍ تحميل المكتبة

خدمة "الأماكن" هي مكتبة مستقلة عن رمز واجهة برمجة تطبيقات JavaScript لـ "خرائط Google" الرئيسي. لاستخدام الوظائف المضمَّنة في هذه المكتبة، يجب أولاً تحميلها باستخدام المَعلمة libraries في عنوان URL الخاص ببدء تشغيل واجهة برمجة تطبيقات "خرائط Google":

<script async
    src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&loading=async&libraries=places&callback=initMap">
</script>

لمزيد من المعلومات، يمكنك الاطّلاع على نظرة عامة على المكتبات.

ملخّص الصفوف

توفّر واجهة برمجة التطبيقات نوعَين من التطبيقات المصغّرة للإكمال التلقائي، يمكنك إضافتهما من خلال الصفَّين Autocomplete وSearchBox على التوالي. بالإضافة إلى ذلك، يمكنك استخدام الفئة AutocompleteService لاسترداد نتائج الإكمال التلقائي بشكل آلي (يمكنك الاطّلاع على مرجع واجهة برمجة تطبيقات JavaScript لـ "خرائط Google": فئة AutocompleteService).

في ما يلي ملخّص عن الصفوف المتاحة:

  • Autocomplete يضيف حقل إدخال نص إلى صفحة الويب ويراقب هذا الحقل بحثًا عن إدخالات الأحرف. بينما يُدخِل المستخدم النص، تعرض ميزة الإكمال التلقائي توقّعات الأماكن على شكل قائمة اختيار منسدلة. عندما يختار المستخدم مكانًا من القائمة، يتم عرض معلومات عن المكان في عنصر الإكمال التلقائي، ويمكن للتطبيق استرداده. يمكنك الاطّلاع على التفاصيل أدناه.
    حقل نصي للإكمال التلقائي وقائمة اختيارات لتوقّعات الأماكن التي يتم تقديمها عندما يُدخِل المستخدم طلب البحث.
    الشكل 1: الإكمال التلقائي لحقل النص وقائمة الاختيار
    نموذج عنوان مكتمل.
    الشكل 2: نموذج العناوين المكتمل
  • يضيف SearchBox حقل إدخال نص إلى صفحة الويب بالطريقة نفسها التي يضيفها Autocomplete. وفي ما يلي الاختلافات:
    • يكمن الاختلاف الرئيسي في النتائج التي تظهر ضمن قائمة الاختيار. وتوفّر دالة SearchBox قائمة موسّعة من عبارات البحث المقترحة التي يمكن أن تشمل أماكن (على النحو المحدّد في Places API) بالإضافة إلى عبارات البحث المقترَحة. على سبيل المثال، إذا أدخل المستخدم عبارة "بيتزا في مطعم جديد"، قد تحتوي قائمة الاختيارات على العبارة "بيتزا في دبي" بالإضافة إلى أسماء منافذ بيع البيتزا المختلفة.
    • ويقدّم SearchBox خيارات أقل من Autocomplete لحصر عملية البحث. في الطريقة الأولى، يمكنك انحياز البحث نحو عنصر LatLngBounds محدّد. وفي الحالة الثانية، يمكنك حصر البحث ببلد معيّن وأنواع أماكن معيّنة، بالإضافة إلى ضبط الحدود. لمزيد من المعلومات، يمكنك الاطّلاع على أدناه.
    نموذج عنوان مكتمل.
    الشكل 3: يعرض SearchBox عبارات البحث وتوقعات الأماكن.
    يمكنك الاطّلاع على التفاصيل أدناه.
  • يمكنك إنشاء كائن AutocompleteService لاسترداد عبارات البحث المقترَحة بطريقة آلية. يمكنك الاتصال بالرقم getPlacePredictions() لاسترداد الأماكن المطابقة، أو الاتصال بالرقم getQueryPredictions() لاسترداد الأماكن المطابقة بالإضافة إلى عبارات البحث المقترَحة. ملاحظة: لا يضيف AutocompleteService أي عناصر تحكم في واجهة المستخدم. بدلاً من ذلك، تعرض الطرق السابقة صفيفًا من كائنات التنبؤ. يحتوي كل كائن توقّعات على نص عبارة البحث المقترحة، بالإضافة إلى معلومات مرجعية وتفاصيل حول كيفية مطابقة النتيجة مع إدخال المستخدم. يمكنك الاطّلاع على التفاصيل أدناه.

إضافة تطبيق مصغّر للإكمال التلقائي

تنشئ التطبيق المصغَّر Autocomplete حقل إدخال نصي على صفحة الويب، وتوفّر توقعات للأماكن في قائمة خيارات واجهة المستخدم، وتعرض تفاصيل المكان استجابةً لطلب getPlace(). يتوافق كل إدخال في قائمة الاختيارات مع مكان واحد (على النحو المحدّد في Places API).

تستخدم الدالة الإنشائية Autocomplete وسيطتين:

  • عنصر HTML input من النوع text هذا هو حقل الإدخال الذي ستقوم خدمة الإكمال التلقائي بمراقبة نتائجه وإرفاقها به.
  • وسيطة AutocompleteOptions اختيارية يمكن أن تحتوي على السمات التالية:
    • مصفوفة من البيانات fields سيتم تضمينها في استجابة Place Details لحقل PlaceResult الذي اختاره المستخدم. في حال عدم ضبط الموقع أو في حال ضبط ['ALL']، يتم عرض جميع الحقول المتاحة وإرسال الفواتير إليها (لا يُنصَح بهذا الإجراء لعمليات النشر في قناة الإصدار العلني). للحصول على قائمة بالحقول، راجِع PlaceResult.
    • مصفوفة من types تحدّد نوعًا صريحًا أو مجموعة أنواع، كما هو موضّح في الأنواع المتوافقة. إذا لم يتم تحديد أي نوع، يتم عرض جميع الأنواع.
    • bounds هو كائن google.maps.LatLngBounds يحدّد المنطقة التي يجب البحث فيها عن الأماكن. النتائج متحيزة نحو، على سبيل المثال لا الحصر، الأماكن الموجودة داخل هذه الحدود.
    • تمثّل السمة strictBounds السمة boolean لتحديد ما إذا كان يجب أن تعرض واجهة برمجة التطبيقات الأماكن فقط التي تقع ضمن المنطقة المحددة في bounds المحدّدة. ولا تعرض واجهة برمجة التطبيقات نتائج خارج هذه المنطقة حتى إذا كانت تتطابق مع البيانات التي أدخلها المستخدم.
    • يمكن استخدام componentRestrictions لحصر النتائج بمجموعات محدّدة يمكنك حاليًا استخدام componentRestrictions للفلترة حسب ما يصل إلى 5 بلدان. يجب إدخال البلدان كرمز بلد مؤلف من حرفين ومتوافق مع معيار ISO 3166-1 Alpha-2. يجب إدراج عدة بلدان كقائمة رموز البلدان.

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

    • يمكن استخدام placeIdOnly لتوجيه تطبيق Autocomplete المصغّر لاسترداد أرقام تعريف الأماكن فقط. عند استدعاء getPlace() على الكائن Autocomplete، سيتم ضبط الخصائص PlaceResult المتاحة فقط على place id وtypes وname. يمكنك استخدام معرّف المكان الذي تم إرجاعه مع مكالمات إلى خدمات "الأماكن" أو "الترميز الجغرافي" أو الاتجاهات أو مصفوفة المسافة.

تقييد توقعات الإكمال التلقائي

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

ضبط الخيارات أثناء البناء

تقبل الدالة الإنشائية Autocomplete المعلَمة AutocompleteOptions لضبط قيود عند إنشاء أداة. يحدّد المثال التالي الخيارات bounds وcomponentRestrictions وtypes لطلب أماكن من النوع establishment، مع تفضيلها ضمن المنطقة الجغرافية المحدّدة وحصر التوقّعات بالأماكن في الولايات المتحدة فقط. عند ضبط الخيار fields، يتم تحديد المعلومات التي يجب عرضها حول المكان الذي اختاره المستخدم.

يمكنك استدعاء setOptions() لتغيير قيمة أحد الخيارات لأداة حالية.

TypeScript

const center = { lat: 50.064192, lng: -130.605469 };
// Create a bounding box with sides ~10km away from the center point
const defaultBounds = {
  north: center.lat + 0.1,
  south: center.lat - 0.1,
  east: center.lng + 0.1,
  west: center.lng - 0.1,
};
const input = document.getElementById("pac-input") as HTMLInputElement;
const options = {
  bounds: defaultBounds,
  componentRestrictions: { country: "us" },
  fields: ["address_components", "geometry", "icon", "name"],
  strictBounds: false,
};

const autocomplete = new google.maps.places.Autocomplete(input, options);

JavaScript

const center = { lat: 50.064192, lng: -130.605469 };
// Create a bounding box with sides ~10km away from the center point
const defaultBounds = {
  north: center.lat + 0.1,
  south: center.lat - 0.1,
  east: center.lng + 0.1,
  west: center.lng - 0.1,
};
const input = document.getElementById("pac-input");
const options = {
  bounds: defaultBounds,
  componentRestrictions: { country: "us" },
  fields: ["address_components", "geometry", "icon", "name"],
  strictBounds: false,
};
const autocomplete = new google.maps.places.Autocomplete(input, options);

تحديد حقول البيانات

حدِّد حقول البيانات لتجنُّب تحصيل الفواتير منك مقابل رموز التخزين التعريفية لبيانات الأماكن التي لا تحتاج إليها. ضمِّن السمة fields في AutocompleteOptions التي يتم تمريرها إلى الدالة الإنشائية للأداة، كما هو موضّح في المثال السابق، أو استدعِ setFields() في عنصر Autocomplete حالي.

autocomplete.setFields(["place_id", "geometry", "name"]);

تحديد التحيزات وحدود منطقة البحث للإكمال التلقائي

يمكنك التحيّز نتائج الإكمال التلقائي لتفضيل موقع جغرافي أو منطقة تقريبية، وذلك بالطرق التالية:

  • يمكنك ضبط الحدود عند إنشاء العنصر Autocomplete.
  • تغيير الحدود على Autocomplete حالي
  • تعيين الحدود على إطار عرض الخريطة.
  • احصر البحث بالحدود.
  • حصر البحث ببلد معيّن

يوضح المثال السابق حدود الإعداد عند الإنشاء. توضح الأمثلة التالية تقنيات التحيز الأخرى.

تغيير حدود إكمال تلقائي حالي

عليك استدعاء setBounds() لتغيير مساحة البحث على عنصر Autocomplete حالي إلى حدود مستطيلة.

TypeScript

const southwest = { lat: 5.6108, lng: 136.589326 };
const northeast = { lat: 61.179287, lng: 2.64325 };
const newBounds = new google.maps.LatLngBounds(southwest, northeast);

autocomplete.setBounds(newBounds);

JavaScript

const southwest = { lat: 5.6108, lng: 136.589326 };
const northeast = { lat: 61.179287, lng: 2.64325 };
const newBounds = new google.maps.LatLngBounds(southwest, northeast);

autocomplete.setBounds(newBounds);
ضبط الحدود على إطار عرض الخريطة

استخدِم bindTo() لانحياز النتائج في إطار عرض الخريطة، حتى مع تغيّر إطار العرض هذا.

TypeScript

autocomplete.bindTo("bounds", map);

JavaScript

autocomplete.bindTo("bounds", map);

يمكنك استخدام unbind() لإلغاء ربط توقّعات "الإكمال التلقائي" من إطار عرض الخريطة.

TypeScript

autocomplete.unbind("bounds");
autocomplete.setBounds({ east: 180, west: -180, north: 90, south: -90 });

JavaScript

autocomplete.unbind("bounds");
autocomplete.setBounds({ east: 180, west: -180, north: 90, south: -90 });

الاطّلاع على مثال

حصر البحث بالحدود الحالية

يمكنك ضبط الخيار strictBounds لحصر النتائج بالحدود الحالية، سواء كانت مستندة إلى إطار عرض الخريطة أو الحدود المستطيلة.

autocomplete.setOptions({ strictBounds: true });
حصر التوقعات في بلد معيّن

يمكنك استخدام الخيار componentRestrictions أو الاتصال بالرقم setComponentRestrictions() لحصر ميزة البحث ضمن ميزة "الإكمال التلقائي" على عدد محدّد يصل إلى خمسة بلدان.

TypeScript

autocomplete.setComponentRestrictions({
  country: ["us", "pr", "vi", "gu", "mp"],
});

JavaScript

autocomplete.setComponentRestrictions({
  country: ["us", "pr", "vi", "gu", "mp"],
});

الاطّلاع على مثال

تقييد أنواع الأماكن

استخدِم الخيار types أو استدعِ setTypes() لحصر التوقّعات بأنواع معيّنة من الأماكن. يحدد هذا القيد نوعًا أو مجموعة أنواع، كما هو مدرج في أنواع الأماكن. إذا لم يتم تحديد أي قيد، يتم عرض جميع الأنواع.

بالنسبة إلى قيمة الخيار types أو القيمة التي تم تمريرها إلى setTypes()، يمكنك تحديد أحد الخيارَين التاليَين:

سيتم رفض الطلب في الحالات التالية:

  • أنت تحدد أكثر من خمسة أنواع.
  • يمكنك تحديد أي أنواع غير معروفة.
  • تمزج أي أنواع من الجدول 1 أو الجدول 2 مع أي فلتر من الجدول 3.

يوضح العرض التوضيحي لميزة الإكمال التلقائي للأماكن الاختلافات في التوقعات بين أنواع الأماكن المختلفة.

الانتقال إلى العرض التوضيحي

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

عندما يختار المستخدم مكانًا من عبارات البحث المقترحة المرفقة بالحقل النصي للإكمال التلقائي، تنشِّط الخدمة حدث place_changed. للحصول على تفاصيل المكان:

  1. أنشِئ معالج أحداث لحدث place_changed، واستدعِ addListener() في كائن Autocomplete لإضافة المعالج.
  2. يمكنك استدعاء Autocomplete.getPlace() على كائن Autocomplete لاسترداد عنصر PlaceResult الذي يمكنك استخدامه بعد ذلك للحصول على مزيد من المعلومات حول المكان المحدد.

عندما يختار المستخدم مكانًا تلقائيًا، تعرض ميزة الإكمال التلقائي جميع حقول البيانات المتاحة للمكان المحدّد، وسيتم تحصيل الفواتير منك وفقًا لذلك. استخدِم Autocomplete.setFields() لتحديد حقول بيانات الأماكن التي تريد عرضها. يمكنك الاطّلاع على مزيد من المعلومات عن العنصر PlaceResult، بما في ذلك قائمة بحقول بيانات الأماكن التي يمكنك طلبها. لتجنّب الدفع مقابل البيانات التي لا تحتاج إليها، احرص على استخدام السمة Autocomplete.setFields() لتحديد بيانات المكان التي ستستخدمها فقط.

تحتوي السمة name على description من توقّعات الإكمال التلقائي للأماكن. يمكنك الاطّلاع على مزيد من المعلومات حول description في مستندات الإكمال التلقائي للأماكن.

بالنسبة إلى نماذج العناوين، من المفيد الحصول على العنوان في تنسيق مُنظَّم. لعرض العنوان المنظّم للمكان المحدّد، يمكنك استدعاء Autocomplete.setFields() وتحديد الحقل address_components.

يستخدم المثال التالي الإكمال التلقائي لملء الحقول في نموذج عنوان.

TypeScript

function fillInAddress() {
  // Get the place details from the autocomplete object.
  const place = autocomplete.getPlace();
  let address1 = "";
  let postcode = "";

  // Get each component of the address from the place details,
  // and then fill-in the corresponding field on the form.
  // place.address_components are google.maps.GeocoderAddressComponent objects
  // which are documented at http://goo.gle/3l5i5Mr
  for (const component of place.address_components as google.maps.GeocoderAddressComponent[]) {
    // @ts-ignore remove once typings fixed
    const componentType = component.types[0];

    switch (componentType) {
      case "street_number": {
        address1 = `${component.long_name} ${address1}`;
        break;
      }

      case "route": {
        address1 += component.short_name;
        break;
      }

      case "postal_code": {
        postcode = `${component.long_name}${postcode}`;
        break;
      }

      case "postal_code_suffix": {
        postcode = `${postcode}-${component.long_name}`;
        break;
      }

      case "locality":
        (document.querySelector("#locality") as HTMLInputElement).value =
          component.long_name;
        break;

      case "administrative_area_level_1": {
        (document.querySelector("#state") as HTMLInputElement).value =
          component.short_name;
        break;
      }

      case "country":
        (document.querySelector("#country") as HTMLInputElement).value =
          component.long_name;
        break;
    }
  }

  address1Field.value = address1;
  postalField.value = postcode;

  // After filling the form with address components from the Autocomplete
  // prediction, set cursor focus on the second address line to encourage
  // entry of subpremise information such as apartment, unit, or floor number.
  address2Field.focus();
}

JavaScript

function fillInAddress() {
  // Get the place details from the autocomplete object.
  const place = autocomplete.getPlace();
  let address1 = "";
  let postcode = "";

  // Get each component of the address from the place details,
  // and then fill-in the corresponding field on the form.
  // place.address_components are google.maps.GeocoderAddressComponent objects
  // which are documented at http://goo.gle/3l5i5Mr
  for (const component of place.address_components) {
    // @ts-ignore remove once typings fixed
    const componentType = component.types[0];

    switch (componentType) {
      case "street_number": {
        address1 = `${component.long_name} ${address1}`;
        break;
      }

      case "route": {
        address1 += component.short_name;
        break;
      }

      case "postal_code": {
        postcode = `${component.long_name}${postcode}`;
        break;
      }

      case "postal_code_suffix": {
        postcode = `${postcode}-${component.long_name}`;
        break;
      }
      case "locality":
        document.querySelector("#locality").value = component.long_name;
        break;
      case "administrative_area_level_1": {
        document.querySelector("#state").value = component.short_name;
        break;
      }
      case "country":
        document.querySelector("#country").value = component.long_name;
        break;
    }
  }

  address1Field.value = address1;
  postalField.value = postcode;
  // After filling the form with address components from the Autocomplete
  // prediction, set cursor focus on the second address line to encourage
  // entry of subpremise information such as apartment, unit, or floor number.
  address2Field.focus();
}

window.initAutocomplete = initAutocomplete;

الاطّلاع على مثال

تخصيص نص العنصر النائب

بشكل تلقائي، يحتوي حقل النص الذي تم إنشاؤه من خلال خدمة الإكمال التلقائي على نص عنصر نائب عادي. لتعديل النص، اضبط السمة placeholder على العنصر input:

<input id="searchTextField" type="text" size="50" placeholder="Anything you want!">

ملاحظة: تتم ترجمة نص العنصر النائب التلقائي تلقائيًا. وإذا حددت قيمة العنصر النائب الخاصة بك، يجب التعامل مع أقلمة هذه القيمة في تطبيقك. للاطّلاع على معلومات عن آلية تحديد واجهة برمجة تطبيقات JavaScript لـ "خرائط Google" اللغة المطلوب استخدامها، يُرجى قراءة المواد المتعلّقة بالأقلمة.

راجِع تصميم كلٍّ من الإكمال التلقائي وأداة SearchBox لتخصيص مظهر التطبيق المصغّر.

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

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

تستخدم الدالة الإنشائية SearchBox وسيطتين:

  • عنصر HTML input من النوع text وهذا هو حقل الإدخال الذي ستراقب خدمة "SearchBox" نتائجها وتُرفِق بها.
  • الوسيطة options التي يمكن أن تحتوي على السمة bounds: bounds هو عنصر google.maps.LatLngBounds يحدّد المنطقة التي يتم البحث فيها عن الأماكن. وتكون النتائج متحيزة نحو، على سبيل المثال لا الحصر، الأماكن الموجودة ضمن هذه الحدود.

يستخدم الرمز التالي مَعلمة الحدود لانحياز النتائج في أماكن داخل منطقة جغرافية معيّنة، يتم تحديدها من خلال إحداثيات خط العرض/خط الطول.

var defaultBounds = new google.maps.LatLngBounds(
  new google.maps.LatLng(-33.8902, 151.1759),
  new google.maps.LatLng(-33.8474, 151.2631));

var input = document.getElementById('searchTextField');

var searchBox = new google.maps.places.SearchBox(input, {
  bounds: defaultBounds
});

تغيير منطقة البحث في SearchBox

لتغيير منطقة البحث عن عنصر SearchBox حالي، استدعِ setBounds() في عنصر SearchBox ومرِّر كائن LatLngBounds ذي الصلة.

الاطّلاع على مثال

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

عندما يختار المستخدم عنصرًا من عبارات البحث المقترحة المرفقة بمربّع البحث، تنشِّط الخدمة حدث places_changed. يمكنك استدعاء getPlaces() على الكائن SearchBox لاسترداد مصفوفة تحتوي على عدة عبارات بحث مقترَحة، وجميعها عبارة عن كائن PlaceResult.

للحصول على مزيد من المعلومات حول الكائن PlaceResult، يمكنك الاطّلاع على المستندات حول النتائج التفصيلية عن المكان.

TypeScript

// Listen for the event fired when the user selects a prediction and retrieve
// more details for that place.
searchBox.addListener("places_changed", () => {
  const places = searchBox.getPlaces();

  if (places.length == 0) {
    return;
  }

  // Clear out the old markers.
  markers.forEach((marker) => {
    marker.setMap(null);
  });
  markers = [];

  // For each place, get the icon, name and location.
  const bounds = new google.maps.LatLngBounds();

  places.forEach((place) => {
    if (!place.geometry || !place.geometry.location) {
      console.log("Returned place contains no geometry");
      return;
    }

    const icon = {
      url: place.icon as string,
      size: new google.maps.Size(71, 71),
      origin: new google.maps.Point(0, 0),
      anchor: new google.maps.Point(17, 34),
      scaledSize: new google.maps.Size(25, 25),
    };

    // Create a marker for each place.
    markers.push(
      new google.maps.Marker({
        map,
        icon,
        title: place.name,
        position: place.geometry.location,
      })
    );

    if (place.geometry.viewport) {
      // Only geocodes have viewport.
      bounds.union(place.geometry.viewport);
    } else {
      bounds.extend(place.geometry.location);
    }
  });
  map.fitBounds(bounds);
});

JavaScript

// Listen for the event fired when the user selects a prediction and retrieve
// more details for that place.
searchBox.addListener("places_changed", () => {
  const places = searchBox.getPlaces();

  if (places.length == 0) {
    return;
  }

  // Clear out the old markers.
  markers.forEach((marker) => {
    marker.setMap(null);
  });
  markers = [];

  // For each place, get the icon, name and location.
  const bounds = new google.maps.LatLngBounds();

  places.forEach((place) => {
    if (!place.geometry || !place.geometry.location) {
      console.log("Returned place contains no geometry");
      return;
    }

    const icon = {
      url: place.icon,
      size: new google.maps.Size(71, 71),
      origin: new google.maps.Point(0, 0),
      anchor: new google.maps.Point(17, 34),
      scaledSize: new google.maps.Size(25, 25),
    };

    // Create a marker for each place.
    markers.push(
      new google.maps.Marker({
        map,
        icon,
        title: place.name,
        position: place.geometry.location,
      }),
    );
    if (place.geometry.viewport) {
      // Only geocodes have viewport.
      bounds.union(place.geometry.viewport);
    } else {
      bounds.extend(place.geometry.location);
    }
  });
  map.fitBounds(bounds);
});

الاطّلاع على مثال

راجِع تصميم كلٍّ من الإكمال التلقائي وأداة SearchBox لتخصيص مظهر التطبيق المصغّر.

استرداد توقعات خدمة الإكمال التلقائي للأماكن بشكل آلي

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

يعرض لك النطاق AutocompleteService الطرق التالية:

  • توقّعات مكان إرجاع سلع getPlacePredictions() ملاحظة: يمكن أن يكون "المكان" مؤسسة أو موقعًا جغرافيًا أو نقطة اهتمام بارزة، على النحو المحدّد في Places API.
  • تعرض getQueryPredictions() قائمة موسّعة من عبارات البحث المقترحة التي يمكن أن تشمل أماكن (كما هو موضّح في Places API) بالإضافة إلى عبارات البحث المقترَحة. على سبيل المثال، إذا أدخل المستخدم عبارة "بيتزا في مطعم جديد"، قد تحتوي قائمة الاختيارات على العبارة "فطائر في دبي" بالإضافة إلى أسماء مطاعم البيتزا المختلفة.

تعرض كلتا الطريقتين السابقتين مصفوفة من كائنات التوقع بالنموذج التالي:

  • description هي عبارة البحث المقترحة المطابقة.
  • distance_meters هي المسافة بالأمتار من المكان عن AutocompletionRequest.origin المحدّد.
  • يحتوي matched_substrings على مجموعة من السلاسل الفرعية في الوصف التي تُطابق العناصر في البيانات التي أدخلها المستخدم. ويساعد ذلك في تمييز تلك السلاسل الفرعية في تطبيقك. وفي كثير من الحالات، سيظهر طلب البحث كسلسلة فرعية من حقل الوصف.
    • length هو طول السلسلة الفرعية.
    • offset هي إزاحة الأحرف، ويتم قياسها من بداية سلسلة الوصف، التي تظهر فيها السلسلة الفرعية المطابقة.
  • place_id هو معرّف نصي يعرّف المكان بشكل فريد. للحصول على معلومات عن المكان، أدخِل هذا المعرّف في الحقل placeId في طلب تفاصيل المكان. مزيد من المعلومات عن كيفية الإشارة إلى مكان باستخدام رقم تعريف المكان
  • terms عبارة عن مصفوفة تحتوي على عناصر من طلب البحث. بالنسبة إلى المكان، يشكل كل عنصر عادةً جزءًا من العنوان.
    • offset هي إزاحة الأحرف، ويتم قياسها من بداية سلسلة الوصف، التي تظهر فيها السلسلة الفرعية المطابقة.
    • value هي العبارة المطابقة.

ينفّذ المثال التالي طلب توقّع طلب بحث للعبارة 'بيتزا بالقرب من' ويعرض النتيجة في قائمة.

TypeScript

// This example retrieves autocomplete predictions programmatically from the
// autocomplete service, and displays them as an HTML list.
// This example requires the Places library. Include the libraries=places
// parameter when you first load the API. For example:
// <script src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&libraries=places">
function initService(): void {
  const displaySuggestions = function (
    predictions: google.maps.places.QueryAutocompletePrediction[] | null,
    status: google.maps.places.PlacesServiceStatus
  ) {
    if (status != google.maps.places.PlacesServiceStatus.OK || !predictions) {
      alert(status);
      return;
    }

    predictions.forEach((prediction) => {
      const li = document.createElement("li");

      li.appendChild(document.createTextNode(prediction.description));
      (document.getElementById("results") as HTMLUListElement).appendChild(li);
    });
  };

  const service = new google.maps.places.AutocompleteService();

  service.getQueryPredictions({ input: "pizza near Syd" }, displaySuggestions);
}

declare global {
  interface Window {
    initService: () => void;
  }
}
window.initService = initService;

JavaScript

// This example retrieves autocomplete predictions programmatically from the
// autocomplete service, and displays them as an HTML list.
// This example requires the Places library. Include the libraries=places
// parameter when you first load the API. For example:
// <script src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&libraries=places">
function initService() {
  const displaySuggestions = function (predictions, status) {
    if (status != google.maps.places.PlacesServiceStatus.OK || !predictions) {
      alert(status);
      return;
    }

    predictions.forEach((prediction) => {
      const li = document.createElement("li");

      li.appendChild(document.createTextNode(prediction.description));
      document.getElementById("results").appendChild(li);
    });
  };

  const service = new google.maps.places.AutocompleteService();

  service.getQueryPredictions({ input: "pizza near Syd" }, displaySuggestions);
}

window.initService = initService;

CSS

HTML

<html>
  <head>
    <title>Retrieving Autocomplete Predictions</title>
    <script src="https://polyfill.io/v3/polyfill.min.js?features=default"></script>

    <link rel="stylesheet" type="text/css" href="./style.css" />
    <script type="module" src="./index.js"></script>
  </head>
  <body>
    <p>Query suggestions for 'pizza near Syd':</p>
    <ul id="results"></ul>
    <!-- Replace Powered By Google image src with self hosted image. https://developers.google.com/maps/documentation/places/web-service/policies#other_attribution_requirements -->
    <img
      class="powered-by-google"
      src="https://storage.googleapis.com/geo-devrel-public-buckets/powered_by_google_on_white.png"
      alt="Powered by Google"
    />

    <!-- 
      The `defer` attribute causes the callback to execute after the full HTML
      document has been parsed. For non-blocking uses, avoiding race conditions,
      and consistent behavior across browsers, consider loading using Promises.
      See https://developers.google.com/maps/documentation/javascript/load-maps-js-api
      for more information.
      -->
    <script
      src="https://maps.googleapis.com/maps/api/js?key=AIzaSyB41DRUbKWJHPxaFjMAwdrzWzbVKartNGg&callback=initService&libraries=places&v=weekly"
      defer
    ></script>
  </body>
</html>

تجربة النموذج

الاطّلاع على مثال

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

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

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

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

يوضّح المثال التالي إنشاء رمز مميّز للجلسة، ثم تمريره في AutocompleteService (تم حذف الدالة displaySuggestions() للإيجاز):

// Create a new session token.
var sessionToken = new google.maps.places.AutocompleteSessionToken();

// Pass the token to the autocomplete service.
var autocompleteService = new google.maps.places.AutocompleteService();
autocompleteService.getPlacePredictions({
  input: 'pizza near Syd',
  sessionToken: sessionToken
},
displaySuggestions);

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

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

تصميم تطبيقَي الإكمال التلقائي وSearchBox

يتم تلقائيًا تصميم عناصر واجهة المستخدم المقدَّمة من Autocomplete وSearchBox بحيث يتم تضمينها على خريطة Google. ويمكنك تعديل التصميم ليلائم موقعك الإلكتروني. تتوفّر فئات CSS التالية. تنطبق جميع الصفوف المدرَجة أدناه على كلٍّ من تطبيقَي Autocomplete وSearchBox المصغّر.

صورة توضيحية رسومية لفئات CSS لتطبيقَي الإكمال التلقائي
      وSearchBox
صفوف CSS لأدوات الإكمال التلقائي وSearchBox
فئة CSS الوصف
pac-container العنصر المرئي الذي يحتوي على قائمة بعبارات البحث المقترحة التي تعرضها خدمة الإكمال التلقائي للأماكن تظهر هذه القائمة كقائمة منسدلة أسفل التطبيق المصغّر Autocomplete أو SearchBox.
pac-icon الرمز الذي يظهر إلى يمين كل عنصر في قائمة عبارات البحث المقترَحة.
pac-item عنصر في قائمة التوقّعات المقدّمة من التطبيق المصغّر Autocomplete أو SearchBox.
pac-item:hover يشير ذلك إلى العنصر الذي يمرِّر المستخدم فوقه بمؤشر الماوس.
pac-item-selected تمثّل هذه السمة العنصر عندما يختاره المستخدم عن طريق لوحة المفاتيح. ملاحظة: ستكون العناصر التي تم اختيارها عضوًا في هذا الصف والصف pac-item.
pac-item-query تمثّل هذه السمة مدى داخل pac-item وهو الجزء الرئيسي في التوقّع. بالنسبة إلى المواقع الجغرافية، يجب تضمين اسم المكان، مثل "سيدني"، أو اسم شارع ورقمه، مثل "10 شارع السلام". وبالنسبة إلى عمليات البحث النصية، مثل "فطائر في دبي"، يجب أن تحتوي النتيجة على النص الكامل لطلب البحث. يكون اللون pac-item-query باللون الأسود تلقائيًا. إذا كان هناك أي نص إضافي في pac-item، يكون خارج pac-item-query ويكتسب نمطه من pac-item. لونه رمادي بشكل افتراضي. ويكون النص الإضافي عادةً عنوانًا.
pac-matched جزء التوقع المعروض الذي يتطابق مع إدخال المستخدم. ويتم تمييز هذا النص المطابق تلقائيًا بنص غامق. يُرجى العِلم أنّ النص المطابِق قد يظهر في أي مكان ضمن pac-item. وليس بالضرورة أن يكون جزءًا من pac-item-query، ويمكن أن يكون جزءًا من النص المتبقي في pac-item بالإضافة إلى جزء منه.pac-item-query

استخدام مكوِّن "أداة اختيار الأماكن"

ملاحظة: يستخدم هذا النموذج مكتبة مفتوحة المصدر. يمكنك الاطّلاع على ملف README للحصول على الدعم والملاحظات المتعلقة بالمكتبة.

جرِّب مكوّنات الويب. استخدِم مكوّن الويب "أداة اختيار المكان" لتفعيل إدخال النص الذي يسمح للمستخدمين بالبحث عن عنوان أو مكان محدّد باستخدام الإكمال التلقائي.

ملف GIF مع مربّع البحث يبدأ المستخدم في كتابة عنوان كإدخال وتظهر قائمة منسدلة بالعناوين ذات الصلة. ينقر المستخدم على عنوان من القائمة المنسدلة وسيملأ مربّع البحث بقية العنوان.
الشكل 1: إدخال نص للبحث عن عنوان أو مكان محدّد باستخدام ميزة "الإكمال التلقائي"

تحسين الإكمال التلقائي للأماكن

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

في ما يلي بعض الإرشادات العامة:

  • تتمثل أسرع طريقة لتطوير واجهة مستخدم عاملة في استخدام واجهة برمجة تطبيقات JavaScript لـ "خرائط Google" أداة الإكمال التلقائي أو حزمة تطوير البرامج (SDK) للأماكن المخصّصة لنظام التشغيل Android أو أداة الإكمال التلقائي أو حزمة تطوير البرامج للأماكن المخصّصة لنظام التشغيل iOS التحكم في الإكمال التلقائي لواجهة المستخدم
  • فهم حقول البيانات الأساسية الخاصة بالإكمال التلقائي للأماكن من البداية
  • يُعدّ حقلا "انحياز الموقع الجغرافي" و"حظر الموقع الجغرافي" اختياريًا، ولكن قد يكون لهما تأثير كبير في أداء الإكمال التلقائي.
  • استخدِم معالجة الأخطاء لضمان تراجع أداء تطبيقك بشكل آمن إذا ظهرت واجهة برمجة التطبيقات خطأ.
  • تأكَّد من أنّ تطبيقك يعالجه في حال عدم تحديد أي خيار، وأنّه يوفِّر للمستخدمين طريقة للمتابعة.

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

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

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

التحسين المتقدم للتكلفة

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

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

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

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

استخدام ميزة "الإكمال التلقائي" المستندة إلى الجلسة لـ "تفاصيل المكان"
بما أنّ طلبك يتطلّب "تفاصيل المكان"، مثل اسم المكان أو حالة النشاط التجاري أو ساعات العمل، يجب أن تستخدِم ميزة "الإكمال التلقائي" الخاصة بالمكان رمزًا مميّزًا للجلسة (آليًا أو مُدمجًا في أدوات JavaScript أو Android أو iOS) بتكلفة إجمالية تبلغ 0.017 دولار أمريكي لكل جلسة بالإضافة إلى رموز التخزين التعريفية لبيانات الأماكن السارية بناءً على حقول بيانات الأماكن التي تطلبها.

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

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

  1. رقم تعريف المكان من رد الإكمال التلقائي للمكان
  2. الرمز المميز للجلسة المستخدَم في طلب الإكمال التلقائي لـ "المكان"
  3. معلمة fields التي تحدد حقول بيانات المكان التي تحتاجها

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

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

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

هل يختار المستخدمون في مؤسستك عبارة بحث مقترحة خاصة بميزة "الإكمال التلقائي" عن الأماكن من خلال أربعة طلبات أو أقل في المتوسط؟

نعم

تنفيذ ميزة الإكمال التلقائي للأماكن بشكل آلي بدون الرموز المميّزة للجلسة وطلب واجهة برمجة التطبيقات Geocoding API عند اقتراح المكان المحدّد
توفّر واجهة برمجة التطبيقات للترميز الجغرافي العناوين وإحداثيات خطوط الطول/العرض مقابل 0.005 دولار أمريكي (أو ما يعادله بالعملة المحلية) لكل طلب. يكلّف إجراء أربعة طلبات من طلبات الإكمال التلقائي - حسب الطلب 0.01132 دولار أمريكي، وبالتالي سيكون إجمالي التكلفة لأربعة طلبات بالإضافة إلى طلب بيانات واجهة برمجة التطبيقات للترميز الجغرافي حول توقّع المكان المحدّد هو 0.01632 دولار أمريكي، وهو أقل من سعر الإكمال التلقائي لكل جلسة الذي يبلغ 0.017 دولار أمريكي لكل جلسة.1

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

لا

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

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

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

  1. رقم تعريف المكان من رد الإكمال التلقائي للمكان
  2. الرمز المميز للجلسة المستخدَم في طلب الإكمال التلقائي لـ "المكان"
  3. المعلمة fields التي تحدد حقول البيانات الأساسية مثل العنوان والشكل الهندسي

تأخير طلبات الإكمال التلقائي لـ "الأماكن"
يمكنك استخدام استراتيجيات مثل تأخير طلب الإكمال التلقائي الخاص بالأماكن إلى أن يكتب المستخدم أول ثلاثة أو أربعة أحرف حتى يتمكّن تطبيقك من تقديم عدد أقل من الطلبات. على سبيل المثال، يعني تقديم طلبات الإكمال التلقائي لـ "أماكن" لكل حرف بعد كتابة المستخدم الحرف الثالث يعني أنه إذا كتب المستخدم سبعة أحرف ثم اختار توقعًا يمكنك تقديم طلب واحد له من واجهة برمجة التطبيقات للترميز الجغرافي، ستكون التكلفة الإجمالية 0.01632 دولار أمريكي (4 * 0.00283 إكمال تلقائي لكل طلب + 0.005 ترميز جغرافي).1

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

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


  1. التكاليف المُدرَجة هنا بالدولار الأمريكي. يُرجى الرجوع إلى صفحة الفوترة في "منصة خرائط Google" للحصول على معلومات كاملة عن الأسعار.

أفضل ممارسات الأداء

توضّح الإرشادات التالية طرق تحسين أداء الإكمال التلقائي للأماكن:

  • أضِف القيود المفروضة على البلدان وانحياز الموقع الجغرافي وإعدادات اللغة المفضّلة (في عمليات التنفيذ الآلية) إلى تنفيذ ميزة الإكمال التلقائي للأماكن. ولا حاجة إلى استخدام الإعدادات المفضّلة للغة في التطبيقات المصغّرة لأنّها تختار الإعدادات المفضّلة للّغة من متصفّح المستخدم أو جهازه الجوّال.
  • إذا كان الإكمال التلقائي للأماكن مصحوبًا بخريطة، يمكنك تحيز الموقع بواسطة إطار عرض الخريطة.
  • في الحالات التي لا يختار فيها المستخدم إحدى عبارات البحث المقترحة من ميزة "الإكمال التلقائي"، وبما أنّ أيًا من عبارات البحث المقترحة هذا ليس عنوان النتيجة المطلوبة، يمكنك إعادة استخدام البيانات التي أدخلها المستخدم بهدف الحصول على نتائج أكثر صلة باهتماماتك، وذلك باتّباع الخطوات التالية: تشمل السيناريوهات الأخرى التي يُفضَّل فيها استخدام واجهة برمجة التطبيقات Geocoding API ما يلي:
    • المستخدمون الذين يُدخِلون عناوين المباني الفرعية في البلدان التي لا تتوفّر فيها ميزة الإكمال التلقائي لعناوين المباني الفرعية، مثل التشيك وإستونيا وليتوانيا. على سبيل المثال، يؤدي العنوان التشيكي "Stroupezznického 3191/17,prha" إلى ظهور توقّع جزئي في ميزة "الإكمال التلقائي" للمكان.
    • المستخدمون الذين يُدخلون عناوين باستخدام بادئات أجزاء الطريق، مثل " 23-30 29th St, Queens" في مدينة نيويورك أو "47-380 شارع الهرم، الإسكندرية" في جزيرة كاواي في مدينة هاواي.

الحدود القصوى للاستخدام والسياسات

الحصص

للحصول على معلومات الحصص والأسعار، راجع مستندات الاستخدام والفوترة الخاصة بـ Places API.

السياسات

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