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

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

اختيار النظام الأساسي: Android iOS JavaScript Web Service

المطوّرون في المنطقة الاقتصادية الأوروبية

مقدمة

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

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

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

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

على سبيل المثال، يمكنك طلب الإكمال التلقائي (جديد) باستخدام سلسلة كإدخال تحتوي على جزء من إدخال المستخدم، "بيتزا صقلية"، مع حصر منطقة البحث في سان فرانسيسكو، كاليفورنيا. تحتوي الاستجابة بعد ذلك على قائمة بتوقّعات الأماكن التي تتطابق مع سلسلة البحث ومنطقة البحث، مثل المطعم المسمّى "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`	في حال صحة ذلك، يتضمّن الأنشطة التجارية التي ليس لها موقع جغرافي (المؤسسات ضمن منطقة الخدمة). القيمة التلقائية هي false.
`includeQueryPredictions`	في حال ضبطها على "صحيح"، يتم تضمين كل من توقعات الأماكن وتوقعات طلبات البحث في الرد. القيمة التلقائية هي false.
`includedRegionCodes`	مصفوفة تتضمّن ما يصل إلى 15 رمزًا للبلد مكوّنًا من حرفَين، وذلك لحصر النتائج في بلدان معيّنة.
`inputOffset`	إزاحة أحرف يونيكود المستندة إلى الصفر لموضع المؤشر ضمن سلسلة الإدخال، ما يؤثر في التوقعات. يتم ضبط هذه السمة تلقائيًا على طول الإدخال.
`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 على معلومات تفصيلية حول عبارة بحث متوقّعة واحدة.

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

يكون عنصر 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).
- يتم تحديد أي أنواع غير معروفة.
ملاحظة: لا تعمل المَعلمة includedPrimaryTypes إلا على النوع الأساسي للمكان، وليس على جميع الأنواع المرتبطة بالمكان. على الرغم من أنّ كل مكان يتضمّن نوعًا أساسيًا، لا تتوافق جميع الأنواع الأساسية مع Places API (New). تشمل الأنواع المتوافقة تلك المذكورة في الجدول أ أو الجدول ب.
includePureServiceAreaBusinesses

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

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

تضمين النتائج من قائمة المناطق المحدّدة فقط، والتي يتم تحديدها كمصفوفة من قيم نطاقات المستوى الأعلى التي يتم ترميزها حسب البلد (ccTLD) المكوّنة من حرفَين، بحد أقصى 15 قيمة. في حال عدم تضمينها، لن يتم تطبيق أي قيود على الردّ. على سبيل المثال، لحصر المناطق على ألمانيا وفرنسا:
```
    "includedRegionCodes": ["de", "fr"]
```
إذا حدّدت كلاً من locationRestriction وincludedRegionCodes، ستظهر النتائج في منطقة تقاطع الإعدادَين.

ملاحظة: إذا تلقّيت نتائج غير متوقّعة باستخدام رمز بلد، تأكَّد من أنّك تستخدم رمزًا يتضمّن البلدان والأقاليم التابعة والمناطق الخاصة ذات الأهمية الجغرافية التي تريدها. يمكنك العثور على معلومات حول الرموز في Wikipedia: List of ISO 3166 country codes أو ISO Online Browsing Platform.
inputOffset

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

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

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

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

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

اختيار المَعلمات التي تريد أن تؤثّر في النتائج

يمكن أن تؤثّر مَعلمات "الإكمال التلقائي" (الجديدة) في نتائج البحث بشكل مختلف. يقدّم الجدول التالي اقتراحات بشأن استخدام المَعلمات استنادًا إلى النتيجة المقصودة.

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

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

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

ملاحظة: تستخدم ميزة "الإكمال التلقائي (جديدة)" ميزة "تحديد الموقع الجغرافي حسب عنوان IP" تلقائيًا للتحكّم في مساحة البحث. باستخدام الانحياز لعنوان IP، تستخدم ميزة "الإكمال التلقائي (جديد)" عنوان IP الخاص بالجهاز لتوجيه النتائج. يمكنك استخدام locationRestriction أو locationBias، ولكن ليس كليهما، لتحديد منطقة للبحث.

تحدّد السمة 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

تحتوي النتائج الآن على المزيد من العناصر، بما في ذلك النتائج خارج نطاق نصف القطر البالغ 5, 000 متر:

{
  "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 الذي يحتوي على سلسلة بحث نصية مقترَحة. يمكنك إجراء طلب البحث النصي (الجديد) للحصول على مزيد من المعلومات عن أيّ من عبارات البحث المتوقّعة التي تم عرضها.

ملاحظة: لا يتم عرض عبارات البحث المقترحة عند ضبط المَعلمة includedRegionCodes.

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

في هذا المثال، أدرِج 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، أو أداة الإكمال التلقائي (جديدة) في Places SDK for Android، أو أداة الإكمال التلقائي (جديدة) في Places SDK for iOS.
التعرّف على حقول البيانات الأساسية الخاصة بميزة "الإكمال التلقائي" (جديدة) منذ البداية
حقلَي "تفضيل الموقع الجغرافي" و"حظر الموقع الجغرافي" اختياريان، ولكن يمكن أن يكون لهما تأثير كبير في أداء ميزة "الإكمال التلقائي".
استخدِم ميزة معالجة الأخطاء للتأكّد من أنّ تطبيقك يتراجع بشكل سليم في حال عرض واجهة برمجة التطبيقات رسالة خطأ.
تأكَّد من أنّ تطبيقك يتعامل مع الحالات التي لا يتم فيها تحديد أي خيار، ويوفّر للمستخدمين طريقة للمتابعة.

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

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

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

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

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

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

للحصول على مساعدة في اختيار عملية تنفيذ ميزة "الإكمال التلقائي (جديد)" التي تناسب احتياجاتك، اختَر علامة التبويب التي تتوافق مع إجابتك عن السؤال التالي.

هل يتطلّب تطبيقك أي معلومات أخرى غير العنوان وخطوط الطول والعرض الخاصة بالتوقّع المحدّد؟

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

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

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

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

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

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

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

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

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

نعم

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

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

لا

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

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

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

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

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

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

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

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

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

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

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

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

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

تحذير: إذا لم يتم توفير radius، سيتم تجاهل المَعلمة location.

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

حصر الوصول إلى الموقع الجغرافي

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

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

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

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

انقر على رمز واجهة برمجة التطبيقات api على يسار الصفحة.
يمكنك تعديل مَعلمات الطلب إذا أردت.
انقر على الزر تنفيذ. في مربّع الحوار، اختَر الحساب الذي تريد استخدامه لتقديم الطلب.
في لوحة "مستكشف واجهات برمجة التطبيقات"، انقر على رمز ملء الشاشة fullscreen لتوسيع نافذة "مستكشف واجهات برمجة التطبيقات".

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

مقدمة

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

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

لمحة عن الردّ

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

إدخال

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

FieldMask

includeFutureOpeningBusinesses

includedPrimaryTypes

includePureServiceAreaBusinesses

includeQueryPredictions

includedRegionCodes

inputOffset

languageCode

locationBias أو locationRestriction

locationBias

locationRestriction

الأصل

regionCode

sessionToken