هذا المنتج أو هذه الميزة في حالة "قديم". لمزيد من المعلومات عن الحالة "قديمة"، يُرجى الاطّلاع على المنتجات والميزات القديمة. لنقل البيانات إلى Places API (الإصدار الجديد)، يُرجى الاطّلاع على دليل نقل البيانات.

ميزة "الإكمال التلقائي للأماكن" (الإصدار القديم)

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

ملاحظة: مكتبات من جهة الخادم ومن جهة العميل

تتوفّر Places API أيضًا مع برنامج Java، وبرنامج Python، وبرنامج Go، وبرنامج Node.js لخدمات "خرائط Google". إنّ Places API ومكتبات البرامج مخصّصة للاستخدام في تطبيقات الخادم.

إذا كنت بصدد إنشاء تطبيق من جهة العميل، يمكنك الاطّلاع على حزمة تطوير البرامج (SDK) الجديدة للأماكن في Android وحزمة تطوير البرامج (SDK) الجديدة للأماكن في iOS ومكتبة الأماكن في Maps JavaScript API.

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

طلبات الإكمال التلقائي للأماكن (الإصدار القديم)

يُعدّ الإكمال التلقائي للأماكن (الإصدار القديم) جزءًا من Places API، وتتشارك مفتاح واجهة برمجة التطبيقات والحصص مع Places API.

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

يجب تنسيق رموز Plus Codes بشكل صحيح. وهذا يعني أنّه يجب ترميز علامة الجمع في عنوان URL إلى %2B، ويجب ترميز المسافات إلى %20.

الرمز العالمي هو رمز منطقة يتألف من أربعة أحرف، ورمز محلي يتألف من ستة أحرف أو أكثر. على سبيل المثال، رمز URL-escape العالمي 849VCWC8+R9 هو 849VCWC8%2BR9.
الرمز المركّب هو رمز محلي مكوّن من ستة أحرف (أو أكثر) مع موقع جغرافي محدّد. على سبيل المثال، الرمز المركّب الذي تمت إزالة الترميز من عنوان URL الخاص به CWC8+R9 Mountain View, CA, USA هو CWC8%2BR9%20Mountain%20View%20CA%20USA.

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

طلب الإكمال التلقائي للأماكن (الإصدار القديم) هو عنوان URL يستخدم HTTP على النحو التالي:

https://maps.googleapis.com/maps/api/place/autocomplete/output?parameters

حيث يمكن أن تكون output إحدى القيمتين التاليتين:

‫json (موصى به) يشير إلى الإخراج بتنسيق JavaScript Object Notation (JSON)
يشير xml إلى الناتج بتنسيق XML

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

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

إدخال

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

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

المكوّنات

مجموعة من الأماكن التي تريد حصر نتائجك بها يمكنك استخدام المكوّنات للتصفية حسب ما يصل إلى 5 بلدان. يجب إدخال البلدان كرمز بلد مكوّن من حرفَين ومتوافق مع معيار ISO 3166-1 Alpha-2. على سبيل المثال: سيؤدي استخدام components=country:fr إلى حصر نتائجك بالأماكن الواقعة ضمن فرنسا. يجب تمرير البلدان المتعدّدة كفلاتر country:XX متعدّدة، مع استخدام الرمز | كفاصل. على سبيل المثال: components=country:us|country:pr|country:vi|country:gu|country:mp سيؤدي إلى حصر نتائجك بالأماكن الواقعة ضمن الولايات المتحدة ومناطقها المنظَّمة غير المدمجة.

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

اللغة التي سيتم عرض النتائج بها
- اطّلِع على قائمة اللغات المتاحة. تُحدّث Google غالبًا اللغات المتوافقة، لذا قد لا تكون هذه القائمة شاملة.
- في حال عدم توفير language، تحاول واجهة برمجة التطبيقات استخدام اللغة المفضّلة كما هو محدّد في العنوان Accept-Language.
- تبذل واجهة برمجة التطبيقات قصارى جهدها لتوفير عنوان شارع يمكن قراءته من قِبل المستخدمين والسكان المحليين. لتحقيق هذا الهدف، تعرض الخدمة عناوين الشوارع باللغة المحلية، مع ترجمتها إلى نص يمكن للمستخدم قراءته إذا لزم الأمر، مع مراعاة اللغة المفضّلة. ويتم عرض جميع العناوين الأخرى باللغة المفضّلة. يتم عرض جميع مكونات العنوان باللغة نفسها، والتي يتم اختيارها من المكون الأول.
- إذا لم يتوفّر اسم باللغة المفضّلة، تستخدم واجهة برمجة التطبيقات أقرب نتيجة مطابِقة.
- للغة المفضّلة تأثير بسيط على مجموعة النتائج التي تختار واجهة برمجة التطبيقات عرضها، وعلى ترتيب عرضها. يفسّر برنامج الترميز الجغرافي الاختصارات بشكل مختلف حسب اللغة، مثل اختصارات أنواع الشوارع أو المرادفات التي قد تكون صالحة في لغة ما ولكن ليس في لغة أخرى. على سبيل المثال، utca وtér هما كلمتان مترادفتان لكلمة "شارع" باللغة الهنغارية.
الموقع

النقطة التي سيتم استرداد معلومات المكان حولها. يجب تحديدها على أنّها latitude,longitude. يجب أيضًا توفير المَعلمة radius عند تحديد موقع جغرافي. إذا لم يتم تقديم radius، سيتم تجاهل المَعلمة location.

عند استخدام Text Search API، يمكن تجاهل المَعلمة `location` إذا كان طلب البحث `query` يتضمّن موقعًا جغرافيًا صريحًا، مثل `سوق في برشلونة`.
locationbias

تفضيل النتائج في منطقة محدّدة، وذلك من خلال تحديد إما نصف قطر بالإضافة إلى خط العرض/خط الطول، أو زوجَين من خط العرض/خط الطول يمثّلان نقطتَي مستطيل في حال عدم تحديد هذه المَعلمة، تستخدم واجهة برمجة التطبيقات ميزة "تفضيل عنوان IP" تلقائيًا.
- تحيز عنوان IP: يوجّه واجهة برمجة التطبيقات إلى استخدام التحيز في عنوان IP. مرِّر السلسلة ipbias (لا يتضمّن هذا الخيار أي مَعلمات إضافية).
- دائري: سلسلة تحدّد نصف القطر بالأمتار، بالإضافة إلى خطوط الطول والعرض بالدرجات العشرية استخدِم التنسيق التالي: circle:radius@lat,lng.
- مستطيل: سلسلة تحدّد زوجَين من خطوط الطول والعرض بالدرجات العشرية، يمثّلان النقطتَين الجنوبية الغربية والشمالية الشرقية من المستطيل. استخدِم التنسيق التالي:rectangle:south,west|north,east. يُرجى العِلم بأنّه يتم تقريب قيم الشرق/الغرب إلى النطاق -180، 180، ويتم تثبيت قيم الشمال/الجنوب في النطاق -90، 90.
locationrestriction

لحصر النتائج بمنطقة محدّدة، عليك تحديد إما نصف قطر بالإضافة إلى خطوط الطول والعرض، أو زوجَين من خطوط الطول والعرض يمثّلان نقاط المستطيل.
- دائري: سلسلة تحدّد نصف القطر بالأمتار، بالإضافة إلى خطوط الطول والعرض بالدرجات العشرية استخدِم التنسيق التالي: circle:radius@lat,lng.
- مستطيل: سلسلة تحدّد زوجَين من خطوط الطول والعرض بالدرجات العشرية، يمثّلان النقطتَين الجنوبية الغربية والشمالية الشرقية من المستطيل. استخدِم التنسيق التالي:rectangle:south,west|north,east. يُرجى العِلم بأنّه يتم تقريب قيم الشرق/الغرب إلى النطاق -180، 180، ويتم تثبيت قيم الشمال/الجنوب في النطاق -90، 90.
offset

موضع آخر حرف تستخدمه الخدمة لمطابقة التوقعات في عبارة الإدخال على سبيل المثال، إذا كان الإدخال هو Google وكان الإزاحة 3، ستطابق الخدمة Goo. تتم مطابقة السلسلة المحدّدة بواسطة الإزاحة مع الكلمة الأولى فقط في عبارة البحث. على سبيل المثال، إذا كانت عبارة الإدخال هي Google abc وكان الإزاحة 3، ستحاول الخدمة إجراء مطابقة مع Goo abc. في حال عدم توفير إزاحة، ستستخدم الخدمة المدة بأكملها. يجب بشكل عام ضبط الإزاحة على موضع علامة الإقحام الخاصة بالنص.
الأصل

تمثّل هذه السمة نقطة البداية التي سيتم منها احتساب المسافة المستقيمة إلى الوجهة (يتم عرضها كـ distance_meters). وفي حال حذف هذه القيمة، لن يتم عرض المسافة المستقيمة. يجب تحديدها على النحو التالي: latitude,longitude.
نطاق جغرافي

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

سيتم تلقائيًا حصر نصف القطر بقيمة قصوى استنادًا إلى نوع البحث والمَعلمات الأخرى.
- الإكمال التلقائي: 50,000 متر
- البحث في الجوار:
  - مع keyword أو name: 50,000 متر
  - بدون keyword أو name
    - ما يصل إلى 50,000 متر، يتم تعديلها ديناميكيًا استنادًا إلى كثافة المنطقة، بغض النظر عن المَعلمة rankby.
    - عند استخدام rankby=distance، لن يتم قبول مَعلمة نصف القطر، وسيؤدي ذلك إلى ظهور INVALID_REQUEST.
- ميزة "الإكمال التلقائي للبحث": 50,000 متر
- البحث النصي: 50,000 متر
المنطقة

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

سلسلة عشوائية تحدّد جلسة الإكمال التلقائي لأغراض الفوترة.

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

ننصحك باتّباع الإرشادات التالية:
- استخدِم رموز الجلسات لجميع جلسات الإكمال التلقائي.
- إنشاء رمز مميز جديد لكل جلسة ننصح باستخدام الإصدار 4 من المعرّف الفريد العالمي (UUID).
- تأكَّد من أنّ مفاتيح واجهة برمجة التطبيقات المستخدَمة في جميع طلبات الإكمال التلقائي للأماكن وطلبات تفاصيل المكان ضمن الجلسة تنتمي إلى مشروع Cloud Console نفسه.
- احرص على تمرير الرمز المميز للجلسة فريد لكل جلسة جديدة. سيؤدي استخدام الرمز المميز نفسه لأكثر من جلسة واحدة إلى تحصيل رسوم كل طلب على حدة.
strictbounds

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

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

يمكن أن يكون للمكان نوع أساسي واحد فقط من الأنواع المدرَجة في الجدول 1 أو الجدول 2. على سبيل المثال، قد يتم عرض فندق يقدّم الطعام فقط باستخدام types=lodging وليس باستخدام types=restaurant.

بالنسبة إلى قيمة المَعلمة types، يمكنك تحديد أحد الخيارَين التاليَين:
- ما يصل إلى خمس قيم من الجدول 1 أو الجدول 2 بالنسبة إلى القيم المتعددة، افصل بين كل قيمة باستخدام | (شريط عمودي). على سبيل المثال:
  
  types=book_store|cafe
- أي فلتر واحد متوافق في الجدول 3 لا يمكنك المزج بين مجموعات الأنواع.
ملاحظة: على الرغم من أنّ geocode وestablishment يشكّلان جزءًا من الجدول 2، لا يمكن دمجهما مع أي نوع آخر في الجداول 1 أو 2 أو 3 في فلاتر طلبات الإكمال التلقائي للأماكن.

سيتم رفض الطلب مع ظهور الخطأ INVALID_REQUEST في الحالات التالية:
- تم تحديد أكثر من خمسة أنواع.
- تتوفّر أي أنواع غير معروفة.
- يتم دمج أي أنواع من الجدول 1 أو الجدول 2 مع أي من الفلاتر في الجدول 3.
ملاحظة: لا تعمل المَعلمة types إلا على النوع الأساسي للمكان، وليس على جميع الأنواع المرتبطة بالمكان. على الرغم من أنّ لكل مكان نوعًا أساسيًا، لا تتوافق بعض الأنواع الأساسية مع Places API (الجديدة). تشمل الأنواع المتوافقة تلك المُدرَجة في الجدول 1 أو الجدول 2.

أمثلة على خدمة "الإكمال التلقائي للأماكن" (الإصدار القديم)

طلب الحصول على مؤسسات تتضمّن السلسلة "Amoeba" ضمن منطقة تتمركز في سان فرانسيسكو، كاليفورنيا:

عنوان URL

https://maps.googleapis.com/maps/api/place/autocomplete/json
      ?input=amoeba
      &types=establishment
      &location=37.76999%2C-122.44696
      &radius=500
      &key=YOUR_API_KEY

curl

curl -L -X GET 'https://maps.googleapis.com/maps/api/place/autocomplete/json?input=amoeba&types=establishment&location=37.76999%2C-122.44696&radius=500&key=YOUR_API_KEY'

الطلب نفسه، ولكن مع حصر النتائج في نطاق 500 متر من شارع Ashbury وشارع Haight في سان فرانسيسكو:

عنوان URL

https://maps.googleapis.com/maps/api/place/autocomplete/json
      ?input=amoeba
      &types=establishment
      &location=37.76999%2C-122.44696&radius=500
      &strictbounds=true
      &key=YOUR_API_KEY

curl

curl -L -X GET 'https://maps.googleapis.com/maps/api/place/autocomplete/json?input=amoeba&types=establishment&location=37.76999%2C-122.44696&radius=500&strictbounds=true&key=YOUR_API_KEY'

طلب البحث عن عناوين تتضمّن "Vict" مع عرض النتائج بالفرنسية:

عنوان URL

https://maps.googleapis.com/maps/api/place/autocomplete/json
      ?input=Vict
      &types=geocode
      &language=fr
      &key=YOUR_API_KEY

curl

curl -L -X GET 'https://maps.googleapis.com/maps/api/place/autocomplete/json?input=Vict&types=geocode&language=fr&key=YOUR_API_KEY'

طلب البحث عن مدن تتضمّن "فيكت" مع عرض النتائج باللغة البرتغالية البرازيلية:

عنوان URL

https://maps.googleapis.com/maps/api/place/autocomplete/json
      ?input=Vict
      &types=(cities)
      &language=pt_BR&key=YOUR_API_KEY

curl

curl -L -X GET 'https://maps.googleapis.com/maps/api/place/autocomplete/json?input=Vict&types=(cities)&language=pt_BR&key=YOUR_API_KEY'

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

استجابة خدمة "الإكمال التلقائي للأماكن" (الإصدار القديم)

يتم عرض استجابات الإكمال التلقائي للأماكن (الإصدار القديم) بالتنسيق المحدّد بواسطة العلامة output ضمن مسار عنوان URL للطلب. تشير النتائج أدناه إلى ما قد يتم عرضه عند إجراء طلب بحث يتضمّن المَعلمات التالية:

عنوان URL

https://maps.googleapis.com/maps/api/place/autocomplete/json
      ?input=Paris
      &types=geocode
      &key=YOUR_API_KEY

curl

curl -L -X GET 'https://maps.googleapis.com/maps/api/place/autocomplete/json?input=Paris&types=geocode&key=YOUR_API_KEY'

JSON

{
  "predictions":
    [
      {
        "description": "Paris, France",
        "matched_substrings": [{ "length": 5, "offset": 0 }],
        "place_id": "ChIJD7fiBh9u5kcRYJSMaMOCCwQ",
        "reference": "ChIJD7fiBh9u5kcRYJSMaMOCCwQ",
        "structured_formatting":
          {
            "main_text": "Paris",
            "main_text_matched_substrings": [{ "length": 5, "offset": 0 }],
            "secondary_text": "France",
          },
        "terms":
          [
            { "offset": 0, "value": "Paris" },
            { "offset": 7, "value": "France" },
          ],
        "types": ["locality", "political", "geocode"],
      },
      {
        "description": "Paris, TX, USA",
        "matched_substrings": [{ "length": 5, "offset": 0 }],
        "place_id": "ChIJmysnFgZYSoYRSfPTL2YJuck",
        "reference": "ChIJmysnFgZYSoYRSfPTL2YJuck",
        "structured_formatting":
          {
            "main_text": "Paris",
            "main_text_matched_substrings": [{ "length": 5, "offset": 0 }],
            "secondary_text": "TX, USA",
          },
        "terms":
          [
            { "offset": 0, "value": "Paris" },
            { "offset": 7, "value": "TX" },
            { "offset": 11, "value": "USA" },
          ],
        "types": ["locality", "political", "geocode"],
      },
      {
        "description": "Paris, TN, USA",
        "matched_substrings": [{ "length": 5, "offset": 0 }],
        "place_id": "ChIJ4zHP-Sije4gRBDEsVxunOWg",
        "reference": "ChIJ4zHP-Sije4gRBDEsVxunOWg",
        "structured_formatting":
          {
            "main_text": "Paris",
            "main_text_matched_substrings": [{ "length": 5, "offset": 0 }],
            "secondary_text": "TN, USA",
          },
        "terms":
          [
            { "offset": 0, "value": "Paris" },
            { "offset": 7, "value": "TN" },
            { "offset": 11, "value": "USA" },
          ],
        "types": ["locality", "political", "geocode"],
      },
      {
        "description": "Paris, Brant, ON, Canada",
        "matched_substrings": [{ "length": 5, "offset": 0 }],
        "place_id": "ChIJsamfQbVtLIgR-X18G75Hyi0",
        "reference": "ChIJsamfQbVtLIgR-X18G75Hyi0",
        "structured_formatting":
          {
            "main_text": "Paris",
            "main_text_matched_substrings": [{ "length": 5, "offset": 0 }],
            "secondary_text": "Brant, ON, Canada",
          },
        "terms":
          [
            { "offset": 0, "value": "Paris" },
            { "offset": 7, "value": "Brant" },
            { "offset": 14, "value": "ON" },
            { "offset": 18, "value": "Canada" },
          ],
        "types": ["neighborhood", "political", "geocode"],
      },
      {
        "description": "Paris, KY, USA",
        "matched_substrings": [{ "length": 5, "offset": 0 }],
        "place_id": "ChIJsU7_xMfKQ4gReI89RJn0-RQ",
        "reference": "ChIJsU7_xMfKQ4gReI89RJn0-RQ",
        "structured_formatting":
          {
            "main_text": "Paris",
            "main_text_matched_substrings": [{ "length": 5, "offset": 0 }],
            "secondary_text": "KY, USA",
          },
        "terms":
          [
            { "offset": 0, "value": "Paris" },
            { "offset": 7, "value": "KY" },
            { "offset": 11, "value": "USA" },
          ],
        "types": ["locality", "political", "geocode"],
      },
    ],
  "status": "OK",
}

XML

    
<?xml version="1.0" encoding="UTF-8"?>
<AutocompletionResponse>
 <status>OK</status>
 <prediction>
  <description>Paris, France</description>
  <type>locality</type>
  <type>political</type>
  <type>geocode</type>
  <reference>ChIJD7fiBh9u5kcRYJSMaMOCCwQ</reference>
  <term>
   <value>Paris</value>
   <offset>0</offset>
  </term>
  <term>
   <value>France</value>
   <offset>7</offset>
  </term>
  <matched_substring>
   <offset>0</offset>
   <length>5</length>
  </matched_substring>
  <place_id>ChIJD7fiBh9u5kcRYJSMaMOCCwQ</place_id>
  <structured_formatting>
   <description>Paris</description>
   <subdescription>France</subdescription>
   <description_matched_substring>
    <offset>0</offset>
    <length>5</length>
   </description_matched_substring>
  </structured_formatting>
 </prediction>
 <prediction>
  <description>Paris, TX, USA</description>
  <type>locality</type>
  <type>political</type>
  <type>geocode</type>
  <reference>ChIJmysnFgZYSoYRSfPTL2YJuck</reference>
  <term>
   <value>Paris</value>
   <offset>0</offset>
  </term>
  <term>
   <value>TX</value>
   <offset>7</offset>
  </term>
  <term>
   <value>USA</value>
   <offset>11</offset>
  </term>
  <matched_substring>
   <offset>0</offset>
   <length>5</length>
  </matched_substring>
  <place_id>ChIJmysnFgZYSoYRSfPTL2YJuck</place_id>
  <structured_formatting>
   <description>Paris</description>
   <subdescription>TX, USA</subdescription>
   <description_matched_substring>
    <offset>0</offset>
    <length>5</length>
   </description_matched_substring>
  </structured_formatting>
 </prediction>
 <prediction>
  <description>Paris, TN, USA</description>
  <type>locality</type>
  <type>political</type>
  <type>geocode</type>
  <reference>ChIJ4zHP-Sije4gRBDEsVxunOWg</reference>
  <term>
   <value>Paris</value>
   <offset>0</offset>
  </term>
  <term>
   <value>TN</value>
   <offset>7</offset>
  </term>
  <term>
   <value>USA</value>
   <offset>11</offset>
  </term>
  <matched_substring>
   <offset>0</offset>
   <length>5</length>
  </matched_substring>
  <place_id>ChIJ4zHP-Sije4gRBDEsVxunOWg</place_id>
  <structured_formatting>
   <description>Paris</description>
   <subdescription>TN, USA</subdescription>
   <description_matched_substring>
    <offset>0</offset>
    <length>5</length>
   </description_matched_substring>
  </structured_formatting>
 </prediction>
 <prediction>
  <description>Paris, Brant, ON, Canada</description>
  <type>neighborhood</type>
  <type>political</type>
  <type>geocode</type>
  <reference>ChIJsamfQbVtLIgR-X18G75Hyi0</reference>
  <term>
   <value>Paris</value>
   <offset>0</offset>
  </term>
  <term>
   <value>Brant</value>
   <offset>7</offset>
  </term>
  <term>
   <value>ON</value>
   <offset>14</offset>
  </term>
  <term>
   <value>Canada</value>
   <offset>18</offset>
  </term>
  <matched_substring>
   <offset>0</offset>
   <length>5</length>
  </matched_substring>
  <place_id>ChIJsamfQbVtLIgR-X18G75Hyi0</place_id>
  <structured_formatting>
   <description>Paris</description>
   <subdescription>Brant, ON, Canada</subdescription>
   <description_matched_substring>
    <offset>0</offset>
    <length>5</length>
   </description_matched_substring>
  </structured_formatting>
 </prediction>
 <prediction>
  <description>Paris, KY, USA</description>
  <type>locality</type>
  <type>political</type>
  <type>geocode</type>
  <reference>ChIJsU7_xMfKQ4gReI89RJn0-RQ</reference>
  <term>
   <value>Paris</value>
   <offset>0</offset>
  </term>
  <term>
   <value>KY</value>
   <offset>7</offset>
  </term>
  <term>
   <value>USA</value>
   <offset>11</offset>
  </term>
  <matched_substring>
   <offset>0</offset>
   <length>5</length>
  </matched_substring>
  <place_id>ChIJsU7_xMfKQ4gReI89RJn0-RQ</place_id>
  <structured_formatting>
   <description>Paris</description>
   <subdescription>KY, USA</subdescription>
   <description_matched_substring>
    <offset>0</offset>
    <length>5</length>
   </description_matched_substring>
  </structured_formatting>
 </prediction>
</AutocompletionResponse>

PlacesAutocompleteResponse

الحقل	مطلوب	النوع	الوصف
`predictions`	مطلوب	Array<PlaceAutocompletePrediction>	يحتوي على مصفوفة من عبارات البحث المقترَحة. راجِع PlaceAutocompletePrediction للحصول على مزيد من المعلومات.
`status`	مطلوب	PlacesAutocompleteStatus	يحتوي على حالة الطلب، وقد يتضمّن معلومات تصحيح الأخطاء لمساعدتك في معرفة سبب تعذُّر تلبية الطلب. لمزيد من المعلومات، يُرجى الاطّلاع على PlacesAutocompleteStatus.
`error_message`	اختياري	سلسلة	عندما تعرض الخدمة رمز حالة غير `OK<`، قد يكون هناك حقل `error_message` إضافي ضمن عنصر الاستجابة. يحتوي هذا الحقل على معلومات أكثر تفصيلاً حول أسباب رمز الحالة المحدّد. لا يتم عرض هذا الحقل دائمًا، وقد يتغيّر محتواه.
`info_messages`	اختياري	Array<string>	عندما تعرض الخدمة معلومات إضافية حول مواصفات الطلب، قد يكون هناك حقل `info_messages` إضافي ضمن عنصر الردّ. لا يتم عرض هذا الحقل إلا للطلبات الناجحة. وقد لا يتم عرضها دائمًا، كما أنّ محتواها قابل للتغيير.

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

تتألف استجابة XML من عنصر <AutocompletionResponse> واحد مع نوعَين من العناصر الثانوية:

يحتوي عنصر <status> واحد على بيانات وصفية حول الطلب. يمكنك الاطّلاع على رموز الحالة أدناه.
عنصر <prediction> واحد أو أكثر، يحتوي كل منها على معلومات حول مكان واحد. راجِع نتائج الإكمال التلقائي للأماكن (الإصدار القديم) للحصول على معلومات حول هذه النتائج. تعرض Places API ما يصل إلى 5 نتائج.

ننصحك باستخدام json كعلامة الإخراج المفضّلة ما لم يتطلّب تطبيقك استخدام xml لسبب ما. تتطلّب معالجة بنى XML بعض الحذر، وذلك لضمان الرجوع إلى العُقد والعناصر المناسبة. يمكنك الاطّلاع على معالجة ملفات XML باستخدام XPath للحصول على مساعدة بشأن معالجة ملفات XML.

قد لا يتوفّر مكوّن العنوان street_number في ردود تفاصيل المكان (قديم) لمعرّفات الأماكن في بعض التوقّعات الخاصة بالإكمال التلقائي. يحدث ذلك عادةً عندما يتعذّر إدخال عنوان مكان. في هذه الحالات، ستتضمّن مصفوفة types الخاصة بالتوقّع القيمة "route". بالنسبة إلى عبارات البحث المقترَحة التي تتضمّن رقمًا في الوصف (تتم مطابقة طلب البحث الذي تم إدخاله)، يتضمّن الردّ من تفاصيل المكان (الإصدار القديم) الخاص برقم تعريف المكان رقم الشارع فقط إذا كانت مصفوفة types الخاصة بعبارة البحث المقترَحة تتضمّن واحدًا على الأقل مما يلي:

street_address
مبنى
مؤسسة

PlacesAutocompleteStatus

رموز الحالة التي تعرضها الخدمة

OK للإشارة إلى أنّ طلب البيانات من واجهة برمجة التطبيقات تمّ بنجاح.
‫ZERO_RESULTS، ما يشير إلى أنّ البحث تم بنجاح ولكن لم يتم عرض أي نتائج. قد يحدث ذلك إذا تم تمرير حدود إلى عملية البحث في موقع جغرافي بعيد.
‫INVALID_REQUEST، ما يشير إلى أنّ طلب البيانات من واجهة برمجة التطبيقات غير صالح، ويعود ذلك عادةً إلى عدم توفّر المَعلمة input.
OVER_QUERY_LIMIT التي تشير إلى أي مما يلي:
- لقد تجاوزت الحدّ الأقصى لعدد الطلبات في الثانية.
- لم يتم تفعيل الفوترة في حسابك.
- تم تجاوز رصيد بقيمة 200 دولار أمريكي شهريًا أو الحد الأقصى للاستخدام الذي فرضته على نفسك.
- لم تعُد طريقة الدفع المقدَّمة صالحة (على سبيل المثال، انتهت صلاحية بطاقة ائتمان).
لمزيد من المعلومات حول كيفية حلّ هذا الخطأ، يمكنك الاطّلاع على الأسئلة الشائعة حول "خرائط Google".
REQUEST_DENIED يشير إلى أنّه تم رفض طلبك، ويكون السبب عادةً أحد ما يلي:
- لا يتضمّن الطلب مفتاح واجهة برمجة التطبيقات.
- المَعلمة key غير صالحة.
‫UNKNOWN_ERROR للإشارة إلى حدوث خطأ غير معروف.

عندما تعرض خدمة "أماكن Google" نتائج JSON من عملية بحث، فإنّها تضعها ضمن مصفوفة predictions. حتى إذا لم تعرض الخدمة أي نتائج (مثلما يحدث إذا كان location بعيدًا)، ستعرض مصفوفة predictions فارغة. تتألف ردود XML من صفر أو أكثر من عناصر <prediction>.

PlaceAutocompletePrediction

الحقل	مطلوب	النوع	الوصف
`description`	مطلوب	سلسلة	تحتوي على الاسم الذي يمكن للمستخدم قراءته للنتيجة التي تم إرجاعها. بالنسبة إلى نتائج `establishment`، يكون هذا الاسم عادةً هو اسم النشاط التجاري. يجب قراءة هذا المحتوى كما هو، ويُرجى عدم تحليل العنوان المنسّق آليًا.
`matched_substrings`	مطلوب	Array<PlaceAutocompleteMatchedSubstring>	قائمة بالسلاسل الفرعية التي تصف موضع العبارة المُدخَلة في نص نتيجة التوقّع، وذلك كي يمكن تمييز العبارة إذا تم اختيارها. لمزيد من المعلومات، يُرجى الاطّلاع على PlaceAutocompleteMatchedSubstring.
`structured_formatting`	مطلوب	PlaceAutocompleteStructuredFormat	توفّر هذه السمة نصًا منسّقًا مسبقًا يمكن عرضه في نتائج الإكمال التلقائي. يجب قراءة هذا المحتوى كما هو، ويُرجى عدم تحليل العنوان المنسّق آليًا. لمزيد من المعلومات، يُرجى الاطّلاع على PlaceAutocompleteStructuredFormat.
`terms`	مطلوب	Array<PlaceAutocompleteTerm>	يحتوي على مصفوفة من المصطلحات التي تحدّد كل قسم من الوصف الذي تم عرضه (عادةً ما ينتهي قسم الوصف بفاصلة). يحتوي كل إدخال في المصفوفة على حقل `value` يتضمّن نص المصطلح، وحقل `offset` يحدّد موضع بدء هذا المصطلح في الوصف، ويتم قياسه بأحرف Unicode. لمزيد من المعلومات، يُرجى الاطّلاع على PlaceAutocompleteTerm.
`distance_meters`	اختياري	عدد صحيح	المسافة المستقيمة بالمتر من نقطة الانطلاق لا يتم عرض هذا الحقل إلا للطلبات التي يتم إجراؤها باستخدام `origin`.
`place_id`	اختياري	سلسلة	معرّف نصي يحدّد مكانًا بشكل فريد. لاسترداد معلومات حول المكان، مرِّر هذا المعرّف في الحقل placeId ضمن طلب بيانات من واجهة برمجة التطبيقات Places API. لمزيد من المعلومات حول معرّفات الأماكن، راجِع النظرة العامة حول معرّفات الأماكن.
`reference`	اختياري	سلسلة	تم إيقاف `reference` نهائيًا. راجِع place_id.
`types`	اختياري	Array<string>	تحتوي على مصفوفة من الأنواع التي تنطبق على هذا المكان. على سبيل المثال: `[ "political", "locality" ]` أو `[ "establishment", "geocode", "beauty_salon" ]`. يمكن أن تحتوي المصفوفة على قيم متعدّدة. مزيد من المعلومات حول أنواع الأماكن

PlaceAutocompleteMatchedSubstring

الحقل	مطلوب	النوع	الوصف
`length`	مطلوب	الرقم	طول السلسلة الفرعية المطابقة في نص نتيجة التوقّع
`offset`	مطلوب	الرقم	تمثّل هذه السمة الموقع الجغرافي لبداية السلسلة الفرعية المطابقة في نص نتيجة التوقّع.

PlaceAutocompleteStructuredFormat

الحقل	مطلوب	النوع	الوصف
`main_text`	مطلوب	سلسلة	يحتوي على النص الرئيسي لتوقّع، وهو عادةً اسم المكان.
`main_text_matched_substrings`	مطلوب	Array<PlaceAutocompleteMatchedSubstring>	يحتوي على مصفوفة تتضمّن القيمة `offset` و`length`. تصف هذه السمة موضع الكلمة التي تم إدخالها في نص نتيجة التوقّع، حتى يمكن تمييز الكلمة إذا تم اختيارها. لمزيد من المعلومات، يُرجى الاطّلاع على PlaceAutocompleteMatchedSubstring.
`secondary_text`	اختياري	سلسلة	تحتوي هذه السمة على النص الثانوي الخاص بنتيجة البحث المتوقّعة، والذي يمثّل عادةً الموقع الجغرافي للمكان.
`secondary_text_matched_substrings`	اختياري	Array<PlaceAutocompleteMatchedSubstring>	يحتوي على مصفوفة تتضمّن القيمة `offset` و`length`. تصف هذه السمة موضع الكلمة التي تم إدخالها في نص نتيجة التوقّع، حتى يمكن تمييز الكلمة إذا تم اختيارها. لمزيد من المعلومات، يُرجى الاطّلاع على PlaceAutocompleteMatchedSubstring.

PlaceAutocompleteTerm

الحقل	مطلوب	النوع	الوصف
`offset`	مطلوب	الرقم	تحدّد هذه السمة موضع بدء المصطلح في الوصف، ويتم قياسه بأحرف Unicode.
`value`	مطلوب	سلسلة	تمثّل هذه السمة نص المصطلح.

تحسين خدمة "الإكمال التلقائي للأماكن" (الإصدار القديم)

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

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

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

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

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

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

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

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

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

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

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

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

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

تنفيذ الأداة
تتضمّن الأدوات 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، وذلك من خلال إضافة المَعلمة strictbounds. يوجّه هذا الإعداد خدمة الإكمال التلقائي للأماكن (الإصدار القديم) لعرض نتائج فقط ضمن تلك المنطقة.

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

طلبات الإكمال التلقائي للأماكن (الإصدار القديم)

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

إدخال

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

المكوّنات

language

الموقع

locationbias

locationrestriction

offset

الأصل

نطاق جغرافي

المنطقة

sessiontoken

strictbounds

الأنواع

أمثلة على خدمة "الإكمال التلقائي للأماكن" (الإصدار القديم)

عنوان URL

curl

عنوان URL

curl

عنوان URL

curl

عنوان URL

curl

استجابة خدمة "الإكمال التلقائي للأماكن" (الإصدار القديم)

عنوان URL

curl

JSON

XML

PlacesAutocompleteResponse

predictions

status

error_message

info_messages

PlacesAutocompleteStatus

PlaceAutocompletePrediction

description

matched_substrings

structured_formatting

terms

distance_meters

place_id

reference

types

PlaceAutocompleteMatchedSubstring

length

offset

PlaceAutocompleteStructuredFormat

main_text

main_text_matched_substrings

secondary_text

secondary_text_matched_substrings

PlaceAutocompleteTerm

offset

value

تحسين خدمة "الإكمال التلقائي للأماكن" (الإصدار القديم)

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

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

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

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

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

نعم

لا

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

انحياز الموقع الجغرافي

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

ميزة "الإكمال التلقائي للأماكن" (الإصدار القديم)

`predictions`

`status`

`error_message`

`info_messages`

`description`

`matched_substrings`

`structured_formatting`

`terms`

`distance_meters`

`place_id`

`reference`

`types`

`length`

`offset`

`main_text`

`main_text_matched_substrings`

`secondary_text`

`secondary_text_matched_substrings`

`offset`

`value`