هذا المنتج في الحالة القديمة. اعتبارًا من أكتوبر 2026، لن يعود بإمكانك تفعيل Places API (الإصدار القديم) لمشاريع Google Cloud الجديدة. ستظل المشاريع الحالية متوافقة تمامًا. للاستفادة من الميزات الجديدة وتحسين الأداء، انتقِل إلى Places API (جديدة).

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

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

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

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

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

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

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

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

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

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

يجب تنسيق Plus Codes بشكل صحيح. وهذا يعني أنّه يجب استخدام الرمز %2B بدلاً من علامة الجمع في عنوان URL، واستخدام الرمز %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: قائمة رموز البلدان وفقًا لمعيار ISO 3166 أو منصة التصفّح على الإنترنت وفقًا لمعيار ISO.
language

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

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

عند استخدام Text Search API، قد يتم تجاهل المَعلمة `location` إذا كان `query` يحتوي على موقع جغرافي صريح، مثل `Market in Barcelona`.
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.
اقتطاع

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

ننصحك باتّباع الإرشادات التالية:
- استخدِم رموز الجلسات المميزة لجميع جلسات الإكمال التلقائي.
- إنشاء رمز مميّز جديد لكل جلسة ننصح باستخدام معرّف UUID من الإصدار 4.
- تأكَّد من أنّ مفاتيح واجهة برمجة التطبيقات المستخدَمة لجميع طلبات "الإكمال التلقائي للأماكن" و"تفاصيل المكان" ضمن جلسة معيّنة تنتمي إلى مشروع 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'

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

عنوان 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`	مطلوب	صفيف<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، اطّلِع على معالجة ملفات XML باستخدام XPath.

قد لا يتوفّر مكوّن العنوان street_number في ردود تفاصيل المكان (قديم) لأرقام تعريف الأماكن في بعض عبارات البحث المقترحة. يحدث ذلك عادةً عندما لا يمكن استيفاء العنوان الخاص بمكان. في هذه الحالات، ستتضمّن مصفوفة types الخاصة بالتوقّع القيمة "route". بالنسبة إلى عبارات البحث المقترَحة التي تتضمّن رقمًا في الوصف (تتم مطابقة طلب البحث الذي تم إدخاله)، يتضمّن الردّ من واجهة برمجة التطبيقات Place Details (الإصدار القديم) لمعرّف المكان رقم الشارع فقط إذا كانت مصفوفة 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`	مطلوب	الرقم	تحدّد موضع بدء هذه العبارة في الوصف، ويتم قياسها بأحرف يونيكود
`value`	مطلوب	سلسلة	تمثّل هذه السمة نص المصطلح.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

لا، يجب توفير العنوان والموقع الجغرافي فقط

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

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

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

نعم

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

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

لا

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

تنفيذ التطبيق المصغّر
تتضمّن التطبيقات المصغّرة 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

اقتطاع

الأصل

نطاق جغرافي

المنطقة

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`