Method: places.autocomplete

لعرض توقّعات للمدخلات المحدّدة

طلب HTTP

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

يستخدِم عنوان URL بنية تحويل ترميز gRPC.

نص الطلب

يحتوي نص الطلب على بيانات بالبنية التالية:

تمثيل JSON
{
  "input": string,
  "locationBias": {
    object (LocationBias)
  },
  "locationRestriction": {
    object (LocationRestriction)
  },
  "includedPrimaryTypes": [
    string
  ],
  "includedRegionCodes": [
    string
  ],
  "languageCode": string,
  "regionCode": string,
  "origin": {
    object (LatLng)
  },
  "inputOffset": integer,
  "includeQueryPredictions": boolean,
  "sessionToken": string,
  "includePureServiceAreaBusinesses": boolean
}
الحقول
input

string

مطلوب. سلسلة النصوص المطلوب البحث فيها.

locationBias

object (LocationBias)

اختياريّ. توجيه النتائج نحو موقع جغرافي محدّد

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

locationRestriction

object (LocationRestriction)

اختياريّ. حصر النتائج بموقع جغرافي محدّد

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

includedPrimaryTypes[]

string

اختياريّ. نوع المكان الأساسي المُدرَج (مثل "مطعم" أو "محطة_غاز") في أنواع الأماكن (https://developers.google.com/maps/documentation/places/web-service/place-types)، أو (regions) فقط، أو (cities) فقط لا يتم عرض مكان إلا إذا كان نوعه الأساسي مضمّنًا في هذه القائمة. يمكن تحديد ما يصل إلى 5 قيم. في حال عدم تحديد أي أنواع، يتم عرض جميع أنواع الأماكن.

includedRegionCodes[]

string

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

languageCode

string

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

regionCode

string

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

origin

object (LatLng)

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

inputOffset

integer

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

إذا كان الحقل فارغًا، يتم ضبط الطول تلقائيًا على input.

includeQueryPredictions

boolean

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

sessionToken

string

اختياريّ. سلسلة تحدد جلسة الإكمال التلقائي لأغراض الفوترة. يجب أن تكون سلسلة base64 آمنة لعنوان URL واسم الملف، ويجب ألا يزيد طولها عن 36 حرفًا ASCII. وخلاف ذلك، سيتم عرض خطأ ضياء_فياكن.

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

ننصحك باتّباع الإرشادات التالية:

  • استخدِم الرموز المميّزة للجلسة في جميع طلبات ميزة "إكمال الأماكن تلقائيًا".
  • أنشئ رمزًا مميزًا جديدًا لكل جلسة. ننصح باستخدام الإصدار 4 من معرّف UUID.
  • تأكَّد من أنّ بيانات الاعتماد المستخدمة لجميع طلبات الإكمال التلقائي للمكان و"تفاصيل المكان" و"التحقق من العنوان" ضمن جلسة تنتمي إلى المشروع نفسه على Cloud Console.
  • احرص على تمرير رمز مميّز للجلسة لكل جلسة جديدة. سيؤدي استخدام الرمز المميّز نفسه لأكثر من جلسة واحدة إلى تحصيل رسوم كل طلب على حدة.
includePureServiceAreaBusinesses

boolean

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

نص الاستجابة

نموذج استجابة لـ places.الإكمال التلقائي.

إذا كانت الاستجابة ناجحة، سيحتوي نص الاستجابة على بيانات بالبنية التالية:

تمثيل JSON
{
  "suggestions": [
    {
      object (Suggestion)
    }
  ]
}
الحقول
suggestions[]

object (Suggestion)

يحتوي على قائمة بالاقتراحات، ويتم ترتيبها تنازليًا حسب مدى صلة كل اقتراح بالبحث.

LocationBias

المنطقة التي تريد البحث فيها. قد تكون النتائج متحيّزة في المنطقة المحدّدة.

تمثيل JSON
{

  // Union field type can be only one of the following:
  "rectangle": {
    object (Viewport)
  },
  "circle": {
    object (Circle)
  }
  // End of list of possible types for union field type.
}
الحقول

حقل الاتحاد type.

يمكن أن يكون type واحدًا فقط مما يلي:

rectangle

object (Viewport)

إطار عرض محدّد من خلال زاوية شمال شرقية وجنوب غربية

circle

object (Circle)

دائرة محدّدة بنقطة مركزية ونصف قطر

LocationRestriction

المنطقة التي تريد البحث فيها. ستقتصر النتائج على المنطقة المحدّدة.

تمثيل JSON
{

  // Union field type can be only one of the following:
  "rectangle": {
    object (Viewport)
  },
  "circle": {
    object (Circle)
  }
  // End of list of possible types for union field type.
}
الحقول

حقل الاتحاد type.

يمكن أن يكون type واحدًا فقط مما يلي:

rectangle

object (Viewport)

إطار عرض محدّد من خلال زاوية شمال شرقية وجنوب غربية

circle

object (Circle)

دائرة محددة بنقطة مركزية ونصف قطر.

اقتراح

نتيجة اقتراح للإكمال التلقائي

تمثيل JSON
{

  // Union field kind can be only one of the following:
  "placePrediction": {
    object (PlacePrediction)
  },
  "queryPrediction": {
    object (QueryPrediction)
  }
  // End of list of possible types for union field kind.
}
الحقول

حقل الربط kind

يمكن أن يكون kind واحدًا فقط مما يلي:

placePrediction

object (PlacePrediction)

توقّع لمكان

queryPrediction

object (QueryPrediction)

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

PlacePrediction

نتائج التوقّعات لعبارة بحث مقترَحة في ميزة "الإكمال التلقائي" للأماكن

تمثيل JSON
{
  "place": string,
  "placeId": string,
  "text": {
    object (FormattableText)
  },
  "structuredFormat": {
    object (StructuredFormat)
  },
  "types": [
    string
  ],
  "distanceMeters": integer
}
الحقول
place

string

اسم المورد للمكان المقترَح يمكن استخدام هذا الاسم في واجهات برمجة التطبيقات الأخرى التي تقبل أسماء الأماكن.

placeId

string

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

text

object (FormattableText)

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

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

قد يختلف هذا النص عن قيمة displayName التي تعرضها الأماكن.get.

قد تكون بلغات مختلطة إذا كان الطلب input وlanguageCode بلغات مختلفة أو إذا لم يكن لدى "المكان" ترجمة من اللغة المحلية إلى languageCode.

structuredFormat

object (StructuredFormat)

تقسيم توقّعات الأماكن إلى نص رئيسي يحتوي على اسم المكان ونص ثانوي يحتوي على ميزات إضافية لإزالة الالتباس (مثل مدينة أو منطقة)

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

types[]

string

قائمة الأنواع التي تنطبق على هذا المكان من الجدول "أ" أو الجدول "ب" في https://developers.google.com/maps/documentation/places/web-service/place-types

النوع هو تصنيف لمكان معيّن. ستتشارك الأماكن ذات الأنواع المشتركة سمات مشابهة.

distanceMeters

integer

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

FormattableText

نص يمثّل مكانًا أو اقتراحًا لطلب بحث يمكن استخدام النص كما هو أو منسَّق.

تمثيل JSON
{
  "text": string,
  "matches": [
    {
      object (StringRange)
    }
  ]
}
الحقول
text

string

نص يمكن استخدامه كما هو أو تنسيقه باستخدام matches

matches[]

object (StringRange)

قائمة بنطاقات السلاسل التي تحدّد مكان مطابقة طلب الإدخال في text يمكن استخدام النطاقات لتنسيق أجزاء معيّنة من text. وقد لا تكون السلاسل الفرعية مطابقة تمامًا لـ input إذا تم تحديد المطابقة من خلال معايير أخرى غير مطابقة السلاسل (مثل التصحيحات الإملائية أو عمليات التحويل الصوتي).

هذه القيم هي Offsets لحرف Unicode‏ text. نضمن ترتيب النطاقات بقيم الإزاحة المتزايدة.

StringRange

لتحديد سلسلة فرعية ضمن نص معيّن

تمثيل JSON
{
  "startOffset": integer,
  "endOffset": integer
}
الحقول
startOffset

integer

القيمة المحورية المستندة إلى الصفر لحرف Unicode الأول في السلسلة (شاملة)

endOffset

integer

القيمة المضافة إلى آخر حرف Unicode (غير شاملة) وتكون مستندة إلى الصفر

StructuredFormat

يحتوي على تفاصيل عن مكان أو توقّعات الاستعلامات في نص رئيسي ونص ثانوي.

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

يحتوي النص الثانوي على ميزات إضافية لإزالة الالتباس (مثل مدينة أو منطقة) لتحديد المكان بشكل أفضل أو تحسين الطلب.

تمثيل JSON
{
  "mainText": {
    object (FormattableText)
  },
  "secondaryText": {
    object (FormattableText)
  }
}
الحقول
mainText

object (FormattableText)

يمثل اسم المكان أو طلب البحث.

secondaryText

object (FormattableText)

يمثّل ميزات إضافية لإزالة الالتباس (مثل مدينة أو منطقة) لتحديد المكان بشكل أفضل أو تحسين الطلب.

QueryPrediction

نتائج التوقّع الخاصة بتوقّعات الإكمال التلقائي لطلب البحث

تمثيل JSON
{
  "text": {
    object (FormattableText)
  },
  "structuredFormat": {
    object (StructuredFormat)
  }
}
الحقول
text

object (FormattableText)

النص المتوقّع لا يمثّل هذا النص مكانًا، بل هو طلب بحث نصي يمكن استخدامه في نقطة نهاية بحث (مثل "البحث النصي").

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

قد يكون المحتوى بلغات مختلطة إذا كان الطلبان input وlanguageCode بلغَين مختلفَين أو إذا لم تتم ترجمة جزء من طلب البحث من اللغة المحلية إلى languageCode.

structuredFormat

object (StructuredFormat)

تقسيم توقّعات طلب البحث إلى نص رئيسي يحتوي على طلب البحث ونص ثانوي يحتوي على ميزات إضافية لإزالة الالتباس (مثل مدينة أو منطقة)

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