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

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

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

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

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

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

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

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

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

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

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

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

المنطقة

رمز المنطقة، ويتم تحديده كقيمة مكوّنة من حرفَين لنطاق المستوى الأعلى الذي يتم ترميزه حسب البلد (ccTLD). تتطابق معظم رموز نطاقات المستوى الأعلى لرمز البلد (ccTLD) مع رموز المنظمة الدولية للمعايير (ISO) 3166-1، مع بعض الاستثناءات الملحوظة. على سبيل المثال، نطاق مستوى أعلى يتم ترميزه حسب البلد (ccTLD) في المملكة المتحدة هو "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`	مطلوب	Array<PlaceAutocompletePrediction>	يحتوي على مصفوفة من عبارات البحث المقترَحة. يمكنك الاطّلاع على PlaceAutocompletePrediction لمزيد من المعلومات.
`status`	مطلوب	PlacesAutocompleteStatus	يحتوي على حالة الطلب، وقد يحتوي على معلومات تصحيح الأخطاء لمساعدتك في تتبُّع سبب تعذُّر الطلب. لمزيد من المعلومات، يُرجى الاطّلاع على PlacesAutocompleteStatus.
`error_message`	اختياري	سلسلة	عندما تعرض الخدمة رمز حالة غير `OK<`، قد يكون هناك حقل `error_message` إضافي ضمن عنصر الاستجابة. يحتوي هذا الحقل على معلومات أكثر تفصيلاً عن الأسباب وراء رمز الحالة المحدّد. لا يتم عرض هذا الحقل دائمًا، ومحتواه عرضة للتغيير.
`info_messages`	اختياري	Array<string>	عندما تعرض الخدمة معلومات إضافية حول مواصفات الطلب، قد يكون هناك حقل `info_messages` إضافي ضمن عنصر الاستجابة. لا يتم عرض هذا الحقل إلا للطلبات الناجحة. وقد لا يتم عرضه دائمًا، كما أنّ محتواه عرضة للتغيير.

Of particular interest within the results are the place_id elements, which can be used to request more specific details about the place using a separate query. يُرجى الاطّلاع على طلبات "تفاصيل المكان (الإصدار القديم)".

يتألف ردّ 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 تشير إلى حدوث خطأ غير معروف.

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

PlaceAutocompletePrediction

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

خدمة "الإكمال التلقائي للأماكن" (القديمة) لكل طلب مع Geocoding API

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

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

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

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

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

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

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

ننصحك بتأخير طلبات الإكمال التلقائي للأماكن (القديم)
يمكنك استخدام استراتيجيات مثل تأخير طلب الإكمال التلقائي للأماكن (القديم) إلى أن يكتب المستخدم الأحرف الثلاثة أو الأربعة الأولى لكي يُرسِل تطبيقك عددًا أقل من الطلبات. على سبيل المثال، إذا أرسلت طلبات بيانات من واجهة برمجة التطبيقات Place Autocomplete (Legacy) لكل حرف بعد أن يكتب المستخدم الحرف الثالث، يعني ذلك أنّه إذا كتب المستخدم سبعة أحرف ثم اختار عبارة بحث مقترَحة أرسلت لها طلبًا واحدًا من Geocoding API، ستكون التكلفة الإجمالية هي 4 طلبات من Place Autocomplete (Legacy) لكل طلب + 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

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

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

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

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

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

خدمة "الإكمال التلقائي للأماكن" (القديمة) لكل طلب مع Geocoding API

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

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

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

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

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

`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`