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

تنظيم صفحاتك في مجموعات يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.
اختَر النظام الأساسي: Android iOS JavaScript خدمة الويب

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

يمكنك إضافة الإكمال التلقائي إلى تطبيقك بالطرق التالية:

إضافة أداة إكمال تلقائي

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

هناك خياران لإضافة أداة الإكمال التلقائي إلى تطبيقك:

الخيار 1: تضمين الإكمال التلقائي supportSupportFragment

لإضافة AutocompleteSupportFragment إلى تطبيقك، يُرجى اتّباع الخطوات التالية:

  1. أضِف جزءًا إلى تنسيق XML لنشاطك.
  2. أضِف مستمعًا إلى نشاطك أو جزء منه.

إضافة CompleteSupportFragment إلى نشاط

لإضافة AutocompleteSupportFragment إلى نشاط، أضِف جزءًا جديدًا إلى تنسيق XML. مثلاً:

<fragment android:id="@+id/autocomplete_fragment"
  android:layout_width="match_parent"
  android:layout_height="wrap_content"
  android:name="com.google.android.libraries.places.widget.AutocompleteSupportFragment"
  />
  • ولا يتم تطبيق حد أو خلفية تلقائيًا على الجزء. لتقديم مظهر مرئي متسق، عليك دمج الجزء داخل عنصر تنسيق آخر، مثل CardView.
  • إذا كنت تستخدم جزء الإكمال التلقائي، وتحتاج إلى إلغاء onActivityResult، يجب استدعاء super.onActivityResult، وإلا لن يعمل الجزء بشكل صحيح.

إضافة PlaceListenionListener إلى نشاط

يتعامل PlaceSelectionListener مع عرض مكان استجابةً لاختيار المستخدم. يعرض الرمز التالي إنشاء مرجع إلى الجزء وإضافة مستمع إلى AutocompleteSupportFragment:

Java


    // Initialize the AutocompleteSupportFragment.
    AutocompleteSupportFragment autocompleteFragment = (AutocompleteSupportFragment)
        getSupportFragmentManager().findFragmentById(R.id.autocomplete_fragment);

    // Specify the types of place data to return.
    autocompleteFragment.setPlaceFields(Arrays.asList(Place.Field.ID, Place.Field.NAME));

    // Set up a PlaceSelectionListener to handle the response.
    autocompleteFragment.setOnPlaceSelectedListener(new PlaceSelectionListener() {
        @Override
        public void onPlaceSelected(@NonNull Place place) {
            // TODO: Get info about the selected place.
            Log.i(TAG, "Place: " + place.getName() + ", " + place.getId());
        }


        @Override
        public void onError(@NonNull Status status) {
            // TODO: Handle the error.
            Log.i(TAG, "An error occurred: " + status);
        }
    });

      

Kotlin


    // Initialize the AutocompleteSupportFragment.
    val autocompleteFragment =
        supportFragmentManager.findFragmentById(R.id.autocomplete_fragment)
            as AutocompleteSupportFragment

    // Specify the types of place data to return.
    autocompleteFragment.setPlaceFields(listOf(Place.Field.ID, Place.Field.NAME))

    // Set up a PlaceSelectionListener to handle the response.
    autocompleteFragment.setOnPlaceSelectedListener(object : PlaceSelectionListener {
        override fun onPlaceSelected(place: Place) {
            // TODO: Get info about the selected place.
            Log.i(TAG, "Place: ${place.name}, ${place.id}")
        }

        override fun onError(status: Status) {
            // TODO: Handle the error.
            Log.i(TAG, "An error occurred: $status")
        }
    })

      

الخيار 2: استخدام هدف لبدء نشاط الإكمال التلقائي

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

لتشغيل أداة الإكمال التلقائي باستخدام intent، اتّبع الخطوات التالية:

  1. يمكنك استخدام Autocomplete.IntentBuilder لإنشاء هدف واجتياز وضع Autocomplete المطلوب. يجب أن تطلب الشريحة startActivityForResult، مع إدخال رمز الطلب الذي يحدِّد الغرض من ذلك.
  2. يمكنك إلغاء استدعاء onActivityResult لاستلام المكان المحدد.

إنشاء هدف إكمال تلقائي

يوضّح المثال التالي استخدام Autocomplete.IntentBuilder لإنشاء نيّة إطلاق أداة الإكمال التلقائي كهدف:

Java


    private static int AUTOCOMPLETE_REQUEST_CODE = 1;

    // Set the fields to specify which types of place data to
    // return after the user has made a selection.
    List<Place.Field> fields = Arrays.asList(Place.Field.ID, Place.Field.NAME);

    // Start the autocomplete intent.
    Intent intent = new Autocomplete.IntentBuilder(AutocompleteActivityMode.FULLSCREEN, fields)
        .build(this);
    startActivityForResult(intent, AUTOCOMPLETE_REQUEST_CODE);

      

Kotlin


    private val AUTOCOMPLETE_REQUEST_CODE = 1

    // Set the fields to specify which types of place data to
    // return after the user has made a selection.
    val fields = listOf(Place.Field.ID, Place.Field.NAME)

    // Start the autocomplete intent.
    val intent = Autocomplete.IntentBuilder(AutocompleteActivityMode.FULLSCREEN, fields)
        .build(this)
    startActivityForResult(intent, AUTOCOMPLETE_REQUEST_CODE)

      

وعند استخدام عنصر intent لإطلاق أداة الإكمال التلقائي، يمكنك الاختيار من بين أوضاع التراكب أو عرض ملء الشاشة. تعرض لقطات الشاشة التالية كل وضع عرض على التوالي:

عند عرض أداة الإكمال التلقائي في وضع التراكب، تظهر متراكبة على واجهة مستخدم الاتصال.
الشكل 1: أداة الإكمال التلقائي في وضع "تراكب"
عند عرض أداة الإكمال التلقائي في وضع ملء الشاشة، تملأ الشاشة بأكملها.
الشكل 2: أداة الإكمال التلقائي في وضع ملء الشاشة

إلغاء استدعاء onActivityResult

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

Java


@Override
protected void onActivityResult(int requestCode, int resultCode, @Nullable Intent data) {
    if (requestCode == AUTOCOMPLETE_REQUEST_CODE) {
        if (resultCode == RESULT_OK) {
            Place place = Autocomplete.getPlaceFromIntent(data);
            Log.i(TAG, "Place: " + place.getName() + ", " + place.getId());
        } else if (resultCode == AutocompleteActivity.RESULT_ERROR) {
            // TODO: Handle the error.
            Status status = Autocomplete.getStatusFromIntent(data);
            Log.i(TAG, status.getStatusMessage());
        } else if (resultCode == RESULT_CANCELED) {
            // The user canceled the operation.
        }
        return;
    }
    super.onActivityResult(requestCode, resultCode, data);
}

      

Kotlin


override fun onActivityResult(requestCode: Int, resultCode: Int, data: Intent?) {
    if (requestCode == AUTOCOMPLETE_REQUEST_CODE) {
        when (resultCode) {
            Activity.RESULT_OK -> {
                data?.let {
                    val place = Autocomplete.getPlaceFromIntent(data)
                    Log.i(TAG, "Place: ${place.name}, ${place.id}")
                }
            }
            AutocompleteActivity.RESULT_ERROR -> {
                // TODO: Handle the error.
                data?.let {
                    val status = Autocomplete.getStatusFromIntent(data)
                    Log.i(TAG, status.statusMessage ?: "")
                }
            }
            Activity.RESULT_CANCELED -> {
                // The user canceled the operation.
            }
        }
        return
    }
    super.onActivityResult(requestCode, resultCode, data)
}

      

الحصول على توقعات المكان آليًا

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

  • مطلوب: سلسلة query تحتوي على النص الذي كتبه المستخدم.
  • إجراء مقترَح: يشير هذا الرمز إلى AutocompleteSessionToken، الذي يجمّع طلب البحث ومرحَل بحث المستخدم في جلسة منفصلة لأغراض الفوترة. تبدأ الجلسة عندما يبدأ المستخدم في كتابة طلب بحث، وتنتهي عند اختيار مكان.
  • إجراء مقترَح: عنصر RectangularBounds يحدّد حدود خطوط الطول والعرض لحصر النتائج على المنطقة المحدّدة.
  • اختيارية: رمز أو أكثر من رموز البلدان المكوّنة من حرفين (ISO 3166-1 Alpha-2)، للإشارة إلى البلد أو البلدان التي يجب تقييد النتائج فيها
  • إجراء اختياري: TypeFilter، يمكنك استخدامه لحصر النتائج بنوع المكان المحدّد. وتتوفّر الأنواع التالية من الأماكن:

    • TypeFilter.GEOCODE – عرض نتائج الترميز الجغرافي فقط، وليس الأنشطة التجارية. استخدِم هذا الطلب لتسليط الضوء على النتائج التي قد يؤدي إلى تحديد موقع جغرافي غير محدّد.
    • TypeFilter.ADDRESS – تعرض نتائج الإكمال التلقائي فقط بعنوان دقيق. استخدِم هذا النوع إذا كنت تعرف أن المستخدم يبحث عن عنوان محدّد بالكامل.
    • TypeFilter.ESTABLISHMENT – تعرِض فقط الأنشطة التجارية.
    • TypeFilter.REGIONS – تعرض فقط الأماكن التي تطابق أحد الأنواع التالية:

      • LOCALITY
      • SUBLOCALITY
      • POSTAL_CODE
      • COUNTRY
      • ADMINISTRATIVE_AREA_LEVEL_1
      • ADMINISTRATIVE_AREA_LEVEL_2
    • TypeFilter.CITIES – تعرض النتائج التي تطابق LOCALITY أو ADMINISTRATIVE_AREA_LEVEL_3 فقط.

  • اختياري: LatLng تحدِّد الموقع الجغرافي لنقطة الطلب. عند طلب setOrigin()، تعرض الخدمة المسافة بالمتر (distanceMeters) من المصدر المحدَّد، وذلك لكل عبارة بحث مقترَحة ضمن الاستجابة.

للحصول على معلومات حول أنواع الأماكن، اطلع على دليل أنواع الأماكن.

يوضّح المثال التالي مكالمة كاملة إلى PlacesClient.findAutocompletePredictions().

Java


    // Create a new token for the autocomplete session. Pass this to FindAutocompletePredictionsRequest,
    // and once again when the user makes a selection (for example when calling fetchPlace()).
    AutocompleteSessionToken token = AutocompleteSessionToken.newInstance();

    // Create a RectangularBounds object.
    RectangularBounds bounds = RectangularBounds.newInstance(
        new LatLng(-33.880490, 151.184363),
        new LatLng(-33.858754, 151.229596));
    // Use the builder to create a FindAutocompletePredictionsRequest.
    FindAutocompletePredictionsRequest request = FindAutocompletePredictionsRequest.builder()
        // Call either setLocationBias() OR setLocationRestriction().
        .setLocationBias(bounds)
        //.setLocationRestriction(bounds)
        .setOrigin(new LatLng(-33.8749937,151.2041382))
        .setCountries("AU", "NZ")
        .setTypeFilter(TypeFilter.ADDRESS)
        .setSessionToken(token)
        .setQuery(query)
        .build();

    placesClient.findAutocompletePredictions(request).addOnSuccessListener((response) -> {
        for (AutocompletePrediction prediction : response.getAutocompletePredictions()) {
            Log.i(TAG, prediction.getPlaceId());
            Log.i(TAG, prediction.getPrimaryText(null).toString());
        }
    }).addOnFailureListener((exception) -> {
        if (exception instanceof ApiException) {
            ApiException apiException = (ApiException) exception;
            Log.e(TAG, "Place not found: " + apiException.getStatusCode());
        }
    });

      

Kotlin


    // Create a new token for the autocomplete session. Pass this to FindAutocompletePredictionsRequest,
    // and once again when the user makes a selection (for example when calling fetchPlace()).
    val token = AutocompleteSessionToken.newInstance()

    // Create a RectangularBounds object.
    val bounds = RectangularBounds.newInstance(
        LatLng(-33.880490, 151.184363),
        LatLng(-33.858754, 151.229596)
    )
    // Use the builder to create a FindAutocompletePredictionsRequest.
    val request =
        FindAutocompletePredictionsRequest.builder()
            // Call either setLocationBias() OR setLocationRestriction().
            .setLocationBias(bounds)
            //.setLocationRestriction(bounds)
            .setOrigin(LatLng(-33.8749937, 151.2041382))
            .setCountries("AU", "NZ")
            .setTypeFilter(TypeFilter.ADDRESS)
            .setSessionToken(token)
            .setQuery(query)
            .build()
    placesClient.findAutocompletePredictions(request)
        .addOnSuccessListener { response: FindAutocompletePredictionsResponse ->
            for (prediction in response.autocompletePredictions) {
                Log.i(TAG, prediction.placeId)
                Log.i(TAG, prediction.getPrimaryText(null).toString())
            }
        }.addOnFailureListener { exception: Exception? ->
            if (exception is ApiException) {
                Log.e(TAG, "Place not found: " + exception.statusCode)
            }
        }

      

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

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

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

الرموز المميزة للجلسة

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

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

مزيد من المعلومات حول الرموز المميّزة للجلسة

تقييد نتائج الإكمال التلقائي

يمكنك تقييد نتائج الإكمال التلقائي بمنطقة جغرافية معيّنة و/أو فلترة النتائج حسب نوع مكان واحد أو أكثر أو إلى ما يصل إلى خمسة بلدان. يمكنك تطبيق هذه القيود على نشاط الإكمال التلقائي AutocompleteSupportFragment وواجهات برمجة التطبيقات للإكمال التلقائي.

لحصر النتائج، عليك تنفيذ ما يلي:

  • لطلب النتائج المفضّلة داخل المنطقة المحدّدة، يمكنك الاتصال بالرقم setLocationBias() (قد يتم عرض بعض النتائج من خارج المنطقة المحدّدة).
  • لكي يتم عرض النتائج داخل المنطقة المحدّدة فقط، يمكنك الاتصال بالرقم setLocationRestriction() (لن يتم عرض سوى النتائج ضمن المنطقة المحدّدة).
  • لعرض النتائج التي تتوافق مع نوع مكان معيّن فقط، يمكنك استدعاء القيمة setTypeFilter() (على سبيل المثال، يؤدي تحديد TypeFilter.ADDRESS إلى عرض النتائج التي تحتوي على عنوان دقيق فقط).
  • لعرض النتائج فقط في خمسة بلدان محدّدة، يُرجى الاتصال بالرقم setCountries(). يجب إدخال البلدان بتنسيق رمز بلد متوافق مع ISO 3166-1 Alpha-2.

نتائج الانحياز إلى منطقة معيّنة

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

Java


    autocompleteFragment.setLocationBias(RectangularBounds.newInstance(
        new LatLng(-33.880490, 151.184363),
        new LatLng(-33.858754, 151.229596)));

      

Kotlin


    autocompleteFragment.setLocationBias(
        RectangularBounds.newInstance(
            LatLng(-33.880490, 151.184363),
            LatLng(-33.858754, 151.229596)
        )
    )

      

حصر النتائج على منطقة معيّنة

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

Java


    autocompleteFragment.setLocationRestriction(RectangularBounds.newInstance(
        new LatLng(-33.880490, 151.184363),
        new LatLng(-33.858754, 151.229596)));

      

Kotlin


    autocompleteFragment.setLocationRestriction(
        RectangularBounds.newInstance(
            LatLng(-33.880490, 151.184363),
            LatLng(-33.858754, 151.229596)
        )
    )

      

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

فلترة النتائج حسب نوع المكان

يمكنك تقييد النتائج من طلب الإكمال التلقائي بحيث تعرض فقط نوعًا معيّنًا من الأماكن. إذا لم يتم تقييد النتائج، يتم عرض جميع الأنواع. بشكل عام، يُسمح بنوع واحد فقط. باستثناء أنّه يمكنك المزج بأمان بين النوعَين GEOCODE وESTABLISHMENT، إلا أنّ له التأثير نفسه الذي تكمن في عدم تحديد أي نوع.

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

يعرض مثال الرمز التالي طلب setTypeFilter() على AutocompleteSupportFragment لضبط فلتر يعرض النتائج فقط مع عنوان دقيق.

Java


    autocompleteFragment.setTypeFilter(TypeFilter.ADDRESS);

      

Kotlin


    autocompleteFragment.setTypeFilter(TypeFilter.ADDRESS)

      

يعرض مثال الرمز التالي طلب setTypeFilter() على IntentBuilder لضبط فلتر يعرض النتائج فقط مع عنوان دقيق.

Java


    Intent intent = new Autocomplete.IntentBuilder(
        AutocompleteActivityMode.FULLSCREEN, fields)
        .setTypeFilter(TypeFilter.ADDRESS)
        .build(this);
    startActivityForResult(intent, AUTOCOMPLETE_REQUEST_CODE);

      

Kotlin


    val intent = Autocomplete.IntentBuilder(AutocompleteActivityMode.FULLSCREEN, fields)
        .setTypeFilter(TypeFilter.ADDRESS)
        .build(this)
    startActivityForResult(intent, AUTOCOMPLETE_REQUEST_CODE)

      

للحصول على معلومات حول أنواع الأماكن، اطلع على دليل أنواع الأماكن.

فلترة النتائج حسب البلد

لفلترة نتائج الإكمال التلقائي في خمسة بلدان بحدٍ أقصى، يمكنك الاتصال بالرقم setCountries() لضبط رمز البلد. ثم تمرير الفلتر إلى جزء أو غرض. يجب إدخال البلدان بتنسيق رمز بلد متوافق مع معيار ISO 3166-1 Alpha-2.

يوضّح مثال الرمز التالي طلب setCountries() على AutocompleteSupportFragment، لضبط فلتر يعرض النتائج ضمن البلدان المحدّدة فقط.

Java


    autocompleteFragment.setCountries("AU", "NZ");

      

Kotlin


    autocompleteFragment.setCountries("AU", "NZ")

      

حدود الاستخدام

لم يعد استخدامك لواجهة برمجة تطبيقات الأماكن، بما في ذلك حزمة تطوير البرامج (SDK) لأماكن Google لنظام التشغيل Android، مقصورًا على الحد الأقصى لعدد الطلبات في اليوم (QPD). ومع ذلك، ستظل حدود الاستخدام التالية سارية:

  • والحد الأقصى لمعدّل الاستخدام هو 100 طلب في الثانية (QPS). ويتم احتسابها على أنّها مجموع الطلبات من جهة العميل وجميع الطلبات من جهة الخادم لجميع التطبيقات التي تستخدم بيانات الاعتماد للمشروع نفسه.

عرض الإحالات في تطبيقك

  • إذا كان تطبيقك يستخدم خدمة الإكمال التلقائي آليًا، يجب أن تعرض واجهة المستخدم الخاصة بك 'بواسطة Google' إحالة، أو تظهر ضمن خريطة تحمل علامة Google.
  • إذا كان تطبيقك يستخدم أداة الإكمال التلقائي، ليس عليك اتخاذ أي إجراء إضافي (يتم عرض الإحالة المطلوبة تلقائيًا).
  • عند استرداد معلومات إضافية عن المكان وعرضها بعد الحصول على مكان من خلال رقم التعريف، يجب عليك أيضًا عرض إحالات الجهات الخارجية.

لمزيد من التفاصيل، اطّلِع على مستندات الإحالات.

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

يصف هذا القسم أفضل الممارسات التي تساعدك في الاستفادة إلى أقصى حد من خدمة الإكمال التلقائي للأماكن.

إليك بعض الإرشادات العامة:

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

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

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

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

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

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

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

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

نعم، بحاجة إلى مزيد من التفاصيل

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

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

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

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

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

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

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

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

نعم

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

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

لا

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

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

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

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

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

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

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


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

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

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

  • يمكنك إضافة قيود على البلد وانحياز الموقع الجغرافي ولغة (لعمليات التنفيذ الآلية) في تنفيذ الإكمال التلقائي للأماكن. لست بحاجة إلى اختيار اللغة المفضّلة باستخدام الأدوات، لأنّها تختار الإعدادات المفضّلة للغة من متصفّح المستخدم أو جهازه الجوّال.
  • إذا كانت ميزة "الإكمال التلقائي" للأماكن مصحوبة بخريطة، يمكنك الانحياز للموقع الجغرافي حسب إطار عرض الخريطة.
  • وفي الحالات التي لا يختار فيها المستخدم أحد عبارات البحث المقترَحة من خلال ميزة"الإكمال التلقائي"، بشكل عام لأنّ أيًا من عبارات البحث المقترَحة لا تمثّل عنوان النتيجة المطلوب، يمكنك إعادة استخدام الإدخال الأصلي للمستخدم لمحاولة الحصول على نتائج أكثر صلة: من السيناريوهات الأخرى التي يفضّل فيها الرجوع إلى واجهة برمجة تطبيقات الترميز الجغرافي:
    • المستخدمون الذين يُدخِلون عناوين فرعية في بلدان أخرى غير أستراليا أو نيوزيلندا أو كندا. على سبيل المثال، لا يمكن استخدام ميزة "الإكمال التلقائي" في عنوان الولايات المتحدة "123 Bowdoin St #456, Texas MA, USA&quot. (لا تسمح ميزة الإكمال التلقائي باستخدام العناوين الفرعية إلا في أستراليا ونيوزيلندا وكندا. تشتمل تنسيقات العناوين المعتمَدة في هذه البلدان الثلاثة على "9/321 Pitt Street, London, New Southville, Australia" أو "14/19 جادة لوس أنجلوس أو براونز باي أو أوكلاند أو نيوزيلندا&quot أو &&;;145-112 Renfrew Dr, Markham, Ontario, Canada".)
    • المستخدمون الذين يُدخِلون عناوين تحتوي على بادئات مقطع الطريق، مثل "23-30 29 St. Queens" في مدينة نيويورك أو: &77-380 Kamehameha Hwy, Kaneohe"على جزيرة كاواي في هاواي'i

تحديد المشاكل وحلّها

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

يتم عرض الأخطاء التي تحدث أثناء استخدام عناصر التحكّم في ميزة"الإكمال التلقائي"في معاودة الاتصال في onActivityResult(). يمكنك الاتصال بالرقم Autocomplete.getStatus() للحصول على رسالة الحالة التي تظهر لك.