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

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

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

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

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

يمكن لتطبيقك الحصول على قائمة بأسماء الأماكن المتوقّعة و/أو للعناوين من واجهة برمجة تطبيقات الإكمال التلقائي عن طريق طلب 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 متطابقة مع رموز ISO 3166-1، مع بعض الاستثناءات الملحوظة. على سبيل المثال، نطاق المستوى الأعلى الذي يتم ترميزه حسب البلد (ccTLD) في المملكة المتحدة هو "uk" (co.uk.)، لكنّ رمزها وفقًا لمعيار ISO 3166-1 هو gb. (من الناحية الفنية بالنسبة كيان "المملكة المتحدة لبريطانيا العظمى وأيرلندا الشمالية").

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

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

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

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

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

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

  لمزيد من المعلومات، يُرجى مراجعة الرموز المميّزة للجلسة:

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

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

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

تحديد الموقع الجغرافي يحدِّد المنطقة المراد البحث فيها. النتائج خارج النطاق المحدّد المنطقة. يستخدم المثال التالي تقييد الموقع الجغرافي لقصر الطلب على تقييد موقع دائري مع نصف قطر يبلغ 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());
        })
    );

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

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

يحدّد المثال التالي سلسلة طلب بحث "كرة القدم" وتستخدم الوحدة الأساسية أنواع المعلَمات لقصر النتائج على مؤسسات من النوع "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 تلقائيًا.