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

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

مقدمة

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

البدء

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

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

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

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

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

<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 JavaScript للخرائط: فئة AutocompleteService).

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

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

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

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

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

  • عنصر input في HTML من النوع 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، سيتم ضبط السمات place id وtypes وname فقط على السمة PlaceResult المتاحة. ويمكنك استخدام معرّف المكان الذي تم عرضه مع طلبات الوصول إلى خدمات "الأماكن" أو "الترميز الجغرافي" أو "الاتجاهات" أو "مصفوفة المسافة".

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

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

تحديد الخيارات عند البناء

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

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

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

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

  • 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-query وكذلك في باقي النص في pac-item.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

نعم

تنفيذ ميزة "الإكمال التلقائي" لميزة "الإكمال التلقائي" في المكان بشكل آلي بدون الرموز المميزة للجلسة وواجهة برمجة التطبيقات Geocoding API لطلب البحث عن المكان المحدّد
توفّر واجهة برمجة التطبيقات 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, Praha" إلى العثور على توقّع جزئي في ميزة "الإكمال التلقائي" في ميزة "الإكمال التلقائي".
    • المستخدمون الذين يُدخلون عناوين باستخدام بادئات قطاعات الطرق، مثل " 23-30 29th St, Queens" في مدينة نيويورك أو " 47-380 Kamehameha Hwy, Kaneohe" على جزيرة كاواي في هاواي.

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

الحصص

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

السياسات

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