- طلب HTTP
- نص الطلب
- نص الاستجابة
- LocationBias
- LocationRestriction
- اقتراح
- PlacePrediction
- FormattableText
- StringRange
- StructuredFormat
- QueryPrediction
تعرض توقعات للمدخل المحدد.
طلب HTTP
POST https://places.googleapis.com/v1/places:autocomplete
يستخدم عنوان URL بنية تحويل الترميز gRPC.
نص الطلب
يحتوي نص الطلب على بيانات بالبنية التالية:
تمثيل JSON |
---|
{ "input": string, "locationBias": { object ( |
الحقول | |
---|---|
input |
مطلوبة. السلسلة النصية المطلوب البحث عليها. |
locationBias |
اختياريّ. تحيز النتائج إلى موقع محدد. يجب ضبط سمة واحدة على الأكثر من |
locationRestriction |
اختياريّ. حصر النتائج في موقع جغرافي محدّد يجب ضبط سمة واحدة على الأكثر من |
includedPrimaryTypes[] |
اختياريّ. تم تضمين نوع "المكان" الأساسي (على سبيل المثال، "مطعم" أو "محطة وقود") من https://developers.google.com/maps/documentation/places/web-service/place-types. يتم إرجاع المكان فقط إذا تم تضمين نوعه الأساسي في هذه القائمة. ويمكن تحديد ما يصل إلى 5 قيم. وإذا لم يتم تحديد أي أنواع، يتم عرض جميع أنواع الأماكن. |
includedRegionCodes[] |
اختياريّ. يمكنك تضمين النتائج في المناطق المحددة فقط، وهي عبارة عن رمز مناطق مؤلفة من حرفين من حرفين من CLDR كحد أقصى. ولن تؤدي المجموعة الفارغة إلى تقييد النتائج. إذا تم ضبط كل من |
languageCode |
اختياريّ. اللغة التي سيتم عرض النتائج بها. يتم ضبط الإعدادات التلقائية على en-US. قد تكون النتائج بلغات مختلطة إذا كانت اللغة المستخدَمة في |
regionCode |
اختياريّ. رمز المنطقة، محدّد كرمز منطقة مؤلف من حرفين CLDR. ويؤثر ذلك في تنسيق العنوان وترتيب النتائج وقد يؤثر في النتائج التي يتم عرضها. ولا يؤدي ذلك إلى حصر النتائج بالمنطقة المحدّدة. لحصر النتائج بمنطقة معيّنة، استخدِم السمة |
origin |
اختياريّ. نقطة الأصل المطلوب منها حساب المسافة الجيوديسية إلى الوجهة (يتم عرضها بالشكل |
inputOffset |
اختياريّ. إزاحة أحرف يونيكود المستندة إلى صفر لـ إذا كانت الصفحة فارغة، سيتم ضبط طول |
includeQueryPredictions |
اختياريّ. إذا كانت الإجابة "صحيح"، سيشمل الردّ توقّعات البحث عن المكان وطلب البحث. وإلا لن تعرض الاستجابة إلا تنبؤات المكان. |
sessionToken |
اختياريّ. سلسلة تحدِّد جلسة إكمال تلقائي لأغراض الفوترة. يجب أن تكون السلسلة آمنة من سلسلة base64 لعنوان URL ولها 36 حرف ASCII كحد أقصى. وفي حال عدم تنفيذ ذلك، يتم عرض خطأ POINTS_Quick. تبدأ الجلسة عندما يبدأ المستخدم في كتابة طلب بحث، وتنتهي عند اختيار مكان وإجراء مكالمة إلى "تفاصيل المكان" أو "التحقّق من صحة العنوان". ويمكن أن تحتوي كل جلسة على طلبات بحث متعددة، متبوعة بطلب واحد من أجل التحقّق من صحة تفاصيل المكان أو العنوان. يجب أن تنتمي بيانات الاعتماد المستخدَمة لكل طلب خلال جلسة إلى المشروع نفسه على Google Cloud Console. بعد انتهاء الجلسة، لن يصبح الرمز المميز صالحًا، لذا يجب أن ينشئ تطبيقك رمزًا مميزًا جديدًا لكل جلسة. إذا تم حذف مَعلمة نوصي بالإرشادات التالية:
|
نص الاستجابة
نموذج الاستجابة لـ places.complete.
إذا كانت الاستجابة ناجحة، سيحتوي نص الاستجابة على بيانات بالبنية التالية:
تمثيل JSON |
---|
{
"suggestions": [
{
object ( |
الحقول | |
---|---|
suggestions[] |
تحتوي على قائمة بالاقتراحات، مرتبة بترتيب تنازلي حسب مدى الصلة بالموضوع. |
LocationBias
المنطقة المراد البحث فيها. قد تكون النتائج منحازة حول المنطقة المحددة.
تمثيل JSON |
---|
{ // Union field |
الحقول | |
---|---|
حقل الاتحاد يمكن أن يكون الحقل " |
|
rectangle |
إطار عرض يتم تحديده من خلال زاوية شمالية شرقية وأخرى جنوبية غربية. |
circle |
دائرة محددة بواسطة نقطة مركزية ونصف قطر. |
LocationRestriction
المنطقة المراد البحث فيها. ستقتصر النتائج على المنطقة المحدّدة.
تمثيل JSON |
---|
{ // Union field |
الحقول | |
---|---|
حقل الاتحاد يمكن أن يكون الحقل " |
|
rectangle |
إطار عرض يتم تحديده من خلال زاوية شمالية شرقية وأخرى جنوبية غربية. |
circle |
دائرة محددة بواسطة نقطة مركزية ونصف قطر. |
الاقتراح
نتيجة لاقتراح إكمال تلقائي
تمثيل JSON |
---|
{ // Union field |
الحقول | |
---|---|
حقل الاتحاد يمكن أن يكون الحقل " |
|
placePrediction |
توقع لمكان. |
queryPrediction |
توقع لطلب بحث. |
PlacePrediction
نتائج التوقّع لتوقّع إكمال تلقائي لمكان
تمثيل JSON |
---|
{ "place": string, "placeId": string, "text": { object ( |
الحقول | |
---|---|
place |
اسم المورد للمكان المقترَح. ويمكن استخدام هذا الاسم في واجهات برمجة التطبيقات الأخرى التي تقبل أسماء الأماكن. |
placeId |
المعرّف الفريد للمكان المقترَح. ويمكن استخدام هذا المعرّف في واجهات برمجة التطبيقات الأخرى التي تقبل أرقام تعريف الأماكن. |
text |
تحتوي على اسم يمكن لشخص عادي قراءته للنتيجة التي يتم عرضها. بالنسبة إلى نتائج المؤسسة، عادةً ما يكون ذلك هو اسم النشاط التجاري وعنوانه. يُنصح باستخدام قد يكون هذا النص مختلفًا عن وقد تظهر بلغات مختلطة إذا كان الطلبان |
structuredFormat |
تحليل تنبؤي بالمكان إلى نص رئيسي يحتوي على اسم المكان ونص ثانوي يحتوي على عناصر إضافية مميزة (مثل مدينة أو منطقة). يُنصَح باستخدام |
types[] |
قائمة بالأنواع التي تنطبق على هذا المكان من الجدول "أ" أو الجدول "ب" في https://developers.google.com/maps/documentation/places/web-service/place-types. النوع هو تصنيف للمكان. تشترك الأماكن ذات الأنواع المشتركة في خصائص متشابهة. |
distanceMeters |
طول الموقع الجيوديسي بالمتر من |
FormattableText
نص يمثّل عبارة عن مكان أو تنبؤ بطلب بحث. يمكن استخدام النص كما هو أو بتنسيق.
تمثيل JSON |
---|
{
"text": string,
"matches": [
{
object ( |
الحقول | |
---|---|
text |
النص الذي يمكن استخدامه على النحو أو بالتنسيق |
matches[] |
قائمة بنطاقات السلاسل التي تحدد موضع مطابقة طلب الإدخال في هذه القيم هي إزاحة أحرف يونيكود لـ |
StringRange
تحدد سلسلة فرعية ضمن نص معين.
تمثيل JSON |
---|
{ "startOffset": integer, "endOffset": integer } |
الحقول | |
---|---|
startOffset |
إزاحة صفرية لحرف Unicode الأول في السلسلة (شاملة). |
endOffset |
إزاحة صفرية لآخر حرف Unicode (حصري). |
StructuredFormat
يحتوي على تقسيم لمكان أو توقع طلب بحث إلى نص رئيسي ونص ثانوي.
بالنسبة إلى توقعات المكان، يحتوي النص الرئيسي على الاسم المحدد للمكان. بالنسبة إلى عبارات البحث المقترحة، يحتوي النص الرئيسي على طلب البحث.
يحتوي النص الثانوي على عناصر إضافية واضحة (مثل مدينة أو منطقة) لتحديد المكان أو تحسين طلب البحث بشكل أكبر.
تمثيل JSON |
---|
{ "mainText": { object ( |
الحقول | |
---|---|
mainText |
تمثل اسم المكان أو طلب البحث. |
secondaryText |
تمثّل عناصر إضافية واضحة (مثل مدينة أو منطقة) لتحديد المكان أو تحسين طلب البحث بشكل أكبر. |
QueryPrediction
نتائج التوقّع لتوقّع إكمال تلقائي لطلب البحث
تمثيل JSON |
---|
{ "text": { object ( |
الحقول | |
---|---|
text |
النص المتنبأ به. لا يمثل هذا النص مكانًا، بل استعلامًا نصيًا يمكن استخدامه في نقطة نهاية البحث (على سبيل المثال، "البحث النصي"). يُنصح باستخدام قد يتم استخدام لغات مختلطة إذا كان الطلبان |
structuredFormat |
تحليل تنبؤ طلب البحث إلى نص رئيسي يتضمن طلب البحث والنص الثانوي الذي يحتوي على ميزات إضافية واضحة (مثل مدينة أو منطقة). يُنصَح باستخدام |