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

اختيار النظام الأساسي: Android iOS JavaScript خدمة الويب
المطوّرون في المنطقة الاقتصادية الأوروبية

مقدمة

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

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

يمكن أن يتضمّن الردّ من ميزة "الإكمال التلقائي" (الجديدة) نوعَين من عبارات البحث المقترَحة:

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

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

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

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

تتيح لك أداة "مستكشف واجهات برمجة التطبيقات" إجراء طلبات مباشرة حتى تتمكّن من التعرّف على واجهة برمجة التطبيقات وخياراتها:

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

طلب "الإكمال التلقائي (جديد)" هو طلب HTTP POST إلى عنوان URL بالشكل التالي:

https://places.googleapis.com/v1/places:autocomplete

يجب تمرير جميع المَعلمات في نص طلب JSON أو في العناوين كجزء من طلب POST. على سبيل المثال:

curl -X POST -d '{
  "input": "pizza",
  "locationBias": {
    "circle": {
      "center": {
        "latitude": 37.7937,
        "longitude": -122.3965
      },
      "radius": 500.0
    }
  }
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
https://places.googleapis.com/v1/places:autocomplete

المَعلمات المتوافقة

المعلَمة

الوصف

input*

سلسلة نصية للبحث عنها (كلمات كاملة، سلاسل فرعية، أسماء أماكن، عناوين، رموز Plus Codes).

FieldMask (عنوان HTTP)

قائمة قيم مفصولة بفاصلة تحدّد الحقول المطلوب عرضها في الاستجابة

includedPrimaryTypes

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

includePureServiceAreaBusinesses

إذا كانت القيمة "صحيح"، يتم تضمين المؤسسات التي ليس لها موقع جغرافي (المؤسسات ضمن منطقة الخدمة). الخيار التلقائي هو "خطأ".

includeQueryPredictions

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

includedRegionCodes

مصفوفة تضم ما يصل إلى 15 رمز بلد مكوّن من حرفَين لحصر النتائج بها

inputOffset

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

languageCode

اللغة المفضّلة (رمز IETF BCP-47) للنتائج القيمة التلقائية هي عنوان Accept-Language أو "en".

locationBias

تحدّد هذه المَعلمة منطقة (دائرة أو مستطيل) لتوجيه نتائج البحث نحوها، مع السماح بعرض نتائج خارج المنطقة. لا يمكن استخدامه مع locationRestriction.

locationRestriction

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

origin

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

regionCode

رمز المنطقة المستخدَم لتنسيق الردّ وتعديل الاقتراحات (مثل "uk" و"fr")

sessionToken

سلسلة من إنشاء المستخدم لتجميع طلبات "الإكمال التلقائي" في جلسة لأغراض الفوترة.
* تشير إلى حقل مطلوب.

لمحة عن الردّ

تعرض ميزة "الإكمال التلقائي (جديد)" عنصر JSON كاستجابة. في الردّ:

  • تحتوي مصفوفة suggestions على جميع الأماكن وطلبات البحث المتوقّعة بالترتيب استنادًا إلى مدى صلتها بموضوع البحث. يتم تمثيل كل مكان بحقل placePrediction ويتم تمثيل كل طلب بحث بحقل queryPrediction.
  • يحتوي الحقل placePrediction على معلومات تفصيلية حول توقّع مكان واحد، بما في ذلك رقم تعريف المكان والوصف النصي.
    • لمطابقة إدخال المستخدم بشكل أوثق كما هو موضّح في المَعلمة input، قد يتضمّن الوصف النصي لتوقّع المكان أسماء بديلة للأماكن والشوارع ومكوّنات العناوين الأخرى. قد تختلف هذه الأسماء البديلة عن الأسماء التي يتم عرضها في حقلَي displayName والعنوان في نتائج تفاصيل المكان لرقم تعريف المكان نفسه.
    • في هذا السياق، قد تكون الأسماء البديلة لبعض الأماكن بلغة مختلفة عن المتوقّع استنادًا إلى المَعلمة languageCode، وذلك حسب الأسماء التي تتطابق مع إدخال المستخدم بشكل أكبر.
  • يحتوي حقل queryPrediction على معلومات تفصيلية حول عبارة بحث متوقّعة واحدة.

يكون عنصر JSON الكامل على النحو التالي:

{
  "suggestions": [
    {
      "placePrediction": {
        "place": "places/ChIJ5YQQf1GHhYARPKG7WLIaOko",
        "placeId": "ChIJ5YQQf1GHhYARPKG7WLIaOko",
        "text": {
          "text": "Amoeba Music, Haight Street, San Francisco, CA, USA",
          "matches": [
            {
              "endOffset": 6
            }]
        },
      ...
    },
    {
      "queryPrediction": {
        "text": {
          "text": "Amoeba Music",
          "matches": [
            {
              "endOffset": 6
            }]
        },
        ...
    }
  ...]
}

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

إدخال

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

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

FieldMask

حدِّد قائمة الحقول التي تريد عرضها في الردّ من خلال إنشاء قناع حقل الردّ. مرِّر قناع حقل الاستجابة إلى الطريقة باستخدام عنوان HTTP‏ X-Goog-FieldMask.

تحديد قائمة قيم مفصولة بفاصلة لحقول الاقتراحات المطلوب عرضها على سبيل المثال، لاسترداد suggestions.placePrediction.text.text وsuggestions.queryPrediction.text.text للاقتراح.

  X-Goog-FieldMask: suggestions.placePrediction.text.text,suggestions.queryPrediction.text.text

استخدِم * لاسترداد جميع الحقول.

  X-Goog-FieldMask: *

includeFutureOpeningBusinesses

إذا كانت القيمة true، يتم عرض الأنشطة التجارية التي من المتوقع افتتاحها في المستقبل. القيمة التلقائية هي false.

includedPrimaryTypes

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

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

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

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

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

  • تم تحديد أكثر من خمسة أنواع.
  • تم تحديد أي نوع بالإضافة إلى (cities) أو (regions).
  • يتم تحديد أي أنواع غير معروفة.

includePureServiceAreaBusinesses

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

includeQueryPredictions

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

includedRegionCodes

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

    "includedRegionCodes": ["de", "fr"]

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

inputOffset

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

languageCode

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

  • يجب استخدام رموز اللغات وفقًا لمعيار IETF BCP-47 لتحديد اللغة المفضّلة.
  • في حال عدم توفير languageCode، تستخدم واجهة برمجة التطبيقات القيمة المحدّدة في العنوان Accept-Language. إذا لم يتم تحديد أي منهما، تكون القيمة التلقائية هي en. إذا حدّدت رمز لغة غير صالح، ستعرض واجهة برمجة التطبيقات الخطأ INVALID_ARGUMENT.
  • تؤثر اللغة المفضّلة بشكل بسيط في مجموعة النتائج التي تختار واجهة برمجة التطبيقات عرضها، وفي ترتيب عرضها. ويؤثر ذلك أيضًا في قدرة واجهة برمجة التطبيقات على تصحيح الأخطاء الإملائية.
  • يتم تنسيق توقعات الأماكن بشكل مختلف حسب إدخال المستخدم في كل طلب.
    • يتم أولاً اختيار العبارات المطابقة في المَعلمة input، باستخدام الأسماء التي تتوافق مع اللغة المفضّلة المحدّدة في المَعلمة languageCode عندما تكون متاحة، بينما يتم في الحالات الأخرى استخدام الأسماء التي تتطابق بشكل أفضل مع ما أدخله المستخدم.
    • يمكن تنسيق أسماء الأماكن باستخدام أسماء بديلة لمطابقة العبارات في المَعلمة input، بما في ذلك الأسماء بلغات أخرى غير اللغة التي تشير إليها المَعلمة languageCode.
    • يتم تنسيق عناوين الشوارع باللغة المحلية، في نص برمجي يمكن للمستخدم قراءته عندما يكون ذلك ممكنًا، فقط بعد اختيار العبارات المطابقة لتتطابق مع العبارات في المَعلمة input.
    • يتم عرض جميع العناوين الأخرى باللغة المفضّلة، بعد اختيار العبارات المطابقة لتتطابق مع العبارات في المَعلمة input. إذا لم يكن الاسم متاحًا باللغة المفضّلة، تستخدم واجهة برمجة التطبيقات أقرب نتيجة مطابقة.

locationBias أو locationRestriction

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

  • locationBias

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

  • locationRestriction

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

حدِّد منطقة locationBias أو locationRestriction على شكل إطار عرض مستطيل أو دائرة.

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

    على سبيل المثال:

    "locationBias": {
  "circle": {
    "center": {
      "latitude": 37.7937,
      "longitude": -122.3965
    },
    "radius": 500.0
  }
}

  • المستطيل هو إطار عرض لخطوط العرض والطول، ويتم تمثيله كنقطتين low ونقاط عالية متقابلة بشكل قطري. تُعتبر إطار العرض منطقة مغلقة، أي أنّها تشمل حدودها. يجب أن تتراوح حدود خط العرض بين -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، ولا يمكن أن يكون المربّع الممثَّل فارغًا. يؤدي ترك نافذة العرض فارغة إلى حدوث خطأ.

    على سبيل المثال، تشمل إطار العرض هذا مدينة نيويورك بالكامل:

    "locationBias": {
  "rectangle": {
    "low": {
      "latitude": 40.477398,
      "longitude": -74.259087
    },
    "high": {
      "latitude": 40.91618,
      "longitude": -73.70018
    }
  }
}

الأصل

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

"origin": {
    "latitude": 40.477398,
    "longitude": -74.259087
}

regionCode

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

تتأثر الاقتراحات أيضًا برموز المناطق. تنصح Google بضبط السمة regionCode وفقًا للإعدادات المفضّلة للمنطقة لدى المستخدم.

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

عند ضبط regionCode، قد تحذف التوقّعات داخل تلك المنطقة اسم البلد من نص الاقتراح، ما يعني أنّ structuredFormat.secondaryText قد لا يكون متوفّرًا. لذلك، تأكَّد من أنّ تطبيقك يتعامل مع الحالات التي يكون فيها secondaryText غير محدّد أو غير متوفّر.

sessionToken

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

اختيار مَعلمات لتوجيه النتائج

يمكن أن تؤثر مَعلمات "الإكمال التلقائي (جديد)" في نتائج البحث بشكل مختلف. يقدّم الجدول التالي اقتراحات لاستخدام المَعلمات استنادًا إلى النتيجة المقصودة.
المَعلمة اقتراح الاستخدام
regionCode يتم ضبطها وفقًا للإعدادات المفضّلة للمنطقة لدى المستخدم.
includedRegionCodes يتم ضبط هذا الإعداد لحصر النتائج بقائمة المناطق المحدّدة.
locationBias استخدِم هذه السمة عندما تكون النتائج المفضّلة في منطقة معيّنة أو حولها. إذا كان ذلك منطبقًا، حدِّد المنطقة على أنّها إطار العرض للخريطة التي ينظر إليها المستخدم.
locationRestriction استخدِم هذه السمة فقط عندما لا يجب عرض النتائج خارج منطقة معيّنة.
origin يُستخدَم هذا الخيار عندما يكون المطلوب هو مسافة خط مستقيم لكل توقّع.

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

حصر البحث في منطقة معيّنة باستخدام locationRestriction

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

curl -X POST -d '{
  "input": "Art museum",
  "locationRestriction": {
    "circle": {
      "center": {
        "latitude": 37.7749,
        "longitude": -122.4194
      },
      "radius": 5000.0
    }
  }
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
https://places.googleapis.com/v1/places:autocomplete

يتم تضمين جميع النتائج من داخل المناطق المحدّدة في مصفوفة suggestions:

  {
    "suggestions": [
      {
        "placePrediction": {
          "place": "places/ChIJkQQVTZqAhYARHxPt2iJkm1Q",
          "placeId": "ChIJkQQVTZqAhYARHxPt2iJkm1Q",
          "text": {
            "text": "Asian Art Museum, Larkin Street, San Francisco, CA, USA",
            "matches": [
              {
                "startOffset": 6,
                "endOffset": 16
              }
            ]
          },
          "structuredFormat": {
            "mainText": {
              "text": "Asian Art Museum",
              "matches": [
                {
                  "startOffset": 6,
                  "endOffset": 16
                }
              ]
            },
            "secondaryText": {
              "text": "Larkin Street, San Francisco, CA, USA"
            }
          },
          "types": [
            "establishment",
            "museum",
            "point_of_interest"
          ]
        }
      },
      {
        "placePrediction": {
          "place": "places/ChIJI7NivpmAhYARSuRPlbbn_2w",
          "placeId": "ChIJI7NivpmAhYARSuRPlbbn_2w",
          "text": {
            "text": "de Young Museum, Hagiwara Tea Garden Drive, San Francisco, CA, USA",
            "matches": [
              {
                "endOffset": 15
              }
            ]
          },
          "structuredFormat": {
            "mainText": {
              "text": "de Young Museum",
              "matches": [
                {
                  "endOffset": 15
                }
              ]
            },
            "secondaryText": {
              "text": "Hagiwara Tea Garden Drive, San Francisco, CA, USA"
            }
          },
          "types": [
            "establishment",
            "point_of_interest",
            "tourist_attraction",
            "museum"
          ]
        }
      },
      /.../
    ]
  }

يمكنك أيضًا استخدام locationRestriction لحصر عمليات البحث في إطار عرض مستطيل. يحدّ المثال التالي من الطلب إلى وسط مدينة سان فرانسيسكو:

  curl -X POST -d '{
    "input": "Art museum",
    "locationRestriction": {
      "rectangle": {
        "low": {
          "latitude": 37.7751,
          "longitude": -122.4219
        },
        "high": {
          "latitude": 37.7955,
          "longitude": -122.3937
        }
      }
    }
  }' \
  -H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
  https://places.googleapis.com/v1/places:autocomplete

يتم تضمين النتائج في مصفوفة suggestions:

  {
    "suggestions": [
      {
        "placePrediction": {
          "place": "places/ChIJkQQVTZqAhYARHxPt2iJkm1Q",
          "placeId": "ChIJkQQVTZqAhYARHxPt2iJkm1Q",
          "text": {
            "text": "Asian Art Museum, Larkin Street, San Francisco, CA, USA",
            "matches": [
              {
                "startOffset": 6,
                "endOffset": 16
              }
            ]
          },
          "structuredFormat": {
            "mainText": {
              "text": "Asian Art Museum",
              "matches": [
                {
                  "startOffset": 6,
                  "endOffset": 16
                }
              ]
            },
            "secondaryText": {
              "text": "Larkin Street, San Francisco, CA, USA"
            }
          },
          "types": [
            "point_of_interest",
            "museum",
            "establishment"
          ]
        }
      },
      {
        "placePrediction": {
          "place": "places/ChIJyQNK-4SAhYARO2DZaJleWRc",
          "placeId": "ChIJyQNK-4SAhYARO2DZaJleWRc",
          "text": {
            "text": "International Art Museum of America, Market Street, San Francisco, CA, USA",
            "matches": [
              {
                "startOffset": 14,
                "endOffset": 24
              }
            ]
          },
          "structuredFormat": {
            "mainText": {
              "text": "International Art Museum of America",
              "matches": [
                {
                  "startOffset": 14,
                  "endOffset": 24
                }
              ]
            },
            "secondaryText": {
              "text": "Market Street, San Francisco, CA, USA"
            }
          },
          "types": [
            "museum",
            "point_of_interest",
            "tourist_attraction",
            "art_gallery",
            "establishment"
          ]
        }
      }
    ]
  }

تفضيل البحث في منطقة معيّنة باستخدام locationBias

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

curl -X POST -d '{
  "input": "Amoeba",
  "locationBias": {
    "circle": {
      "center": {
        "latitude": 37.7749,
        "longitude": -122.4194
      },
      "radius": 5000.0
    }
  }
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
https://places.googleapis.com/v1/places:autocomplete

تحتوي النتائج الآن على العديد من العناصر الإضافية، بما في ذلك النتائج خارج نطاق 5000 متر:

{
  "suggestions": [
    {
      "placePrediction": {
        "place": "places/ChIJ5YQQf1GHhYARPKG7WLIaOko",
        "placeId": "ChIJ5YQQf1GHhYARPKG7WLIaOko",
        "text": {
          "text": "Amoeba Music, Haight Street, San Francisco, CA, USA",
          "matches": [
            {
              "endOffset": 6
            }
          ]
        },
        "structuredFormat": {
          "mainText": {
            "text": "Amoeba Music",
            "matches": [
              {
                "endOffset": 6
              }
            ]
          },
          "secondaryText": {
            "text": "Haight Street, San Francisco, CA, USA"
          }
        },
        "types": [
          "electronics_store",
          "point_of_interest",
          "store",
          "establishment",
          "home_goods_store"
        ]
      }
    },
    {
      "placePrediction": {
        "place": "places/ChIJr7uwwy58hYARBY-e7-QVwqw",
        "placeId": "ChIJr7uwwy58hYARBY-e7-QVwqw",
        "text": {
          "text": "Amoeba Music, Telegraph Avenue, Berkeley, CA, USA",
          "matches": [
            {
              "endOffset": 6
            }
          ]
        },
        "structuredFormat": {
          "mainText": {
            "text": "Amoeba Music",
            "matches": [
              {
                "endOffset": 6
              }
            ]
          },
          "secondaryText": {
            "text": "Telegraph Avenue, Berkeley, CA, USA"
          }
        },
        "types": [
          "electronics_store",
          "point_of_interest",
          "establishment",
          "home_goods_store",
          "store"
        ]
      }
    },
    ...
  ]
}

يمكنك أيضًا استخدام locationBias لتوجيه عمليات البحث إلى إطار عرض مستطيل. يحدّ المثال التالي من الطلب إلى وسط مدينة سان فرانسيسكو:

  curl -X POST -d '{
    "input": "Amoeba",
    "locationBias": {
      "rectangle": {
        "low": {
          "latitude": 37.7751,
          "longitude": -122.4219
        },
        "high": {
          "latitude": 37.7955,
          "longitude": -122.3937
        }
      }
    }
  }' \
  -H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
  https://places.googleapis.com/v1/places:autocomplete

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

  {
    "suggestions": [
      {
        "placePrediction": {
          "place": "places/ChIJ5YQQf1GHhYARPKG7WLIaOko",
          "placeId": "ChIJ5YQQf1GHhYARPKG7WLIaOko",
          "text": {
            "text": "Amoeba Music, Haight Street, San Francisco, CA, USA",
            "matches": [
              {
                "endOffset": 6
              }
            ]
          },
          "structuredFormat": {
            "mainText": {
              "text": "Amoeba Music",
              "matches": [
                {
                  "endOffset": 6
                }
              ]
            },
            "secondaryText": {
              "text": "Haight Street, San Francisco, CA, USA"
            }
          },
          "types": [
            "point_of_interest",
            "store",
            "establishment"
          ]
        }
      },
      {
        "placePrediction": {
          "place": "places/ChIJr7uwwy58hYARBY-e7-QVwqw",
          "placeId": "ChIJr7uwwy58hYARBY-e7-QVwqw",
          "text": {
            "text": "Amoeba Music, Telegraph Avenue, Berkeley, CA, USA",
            "matches": [
              {
                "endOffset": 6
              }
            ]
          },
          "structuredFormat": {
            "mainText": {
              "text": "Amoeba Music",
              "matches": [
                {
                  "endOffset": 6
                }
              ]
            },
            "secondaryText": {
              "text": "Telegraph Avenue, Berkeley, CA, USA"
            }
          },
          "types": [
            "point_of_interest",
            "store",
            "establishment"
          ]
        }
      },
      {
        "placePrediction": {
          "place": "places/ChIJRdmfADq_woARYaVhnfQSUTI",
          "placeId": "ChIJRdmfADq_woARYaVhnfQSUTI",
          "text": {
            "text": "Amoeba Music, Hollywood Boulevard, Los Angeles, CA, USA",
            "matches": [
              {
                "endOffset": 6
              }
            ]
          },
          "structuredFormat": {
            "mainText": {
              "text": "Amoeba Music",
              "matches": [
                {
                  "endOffset": 6
                }
              ]
            },
            "secondaryText": {
              "text": "Hollywood Boulevard, Los Angeles, CA, USA"
            }
          },
          "types": [
            "point_of_interest",
            "store",
            "establishment"
          ]
        }
      },
    /.../
    ]
  }

استخدام includedPrimaryTypes

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

في المثال التالي، يمكنك تحديد سلسلة input "كرة قدم" واستخدام المَعلمة includedPrimaryTypes لحصر النتائج بالمؤسسات من النوع "sporting_goods_store":

curl -X POST -d '{
  "input": "Soccer",
  "includedPrimaryTypes": ["sporting_goods_store"],
  "locationBias": {
    "circle": {
      "center": {
        "latitude": 37.7749,
        "longitude": -122.4194
      },
      "radius": 500.0
    }
  }
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
https://places.googleapis.com/v1/places:autocomplete

في حال حذف المَعلمة includedPrimaryTypes، يمكن أن تتضمّن النتائج مؤسسات من نوع لا تريده، مثل "athletic_field".

طلب توقّعات طلبات البحث

لا يتم عرض عبارات البحث المتوقّعة تلقائيًا. استخدِم مَعلمة الطلب includeQueryPredictions لإضافة عبارات البحث المقترحة إلى الاستجابة. على سبيل المثال:

curl -X POST -d '{
  "input": "Amoeba",
  "includeQueryPredictions": true,
  "locationBias": {
    "circle": {
      "center": {
        "latitude": 37.7749,
        "longitude": -122.4194
      },
      "radius": 5000.0
    }
  }
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
https://places.googleapis.com/v1/places:autocomplete

تحتوي مصفوفة suggestions الآن على عبارات البحث المقترَحة للأماكن وعبارات البحث المقترَحة لطلبات البحث، كما هو موضّح أعلاه في قسم لمحة عن الاستجابة. يتضمّن كل طلب بحث مقترَح الحقل text الذي يحتوي على سلسلة نصية مقترَحة للبحث النصي. يمكنك إجراء طلب Text Search (New) للحصول على مزيد من المعلومات عن أيّ من عبارات البحث المقترَحة التي تم عرضها.

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

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

curl -X POST -d '{
  "input": "Amoeba",
  "origin": {
    "latitude": 37.7749,
    "longitude": -122.4194
  },
  "locationRestriction": {
    "circle": {
      "center": {
        "latitude": 37.7749,
        "longitude": -122.4194
      },
      "radius": 5000.0
    }
  }
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
https://places.googleapis.com/v1/places:autocomplete

يتضمّن الردّ الآن distanceMeters:

{
  "suggestions": [
    {
      "placePrediction": {
        "place": "places/ChIJ5YQQf1GHhYARPKG7WLIaOko",
        "placeId": "ChIJ5YQQf1GHhYARPKG7WLIaOko",
        "text": {
          "text": "Amoeba Music, Haight Street, San Francisco, CA, USA",
          "matches": [
            {
              "endOffset": 6
            }
          ]
        },
        "structuredFormat": {
          "mainText": {
            "text": "Amoeba Music",
            "matches": [
              {
                "endOffset": 6
              }
            ]
          },
          "secondaryText": {
            "text": "Haight Street, San Francisco, CA, USA"
          }
        },
        "types": [
          "home_goods_store",
          "establishment",
          "point_of_interest",
          "store",
          "electronics_store"
        ],
        "distanceMeters": 3012
      }
    }
  ]
}

العثور على أنشطة تجارية ستفتح في المستقبل

يوضّح المثال التالي طلب "إكمال تلقائي (جديد)" للمؤسسات التي سيتم افتتاحها في المستقبل في نيو ميدوز، أيداهو:

curl -X POST \
-H "Content-Type: application/json" \
-H "X-Goog-Api-Key: API_KEY" \
-d '{
  "input": "Roberts Greenhouse and Tree Farm",
  "includeFutureOpeningBusinesses": true,
  "locationBias": {
    "circle": {
      "center": {"latitude": 44.9755100, "longitude": -116.2842180},
      "radius": 20
    }
  }
}' \
"https://places.googleapis.com/v1/places:autocomplete"

يتضمّن الردّ تفاصيل عن المكان، ولكنّه لا يتضمّن تاريخ الافتتاح.

{
  "suggestions": [
    {
      "placePrediction": {
        "place": "places/ChIJp1-VoKWJplQRMz8g-7Wa3Do",
        "placeId": "ChIJp1-VoKWJplQRMz8g-7Wa3Do",
        "text": {
          "text": "Roberts Greenhouse and Tree Farm, McLain Street, New Meadows, ID, USA",
          "matches": [
            {
              "endOffset": 32
            }
          ]
        },
        "structuredFormat": {
          "mainText": {
            "text": "Roberts Greenhouse and Tree Farm",
            "matches": [
              {
                "endOffset": 32
              }
            ]
          },
          "secondaryText": {
            "text": "McLain Street, New Meadows, ID, USA"
          }
        },
        "types": [
          "garden_center",
          "establishment",
          "service",
          "store",
          "point_of_interest"
        ]
      }
    }
  ]
}

المسافة غير متوفّرة في الردّ

في بعض الحالات، لا يتوفّر distanceMeters في نص الرد، حتى عند تضمين origin في الطلب. قد يحدث ذلك في السيناريوهات التالية:

  • لا يتم تضمين distanceMeters في توقّعات route.
  • لا يتم تضمين distanceMeters عندما تكون قيمته 0، وهو ما يحدث في التوقعات التي تبعد أقل من متر واحد عن الموقع الجغرافي المقدَّم origin.

ستعرض مكتبات البرامج التي تحاول قراءة الحقل distanceMeters من عنصر تم تحليله حقلاً بقيمة 0. لتجنُّب تضليل المستخدمين، لا تعرض مسافة صفرية للمستخدمين.

تحسين ميزة "الإكمال التلقائي (جديد)"

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

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

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

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

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

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

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

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

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

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

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

الإكمال التلقائي المستنِد إلى الجلسة (جديد) مع تفاصيل المكان (جديد)

استخدام ميزة "الإكمال التلقائي (جديد)" المستندة إلى الجلسة مع ميزة "تفاصيل المكان (جديد)"
بما أنّ تطبيقك يتطلّب استخدام واجهة برمجة التطبيقات Place Details (New)، مثل اسم المكان أو حالة النشاط التجاري أو ساعات العمل، يجب أن يستخدم تنفيذك لواجهة برمجة التطبيقات Autocomplete (New) رمزًا مميزًا للجلسة (برمجيًا أو مضمّنًا في تطبيقات JavaScript أو Android أو iOS المصغّرة) لكل جلسة بالإضافة إلى رموز التخزين التعريفية السارية في Places، استنادًا إلى حقول بيانات المكان التي تطلبها.1

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

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

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

ميزة "الإكمال التلقائي" (الجديدة) لكل طلب مع Geocoding API

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

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

ميزة "الإكمال التلقائي (جديد)" المستندة إلى الجلسة للتطبيقات التي تستخدم العناوين فقط

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

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

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

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

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

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

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

  1. لمعرفة التكاليف، يُرجى الاطّلاع على قوائم أسعار "منصة خرائط Google".

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

توضّح الإرشادات التالية طرق تحسين أداء ميزة "الإكمال التلقائي (جديد)":

  • أضِف القيود المفروضة على البلدان والانحياز للموقع الجغرافي واللغة المفضّلة (لعمليات التنفيذ الآلية) إلى عملية تنفيذ ميزة "الإكمال التلقائي (جديد)". لا حاجة إلى تحديد اللغة المفضّلة في التطبيقات المصغّرة لأنّها تختار اللغات المفضّلة من متصفّح المستخدم أو جهازه الجوّال.
  • إذا كانت ميزة "الإكمال التلقائي (جديد)" مصحوبة بخريطة، يمكنك تحديد الموقع الجغرافي حسب إطار العرض في الخريطة.
  • في الحالات التي لا يختار فيها المستخدم إحدى عبارات البحث المقترَحة في ميزة "الإكمال التلقائي" (الجديدة)، لأنّ أيًا من هذه العبارات لا يمثّل العنوان المطلوب، يمكنك إعادة استخدام البيانات التي أدخلها المستخدم في الأصل لمحاولة الحصول على نتائج أكثر صلة:
    • إذا كنت تتوقّع أن يُدخل المستخدم معلومات العنوان فقط، أعِد استخدام البيانات التي أدخلها المستخدم الأصلي في طلب إلى Geocoding API.
    • إذا كنت تتوقّع أن يُدخل المستخدم طلبات بحث عن مكان معيّن حسب الاسم أو العنوان، استخدِم طلب "تفاصيل المكان (جديد)". إذا كان من المتوقّع ظهور النتائج في منطقة معيّنة فقط، استخدِم الانحياز للموقع الجغرافي.
    تشمل السيناريوهات الأخرى التي يُفضَّل فيها استخدام Geocoding API ما يلي:
    • المستخدمون الذين يُدخلون عناوين فرعية، مثل عناوين وحدات أو شقق معيّنة داخل مبنى على سبيل المثال، العنوان التشيكي "Stroupežnického 3191/17, Praha" يؤدي إلى توقّع جزئي في ميزة "الإكمال التلقائي" (الجديدة).
    • المستخدمون الذين يُدخلون عناوين تحتوي على بادئات لأجزاء الطرق، مثل "‎23-30 29th St, Queens" في مدينة نيويورك أو "‎47-380 Kamehameha Hwy, Kaneohe" في جزيرة كاواي في هاواي

تحديد الموقع الجغرافي

يمكنك تحسين النتائج لمنطقة معيّنة من خلال تمرير مَعلمة location ومَعلمة radius. يؤدي ذلك إلى توجيه ميزة "الإكمال التلقائي (جديد)" إلى تفضيل عرض النتائج ضمن المنطقة المحدّدة. وقد يستمر عرض النتائج خارج المنطقة المحدّدة. يمكنك استخدام المَعلمة includedRegionCodes لفلترة النتائج وعرض الأماكن ضمن بلد محدّد فقط.

تقييد الموقع الجغرافي

يمكنك حصر النتائج بمنطقة معيّنة من خلال تمرير مَعلمة locationRestriction.

يمكنك أيضًا حصر النتائج بالمنطقة المحدّدة من خلال المَعلمة location ومَعلمة radius، وذلك من خلال إضافة المَعلمة locationRestriction. يؤدي ذلك إلى توجيه ميزة "الإكمال التلقائي (جديد)" لعرض النتائج فقط ضمن تلك المنطقة.

جرِّبها الآن.

يتيح لك "مستكشف واجهات برمجة التطبيقات" إرسال نماذج طلبات لكي تتمكّن من التعرّف على واجهة برمجة التطبيقات وخياراتها.

  1. انقر على رمز واجهة برمجة التطبيقات api على يسار الصفحة.

  2. يمكنك تعديل مَعلمات الطلب إذا أردت.

  3. انقر على الزر تنفيذ. في مربّع الحوار، اختَر الحساب الذي تريد استخدامه لتقديم الطلب.

  4. في لوحة "مستكشف واجهات برمجة التطبيقات"، انقر على رمز ملء الشاشة ملء الشاشة لتوسيع نافذة "مستكشف واجهات برمجة التطبيقات".