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

اختيار النظام الأساسي: 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 للجهاز لمنح الأولوية للنتائج. يمكنك اختياريًا استخدام قيود الموقع الجغرافي أو الميل حسب الموقع الجغرافي، ولكن ليس كلاهما، لتحديد منطقة للبحث فيها.

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

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

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

يحدِّد المثال التالي سلسلة طلب بحث هي "كرة القدم" ويستخدم المَعلمة primary 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 و الإحالات.