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

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

مقدمة

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

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

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

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

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

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

خدمة الأماكن هي مكتبة مستقلة ومنفصلة عن رمز واجهة برمجة التطبيقات بلغة JavaScript للخرائط. لاستخدام الوظائف المضمّنة في هذه المكتبة، عليك أولاً تحميلها باستخدام المَعلمة libraries في عنوان URL لبدء تشغيل Maps 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 لخرائط Google: فئة AutocompleteService).

في ما يلي ملخّص للفئات المتاحة:

  • Autocomplete تُضيف حقل إدخال نص إلى صفحة الويب، وتتتبّع هذا الحقل لإدخال الأحرف. وعندما يُدخل المستخدم النص، يقوم الإكمال التلقائي بإرجاع تنبؤات الأماكن في شكل قائمة منسدلة للتحديد. عندما يحدد المستخدم مكانًا من القائمة، فإن المعلومات حول المكان إلى كائن الإكمال التلقائي، ويمكن استردادها من خلال تطبيقك. يمكنك الاطّلاع على التفاصيل أدناه.
    حقل نصي للإكمال التلقائي وقائمة اختيار للأماكن المقترَحة التي يتم عرضها عندما يُدخِل المستخدم طلب البحث
    الشكل 1: حقل نصي للملء التلقائي وقائمة اختيار
    نموذج عنوان مكتمل
    الشكل 2: نموذج العنوان المكتمل
  • يضيف SearchBox حقل إدخال نص إلى صفحة الويب، بالطريقة نفسها التي يضيف بها Autocomplete حقل إدخال نص. في ما يلي الاختلافات:
    • يكمن الاختلاف الرئيسي في النتائج التي تظهر في قائمة الخيارات. مستلزمات SearchBox قائمة موسعة من التوقعات، والتي يمكن أن تشمل أماكن (على النحو المحدد بواسطة Places API) بالإضافة إلى عبارات البحث المقترحة. على سبيل المثال، إذا أدخل المستخدم "بيتزا في القاهرة"، قد تتضمّن قائمة الاختيار العبارة 'بيتزا في القاهرة، القاهرة" بالإضافة إلى أسماء منافذ بيع مختلفة لبيع البيتزا.
    • يقدم SearchBox خيارات أقل من Autocomplete لحظر البحث. في السابق، يمكن أن تؤدي إلى انحياز البحث نحو LatLngBounds معيّن. في الحالة الأخيرة، يمكنك حصر البحث على بلد معيّن وأنواع أماكن معيّنة، بالإضافة إلى ضبط الحدود. لمزيد من المعلومات، يُرجى الاطّلاع على القسم أدناه.
    نموذج عنوان مكتمل
    الشكل 3: يعرض مربّع البحث عبارات البحث وتوقّعات الأماكن.
    يُرجى الاطّلاع على التفاصيل أدناه.
  • يمكنك إنشاء الكائن AutocompleteService المطلوب استرداده والتنبؤات آليًا. اتصل بالرقم getPlacePredictions() ل retrieving matching places، أو اتصل بالرقم getQueryPredictions() ل retrieving matching places plus suggested search terms. ملاحظة: لا تضيف 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. الرمز. يجب ضبط البلدان المتعددة كقائمة لرموز البلدان.

      ملاحظة: إذا تلقيت نتائج غير متوقعة برمز بلد، احرص على إجراء أنك تستخدم رمزًا يتضمن البلدان والأقاليم التابعة المناطق الجغرافية ذات الاهتمام الجغرافي التي تريدها. يمكنك العثور على معلومات عن الرموز على Wikipedia: List of ISO 3166 country codes أو ISO Online Browsing Platform.

    • يمكن استخدام 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);
index.ts

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);

index.js

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

حدِّد حقول البيانات لتجنُّب أن يتم تحصيل رسوم منك مقابل رموز التخزين التعريفية لبيانات "الأماكن" التي لا تحتاج إليها. أدرِج السمة 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);
index.ts

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);

index.js
ضبط الحدود على إطار عرض الخريطة

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

TypeScript

autocomplete.bindTo("bounds", map);
index.ts

JavaScript

autocomplete.bindTo("bounds", map);

index.js

استخدِم unbind() لإزالة ربط توقّعات الإكمال التلقائي بمساحة العرض في الخريطة.

TypeScript

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

JavaScript

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

عرض مثال

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

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

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

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

TypeScript

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

JavaScript

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

index.js

عرض مثال

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

يمكنك استخدام الخيار 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();
}
index.ts

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;

index.js

عرض مثال

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

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

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

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

اطّلِع على تصميم التطبيقات المصغّرة "الإكمال التلقائي" و"مربّع البحث" لتخصيص مظهر التطبيق المصغّر.

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

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

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);
});
index.js

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

اطّلِع على تصميم التطبيقات المصغّرة "الإكمال التلقائي" و"مربّع البحث" لتخصيص مظهر التطبيق المصغّر.

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

لاسترداد التوقعات آليًا، يُرجى استخدام صف واحد (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 هو العبارة المطابِقة.

ينفِّذ المثال أدناه طلب توقّع طلب بحث للعبارة 'pizza near' ويعرض النتيجة في قائمة.

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;
index.ts

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;
index.js

CSS

style.css

HTML

<html>
  <head>
    <title>Retrieving Autocomplete Predictions</title>

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

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

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

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

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

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

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

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

نعم، يجب تقديم المزيد من التفاصيل

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

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

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

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

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

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

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

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

نعم

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

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

لا

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

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

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

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

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

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

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

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

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

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

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

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

الحصص

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

السياسات

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