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

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

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

على سبيل المثال، يمكنك استدعاء ميزة "الإكمال التلقائي" باستخدام سلسلة تحتوي على إدخال جزئي من المستخدِم، مثل "بيتزا صقلية"، مع محدودية منطقة البحث إلى سان فرانسيسكو، كاليفورنيا. تحتوي الاستجابة بعد ذلك على قائمة بأماكن التوقّعات التي تتطابق مع سلسلة البحث ومنطقة البحث، مثل المطعم الذي يحمل الاسم "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) تؤدي إلى إرجاع النص الفرعي لوصف المكان. هذا مفيد، مثلاً، كسطر ثانٍ عند عرض توقعات الإكمال التلقائي. أمثلة: "Avenue Anatole France, Paris, France" و"Sydney, New South Wales"
  • getPlaceId() تعرض معرف المكان للمكان المتوقع. معرّف المكان هو معرّف نصي يحدِّد مكانًا بشكل فريد، ويمكنك استخدامه لاسترداد الموضوع Place لاحقًا. لمزيد من المعلومات عن أرقام تعريف الأماكن في الإكمال التلقائي، راجِع تفاصيل المكان. (جديد): عامة معلومات عن أرقام تعريف الأماكن، راجِع رقم تعريف المكان. نظرة عامة.
  • getTypes() تعرض قائمة أنواع الأماكن المرتبطة بهذا المكان.
  • تُعرِض دالة getDistanceMeters() المسافة المستقيمة بالكيلومترات بين هذا المكان و المصدر المحدّد في الطلب.

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

  • طلب البحث

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

    لضبط مَعلمة الطلب، استخدِم طريقة setQuery() عند إنشاء عنصر FindAutocompletePredictionsRequest.

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

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

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

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

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

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

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

  • البلدان

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

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

    لضبط المَعلمة countries، استخدِم طريقة 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()). إذا كانت هذه القيمة سيتم حذف المسافة المستقيمة. يجب تحديده على أنّه إحداثيات خطوط العرض وخطوط الطول:

    لضبط مَعلمة origin، استخدِم طريقة setOrigin() عند إنشاء عنصر FindAutocompletePredictionsRequest.

  • رمز المنطقة

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

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

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

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

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

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

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

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

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

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

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

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

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 ب. يمكنك تحديد صفيف مكونة من خمس قيم بحد أقصى. في حال حذفه، يتم عرض جميع الأنواع.

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