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
}
الحقول
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. يتم إرجاع المكان فقط إذا تم تضمين نوعه الأساسي في هذه القائمة. ويمكن تحديد ما يصل إلى 5 قيم. وإذا لم يتم تحديد أي أنواع، يتم عرض جميع أنواع الأماكن.
includedRegionCodes[]

string

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

string

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

string

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

object (LatLng)

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

integer

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

إذا كانت الصفحة فارغة، سيتم ضبط طول input تلقائيًا.
includeQueryPredictions

boolean

اختياريّ. إذا كانت الإجابة "صحيح"، سيشمل الردّ توقّعات البحث عن المكان وطلب البحث. وإلا لن تعرض الاستجابة إلا تنبؤات المكان.
sessionToken

string

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

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

نوصي بالإرشادات التالية:

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

نص الاستجابة

نموذج الاستجابة لـ places.complete.

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

تمثيل 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 إذا تم تحديد المطابقة بالاستناد إلى معايير أخرى غير مطابقة السلسلة (مثل التصحيحات الإملائية أو عمليات التحويل الصوتي).

هذه القيم هي إزاحة أحرف يونيكود لـ 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 أو العكس.