إكمال تلقائي (جديد)

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

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

على سبيل المثال، يمكنك استدعاء الإكمال التلقائي باستخدام كإدخال سلسلة تحتوي على إدخال جزئي للمستخدم "piz" مع منطقة البحث التي تقتصر على سان فرانسيسكو، كاليفورنيا. يحتوي الرد بعد ذلك على قائمة بتنبؤات الأماكن التي تتطابق مع سلسلة البحث ومنطقة البحث، مثل المطعم الذي يحمل اسم "Sicilian Pizza Kitchen".

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

طلبات الإكمال التلقائي (الجديدة)

يمكن لتطبيقك الحصول على قائمة بأسماء و/أو عناوين الأماكن المتوقّعة من واجهة برمجة تطبيقات الإكمال التلقائي من خلال استدعاء PlacesClient.findAutocompletePredictions() وتمرير كائن FindAutocompletePredictionsRequest. يوضح المثال أدناه مكالمة كاملة إلى PlacesClient.findAutocompletePredictions().

Places.initializeWithNewPlacesApiEnabled(context, apiKey);
final List<Field> placeFields = getPlaceFields();
LatLng center = new LatLng(37.7749, -122.4194);
CircularBounds circle = CircularBounds.newInstance(center, /* radius = */ 5000);
final FindAutocompletePredictionsRequest autocompletePlacesRequest =
    FindAutocompletePredictionsRequest.builder()
            .setQuery("Sicilian piz")
            .setRegionCode("ES")
            .setLocationRestriction(circle)
            .build());
placesClient.findAutocompletePredictions(autoCompletePlacesRequest)
    .addOnSuccessListener(
        (response) -> {
            List<AutocompletePrediction> predictions = response.getResult().getAutocompletePredictions();
          }
    ).addOnFailureListener(
        exception -> {
            Log.e(TAG, "some exception happened" + exception.getMessage());
        })
    );

ردود الإكمال التلقائي (الجديدة)

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

بالنسبة إلى كل مكان متنبأ به، يمكنك استدعاء الطرق التالية لاسترداد تفاصيل المكان:

  • تعرض getFullText(CharacterStyle) النص الكامل لوصف المكان. يعد هذا مزيجًا من النص الأساسي والثانوي. مثال: "برج إيفل، شارع الأناضول في فرنسا، باريس، فرنسا" فضلاً عن ذلك، تتيح لك هذه الطريقة إبراز أقسام الوصف التي تتطابق مع طلب البحث باستخدام نمط من اختيارك، وذلك باستخدام السمة CharacterStyle. المعلمة CharacterStyle اختيارية. قم بتعيينها على قيمة فارغة إذا لم تكن بحاجة إلى أي تظليل.
  • تعرض getPrimaryText(CharacterStyle) النص الرئيسي الذي يصف المكان. عادةً ما يكون هذا هو اسم المكان. أمثلة: "برج إيفل"، و123 شارع "بيت".
  • تعرض getSecondaryText(CharacterStyle) النص الفرعي الخاص بوصف المكان. ويكون هذا مفيدًا، على سبيل المثال، كسطر ثانٍ عند عرض توقعات الإكمال التلقائي. أمثلة: "شارع أناتول فرنسا، باريس، فرنسا" و "سيدني، نيو ساوث ويلز".
  • تعرض getPlaceId() معرّف المكان للمكان المتوقّع. معرّف المكان هو معرّف نصي يحدّد مكانًا بشكل فريد، ويمكنك استخدامه لاسترداد كائن Place مرة أخرى لاحقًا. لمزيد من المعلومات عن أرقام تعريف الأماكن في ميزة "الإكمال التلقائي"، راجِع تفاصيل المكان (جديد). للحصول على معلومات عامة حول أرقام تعريف الأماكن، راجِع النظرة العامة على معرّف المكان.
  • يعرض getTypes() قائمة أنواع الأماكن المرتبطة بهذا المكان.
  • تعرض getDistanceMeters() المسافة المستقيمة بالأمتار بين هذا المكان والمصدر المحدّد في الطلب.

المعلمات المطلوبة

  • طلب

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

    لضبط مَعلمة طلب البحث، يمكنك طلب الطريقة setQuery() عند إنشاء العنصر FindAutocompletePredictionsRequest.

المعلمات الاختيارية

  • الأنواع الأساسية

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

    يمكن أن يحتوي المكان على نوع أساسي واحد فقط من أنواع الجدول أ أو الجدول ب المرتبط به. على سبيل المثال، قد يكون النوع الأساسي "mexican_restaurant" أو "steak_house".

    يتم رفض الطلب مع ظهور خطأ INVALID_REQUEST في الحالات التالية:

    • تم تحديد أكثر من خمسة أنواع.
    • تم تحديد أي أنواع غير معروفة.

    لضبط مَعلمة الأنواع الأساسية، يمكنك طلب الطريقة setTypesFilter() عند إنشاء عنصر FindAutocompletePredictionsRequest.

  • البلدان

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

    إذا حدّدت كلاً من locationRestriction وincludedRegionCodes، ستظهر النتائج في المنطقة التي تقع فيها الإعدادَين.

    لضبط مَعلمة البلدان، يمكنك طلب الطريقة setCountries() عند إنشاء الكائن FindAutocompletePredictionsRequest.

  • مدة الإدخال

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

    لضبط مَعلمة إزاحة الإدخال، يمكنك استدعاء الطريقة setInputOffset() عند إنشاء الكائن FindAutocompletePredictionsRequest.

  • تحيز الموقع أو تقييده

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

    • تحيز الموقع

      لتحديد منطقة للبحث. يُعدّ هذا الموقع الجغرافي انحيازًا وليس تقييدًا، وبالتالي قد يتم عرض النتائج خارج المنطقة المحدّدة.

      لضبط مَعلمة انحياز الموقع الجغرافي، يمكنك طلب الطريقة setLocationBias() عند إنشاء عنصر FindAutocompletePredictionsRequest.

    • القيود المفروضة على الموقع الجغرافي

      لتحديد منطقة للبحث. لا يتم عرض النتائج خارج المنطقة المحدّدة.

      لضبط مَعلمة تقييد الموقع الجغرافي، يمكنك طلب الطريقة setLocationRestriction() عند إنشاء عنصر FindAutocompletePredictionsRequest.

    حدِّد انحياز الموقع الجغرافي أو منطقة القيود المفروضة على الموقع الجغرافي كإطار عرض مستطيل أو دائرة.

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

    • المستطيل هو إطار عرض لخطوط الطول والعرض، ويتم تمثيله على شكل نقطتين قطريًا مقابل نقطتَي low وhigh. يُعدّ إطار العرض منطقة مغلقة، ما يعني أنّه يتضمّن حدوده. يجب أن تتراوح حدود خطوط العرض بين -90 و90 درجة ضمنًا، ويجب أن تتراوح حدود خطوط الطول بين -180 و180 درجة، بما في ذلك:

      • إذا كانت low = high، يتكوّن إطار العرض من هذه النقطة الفردية.
      • إذا كانت القيمة low.longitude > high.longitude، يتم قلب نطاق خط الطول (يتجاوز إطار العرض خط الطول الذي يبلغ 180 درجة).
      • إذا كانت قيمة low.longitude = -180 درجة وhigh.longitude = 180 درجة، سيتضمّن إطار العرض جميع خطوط الطول.
      • إذا كانت low.longitude = 180 درجة وhigh.longitude = -180 درجة، يكون نطاق خط الطول فارغًا.

      يجب تعبئة كلّ من low وhigh، ولا يمكن أن يكون المربّع فارغًا. يؤدي استخدام إطار عرض فارغ إلى حدوث خطأ.

  • الأصل

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

    لضبط مَعلمة المصدر، يمكنك طلب الطريقة setOrigin() عند إنشاء الكائن FindAutocompletePredictionsRequest.

  • رمز المنطقة

    تمثّل هذه السمة رمز المنطقة المستخدَم لتنسيق الردّ، بما في ذلك تنسيق العنوان، ويتمّ تحديده على أنّه ccTLD ("نطاق المستوى الأعلى") مؤلف من حرفَين. تتطابق معظم رموز نطاقات المستوى الأعلى التي يتم ترميزها حسب البلد (ccTLD)، مع بعض الاستثناءات الملحوظة. على سبيل المثال، نطاق المستوى الأعلى الذي يتم ترميزه حسب البلد (ccTLD) في المملكة المتحدة هو uk. (co.uk). في حين أنّ رمز ISO 3166-1 الخاص بها هو gb (من الناحية التقنية، تشير وحدة "المملكة المتحدة لبريطانيا العظمى وأيرلندا الشمالية").

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

    لضبط مَعلمة رمز المنطقة، يمكنك طلب الطريقة setRegionCode() عند إنشاء عنصر FindAutocompletePredictionsRequest.

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

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

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

    لضبط مَعلمة الرمز المميّز للجلسة، يمكنك طلب الطريقة setSessionToken() عند إنشاء كائن FindAutocompletePredictionsRequest.

    لمزيد من المعلومات، راجِع الرموز المميّزة للجلسة.

أمثلة على الإكمال التلقائي (جديدة)

استخدام تقييد الموقع الجغرافي وانحياز الموقع الجغرافي

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

تحديد الموقع الجغرافي يحدِّد المنطقة المراد البحث فيها. لا يتم عرض النتائج خارج المنطقة المحدّدة يستخدم المثال التالي تقييد الموقع الجغرافي لقصر الطلب على موقع جغرافي يحصر نطاقه الجغرافي 5000 متر في وسط مدينة سان فرانسيسكو:

Places.initializeWithNewPlacesApiEnabled(context, apiKey);
final List<Field> placeFields = getPlaceFields();

LatLng center = new LatLng(37.7749, -122.4194);
CircularBounds circle = CircularBounds.newInstance(center, /* radius = */ 5000);

final FindAutocompletePredictionsRequest autocompletePlacesRequest =
    FindAutocompletePredictionsRequest.builder()
            .setQuery("Amoeba")
            .setLocationRestriction(circle)
            .build());
placesClient.findAutocompletePredictions(autoCompletePlacesRequest)
    .addOnSuccessListener(
        (response) -> {
            List<AutocompletePrediction> predictions = response.getResult().getAutocompletePredictions();
          }
    ).addOnFailureListener(
        exception -> {
            Log.e(TAG, "some exception happened" + exception.getMessage());
        })
    );

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

Places.initializeWithNewPlacesApiEnabled(context, apiKey);
final List<Field> placeFields = getPlaceFields();

LatLng center = new LatLng(37.7749, -122.4194);
CircularBounds circle = CircularBounds.newInstance(center, /* radius = */ 5000);

final FindAutocompletePredictionsRequest autocompletePlacesRequest =
    FindAutocompletePredictionsRequest.builder()
            .setQuery("Amoeba")
            .setLocationBias(circle)
            .build());
placesClient.findAutocompletePredictions(autoCompletePlacesRequest)
    .addOnSuccessListener(
        (response) -> {
            List<AutocompletePrediction> predictions = response.getResult().getAutocompletePredictions();
          }
    ).addOnFailureListener(
        exception -> {
            Log.e(TAG, "some exception happened" + exception.getMessage());
        })
    );

استخدام الأنواع الأساسية

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

يحدّد المثال التالي سلسلة طلب بحث "كرة القدم" ويستخدم مَعلمة "types" الأساسية لحصر النتائج بمؤسسات من النوع "sporting_goods_store":

Places.initializeWithNewPlacesApiEnabled(context, apiKey);
final List<Field> placeFields = getPlaceFields();

final List<Place.Field> primaryTypes = Arrays.asList("sporting_goods_store");

LatLng center = new LatLng(37.7749, -122.4194);
CircularBounds circle = CircularBounds.newInstance(center, /* radius = */ 5000);

final FindAutocompletePredictionsRequest autocompletePlacesRequest =
    FindAutocompletePredictionsRequest.builder()
            .setQuery("Soccer")
            .setIncludedPrimaryTypes(primaryTypes)
            .setLocationBias(circle)
            .build());
placesClient.findAutocompletePredictions(autoCompletePlacesRequest)
    .addOnSuccessListener(
        (response) -> {
            List<AutocompletePrediction> predictions = response.getResult().getAutocompletePredictions();
          }
    ).addOnFailureListener(
        exception -> {
            Log.e(TAG, "some exception happened" + exception.getMessage());
        })
    );

إذا لم تستخدم معلمة الأنواع الأساسية، يمكن أن تتضمن النتائج منشآت من نوع لا تريده، مثل "athletic_field".

استخدام المصدر

عند تضمين المَعلمة origin في الطلب، المحدّدة كإحداثيات خطوط الطول والعرض، ستتضمّن واجهة برمجة التطبيقات المسافة المستقيمة من نقطة الأصل إلى الوجهة في الردّ (يتم الوصول إليها باستخدام getDistanceMeters()). يضبط هذا المثال المصدر على وسط سان فرانسيسكو:

Places.initializeWithNewPlacesApiEnabled(context, apiKey);
final List<Field> placeFields = getPlaceFields();

LatLng center = new LatLng(37.7749, -122.4194);
CircularBounds circle = CircularBounds.newInstance(center, /* radius = */ 5000);

final FindAutocompletePredictionsRequest autocompletePlacesRequest =
    FindAutocompletePredictionsRequest.builder()
            .setQuery("Amoeba")
            .setOrigin(center)
            .setLocationRestriction(circle)
            .build());
placesClient.findAutocompletePredictions(autoCompletePlacesRequest)
    .addOnSuccessListener(
        (response) -> {
            List<AutocompletePrediction> predictions = response.getResult().getAutocompletePredictions();
          }
    ).addOnFailureListener(
        exception -> {
            Log.e(TAG, "some exception happened" + exception.getMessage());
        })
    );

عمليات تحديد المصدر

يمكنك استخدام الإكمال التلقائي (جديد) حتى بدون خريطة. إذا عرضت خريطة، فيجب أن تكون خريطة Google. عند عرض توقعات من خدمة الإكمال التلقائي (الجديدة) بدون خريطة، عليك تضمين شعار Google المعروض بشكل مضمّن مع حقل/نتائج البحث. ولمزيد من المعلومات، يُرجى الاطّلاع على عرض شعار Google وعمليات الإحالة.